Users can make calls to each other by using their own unique ID. Using the Calls API, you can manage each user’s actions regarding Sendbird Calls.
Note: Use Chat Platform API to perform user-related actions.
Resource representation
The following table shows the list of properties in a user resource.
Property name
Type
Description
user_id
string
The unique ID of the user.
nickname
string
The user's nickname.
profile_url
string
The URL of the user’s profile image.
access_token
string
An opaque string that identifies the user. It is recommended that every user has their own access token and provides it upon login for security.
session_tokens[]
list
A list of information of session tokens that identifies the user session and which have no validity after their own expiration time. Each of items consists of two session_token and expires_at properties. The session_token is an opaque string and expires_at is a validation period of the session token. It is recommended that a new session token is periodically issued to every user, and provided upon the user's login for security.
has_ever_logged_in
boolean
Indicates whether the user has ever logged into the application so far.
is_active
boolean
Indicates whether the user is currently active within the application.
is_online
boolean
Indicates whether the user is currently connected to Sendbird server.
discovery_keys[]
array
An array of unique keys of the user which is provided to Sendbird server for discovering friends. By using the keys, the server can identify and match the user with other users.
preferred_languages[]
array
An array of one or more language codes to translate notification messages to preferred languages. Up to 4 languages can be set for the user. If messages are sent in one of the preferred languages, notification messages won't be translated. If messages are sent in a language other than the preferred languages, notification messages will be translated into the first language in the array. In addition, the messages translated into other preferred languages will be provided in the sendbird property of a notification message payload.
created_at
long
The time that the user was created, in Unix seconds format.
last_seen_at
long
The time recorded when the user goes offline, to indicate when they were last online, in Unix milliseconds format. If the user is online, the value is set as 0.
metadata[]
array
An array of key-value items which store additional user information. For more information, see the User & channel metadata page.
Actions
API endpoints are relative to the base URL allocated to your application. In this page, the /users endpoint refers to https://api-{application_id}.calls.sendbird.com/v1/users.
Note: If you want to know your application ID, sign in to your dashboard, go to the Settings > Application > General, and then check the Application ID.
It's recommended that the parameter values in API URLs be urlencoded, such as {user_id}.
Specifies the value of the next property in the response to retrieve the next page in the result set.
limit
int
Specifies the number of results to return per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
user_ids
string
Searches for users who are using the user IDs in the specified value. The string should consist of multiple urlencoded user IDs separated by commas (for example, ?user_ids=urlencoded_id_1,urlencoded_id_2).
* We recommend you set the maximum number of the user IDs to 250. If exceeded, your request may receive an HTTP 414 error indicating that the request URL is longer than Sendbird server is willing to interpret.
?token=YXYWRFBTQlArEUBXWFNeF2p2FEFdUA~~&limit=3
Response
If successful, this action returns a list of user resources in the response body.
{
"users": [
{
"user_id": "Julia",
"nickname": "Yogini",
"profile_url": "https://sendbird.com/main/img/profiles/profile_94_512px.png",
"is_active": true,
"is_online": false, // Offline on Sendbird Chat platform. Not related to whether the user is on a call.
"created_at": 1540275265,
"last_seen_at": 1540245396131,
"has_ever_logged_in": true,
"metadata": {
"location": "Bali",
"marriage": "N"
}
},
{
"user_id": "Debbie",
"nickname": "Joe",
"profile_url": "https://sendbird.com/main/img/profiles/profile_145_512px.png"
"is_active": true,
"is_online": true, // Online on Sendbird Chat platform. Not related to whether the user is on a call.
"created_at": 1542153463,
"last_seen_at": 1542356433721,
"has_ever_logged_in": true,
"metadata": {
"location": "Seoul",
"marriage": "N"
}
},
{
"user_id": "Katherine",
"nickname": "Bambi",
"profile_url": "https://sendbird.com/main/img/profiles/profile_151_512px.png"
"is_active": true,
"is_online": true,
"created_at": 1552303401,
"last_seen_at": 1542356133981,
"has_ever_logged_in": true,
"metadata": {
"location": "Tokyo",
"marriage": "N"
}
}
],
"next": "YXEZR1VVQVErEUBXWFNeF2p3FkFVVA~~"
}
The value for the next parameter to retrieve the next page in the result set.
Note: In the response body, the is_online property of a user object indicates whether the user is online on Sendbird Chat platform, not on Sendbird Calls platform.
Retrieve a list of a user's calls
Retrieves all the calls that a specific user has made.
HTTP request
GET https://api-{application_id}.calls.sendbird.com/v1/users/{user_id}/calls
Parameters
The following table lists the parameters that this action supports.
Parameters
Required
Type
Description
user_id
string
Specifies the unique ID of the target user.
Optional
Type
Description
limit
int
Specifies the number of results to return per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
Specifies the value of the next property in the response to retrieve the next page in the result set.
type
string
Restricts the search scope to only retrieve calls of which type matches the specified value. Acceptable value is currently limited to direct only.
role
string
Restricts the search scope to only retrieve calls that the user's role matches the specified value. Acceptable values are limited to dc_caller and dc_callee.
start_ts
int
Restricts the search scope to only retrieve calls which have been started after the specified time in Unix seconds format.
end_ts
int
Restricts the search scope to only retrieve calls which have been ended before the specified time in Unix seconds format.
end_result
string
Specifies a comma-seperated string of one or more end results to only retrieve calls of which the end result that matches any of the specified values. Acceptable values are limited to no_answer, canceled, declined, completed, timed_out, connection_lost, and unknown.
Adds a registration or device token of a user for push notification service. Depending on which push service you are using, you can pass one of two values in the token_type parameter: apns_voip, or fcm_voip. With APNs, you can also add remote notification by passing the calls_apns_remote value. An FCM registration token and an APNs device token allow identification of each client app instance on each device and are generated and registered by Android and iOS apps through the corresponding SDKs. Use this method if you need to register a token via your own server.
Note: For APNs, VoIP push tokens should be registered to receive incoming calls.
HTTP request
POST https://api-{application_id}.calls.sendbird.com/v1/users/{user_id}/push/{token_type}
Parameters
The following table lists the parameters that this action supports.
Required
Parameter name
Type
Description
user_id
string
Specifies the unique ID of the user to delete.
token_type
string
Specifies the type of the push token. Acceptable values are apns_voip, fcm_voip, and calls_apns_remote.
token
string
Specifies the value of the push token to add to Sendbird server.
Response
If successful, this action returns a user resource and the added push token in the response body.