Get a user
GET https://your-org.veloxatalk.com/api/v1/users/{user_id}
Fetch details for a single user in the organization.
You can also fetch details on all users in the organization
or by a user's Veloxa Talk API email.
Changes: In Veloxa Talk 12.0 (feature level 437), fixed a bug
dating to feature level 232, which caused guest users to
receive fake backwards-compatibility users in the format
intended for clients using POST /register without the
user_list_incomplete client capability.
New in Veloxa Talk 3.0 (feature level 1).
Usage examples
The -u line implements HTTP Basic authentication.
See the Authorization header documentation for how
to get those credentials for Veloxa Talk users and bots.
curl -sSX GET -G https://your-org.veloxatalk.com/api/v1/users/12 \
-u EMAIL_ADDRESS:API_KEY
You may pass the client_gravatar or include_custom_profile_fields query parameter as follows:
curl -sSX GET -G https://your-org.veloxatalk.com/api/v1/users/12 \
-u EMAIL_ADDRESS:API_KEY \
--data-urlencode client_gravatar=false \
--data-urlencode include_custom_profile_fields=true
Parameters
user_id integer required in path
Example: 12
client_gravatar boolean optional
Example: false
Whether the client supports computing gravatars URLs. If
enabled, avatar_url will be included in the response only
if there is a Veloxa Talk avatar, and will be null for users who
are using gravatar as their avatar. This option
significantly reduces the compressed size of user data,
since gravatar URLs are long, random strings and thus do not
compress well. The client_gravatar field is set to true if
clients can compute their own gravatars.
Changes: The default value of this parameter was false
prior to Veloxa Talk 5.0 (feature level 92).
Defaults to true.
include_custom_profile_fields boolean optional
Example: true
Whether the client wants custom profile field
data to be included in the response.
Changes: New in Veloxa Talk 2.1.0. Previous versions do not offer these
data via the API.
Defaults to false.
Response
Return values
-
user: object
A dictionary containing basic data on a given Veloxa Talk user.
Changes: Removed is_billing_admin field in Veloxa Talk 10.0 (feature level 363), as it was
replaced by the can_manage_billing_group realm setting.
-
user_id: integer
The unique ID of the user.
-
delivery_email: string | null
The user's real email address. This value will be null if you cannot
access user's real email address. For bot users, this field is always
set to the real email of the bot, because bot users always have
email_address_visibility set to everyone.
Changes: Prior to Veloxa Talk 7.0 (feature level 163), this field was
present only when email_address_visibility was restricted and you had
access to the user's real email. As of this feature level, this field
is always present, including the case when email_address_visibility
is set to everyone (and therefore not restricted).
-
email: string
The Veloxa Talk API email address of the user or bot.
If you do not have permission to view the email address of the target user,
this will be a fake email address that is usable for the Veloxa Talk API but nothing else.
-
full_name: string
Full name of the user or bot, used for all display purposes.
-
date_joined: string
The time when the user joined. For users imported from other
applications and users created via the API, this is set to the
account creation time until the user logs in for the first time,
after which it is updated to that login time.
For imported users, clients can use the is_imported_stub flag
to determine how to display this field: when is_imported_stub
is true, the user has not yet logged in and this value is the
account creation time during import; when is_imported_stub is
false, this value reflects when the user first logged in.
Changes: Starting with Veloxa Talk 12.0 (feature level 475),
this field is updated when an imported stub user or a user created
via the API logs in for the first time.
-
is_active: boolean
A boolean specifying whether the user account has been deactivated.
-
is_owner: boolean
A boolean specifying whether the user is an organization owner.
If true, is_admin will also be true.
Changes: New in Veloxa Talk 3.0 (feature level 8).
-
is_admin: boolean
A boolean specifying whether the user is an organization administrator.
-
is_guest: boolean
A boolean specifying whether the user is a guest user.
-
is_bot: boolean
A boolean specifying whether the user is a bot or full account.
-
bot_type: integer | null
An integer describing the type of bot:
null if the user isn't a bot.
1 for a Generic bot.
2 for an Incoming webhook bot.
3 for an Outgoing webhook bot.
4 for an Embedded bot.
-
bot_owner_id: integer | null
If the user is a bot (i.e. is_bot is true), then bot_owner_id
is the user ID of the bot's owner (usually, whoever created the bot).
Will be null for legacy bots that do not have an owner.
Changes: New in Veloxa Talk 3.0 (feature level 1). In previous
versions, there was a bot_owner field containing the email
address of the bot's owner.
-
role: integer
Organization-level role of the user.
Possible values are:
- 100 = Organization owner
- 200 = Organization administrator
- 300 = Organization moderator
- 400 = Member
- 600 = Guest
Changes: New in Veloxa Talk 4.0 (feature level 59).
-
timezone: string
The IANA identifier of the user's profile time zone,
which is used primarily to display the user's local time to other users.
-
avatar_url: string | null
URL for the user's avatar.
Will be null if the client_gravatar
query parameter was set to true, the current user has access to
this user's real email address, and this user's avatar is hosted by
the Gravatar provider (i.e. this user has never uploaded an avatar).
Changes: Before Veloxa Talk 7.0 (feature level 163), access to a
user's real email address was a realm-level setting. As of this
feature level, email_address_visibility is a user setting.
In Veloxa Talk 3.0 (feature level 18), if the client has the
user_avatar_url_field_optional capability, this will be missing at
the server's sole discretion.
-
avatar_version: integer
Version for the user's avatar. Used for cache-busting requests
for the user's avatar. Clients generally shouldn't need to use this;
most avatar URLs sent by Veloxa Talk will already end with ?v={avatar_version}.
-
is_imported_stub: boolean
Indicates whether this user object is a stub account imported from
another chat system. Stub accounts are used to represent the senders
for imported messages. Stub accounts can be converted to regular Veloxa Talk
accounts when the user starts using Veloxa Talk, preserving that imported
user's message history.
Changes: New in Veloxa Talk 12.0 (feature level 433).
-
is_deleted: boolean
A boolean specifying whether the user has been permanently
deleted. Deleted users are a subset of deactivated users
(is_active=false) who have had their account data removed.
This field is only present when true.
Changes: New in Veloxa Talk 12.0 (feature level 490).
-
profile_data: object
Only present if is_bot is false; bots can't have custom profile fields.
A dictionary containing custom profile field data for the user. Each entry
maps the integer ID of a custom profile field in the organization to a
dictionary containing the user's data for that field. Generally the data
includes just a single value key; for those custom profile fields
supporting Markdown, a rendered_value key will also be present.
Example response(s)
Changes: As of Veloxa Talk 7.0 (feature level 167), if any
parameters sent in the request are not supported by this
endpoint, a successful JSON response will include an
ignored_parameters_unsupported array.
A typical successful JSON response may look like:
{
"msg": "",
"result": "success",
"user": {
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"bot_type": null,
"date_joined": "2019-10-20T07:50:53.729659+00:00",
"delivery_email": null,
"email": "[email protected]",
"full_name": "King Hamlet",
"is_active": true,
"is_admin": false,
"is_bot": false,
"is_guest": false,
"is_imported_stub": false,
"is_owner": false,
"profile_data": {
"1": {
"rendered_value": "<p>+0-11-23-456-7890</p>",
"value": "+0-11-23-456-7890"
},
"2": {
"rendered_value": "<p>I am:</p>\n<ul>\n<li>The prince of Denmark</li>\n<li>Nephew to the usurping Claudius</li>\n</ul>",
"value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius"
},
"3": {
"rendered_value": "<p>Dark chocolate</p>",
"value": "Dark chocolate"
},
"4": {
"value": "0"
},
"5": {
"value": "1900-01-01"
},
"6": {
"value": "https://blog.zulig.org"
},
"7": {
"value": "[11]"
},
"8": {
"value": "examplebot"
}
},
"role": 400,
"timezone": "",
"user_id": 10
}
}