Calls Platform API v1

Calls Platform API

Version 1

User

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 metadata and 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}.

List of actions

Action	HTTP request
List users for Calls	`GET` /users Retrieves a list of Calls users in your Sendbird application. You can query the list using various parameters.
Retrieve a list of a user's calls	`GET` /users/{user_id}/calls Retrieves all the calls that a specific user has made.
Retrieve a user's call summary	`GET` /users/{user_id}/call_summary Retrieves the call summary of a specific user.
Retrieve a list of a user's push tokens	`GET` /users/{user_id}/push/{token_type} Retrieves a specific user’s push tokens.
Add a registration or device token	`POST` /users/{user_id}/push/{token_type} Adds a registration or device token of a user for push notification service.
Remove a user's push token	`DELETE` /users/{user_id}/push/{token_type}/{token} Removes a specific user’s push token.
Remove a certain type of push tokens	`DELETE` /users/{user_id}/push/{token_type} Removes a specific user’s certain type of push tokens.

List users for Calls

Retrieves a list of Calls users in your Sendbird application.

HTTP request

GET https://api-{application_id}.calls.sendbird.com/v1/users

Parameters

The following table lists the parameters that this action supports.

Optional

Parameter name	Type	Description
next	string	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.

Query string example

?token=YXYWRFBTQlArEUBXWFNeF2p2FEFdUA~~&limit=3

Response

If successful, this action returns a list of user resources in the response body.

Status: 200 OK

{
    "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": {
                "font_preference": "times new roman",
                "font_color": "black"
            }
        },
        {
            "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": {
                "font_preference": "times new roman",
                "font_color": "black"
            }
        },
        {
            "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": {
                "font_preference": "times new roman",
                "font_color": "gray"
            }
        }
    ],
    "next": "YXEZR1VVQVErEUBXWFNeF2p3FkFVVA~~"
}

List of response properties

Property name	Type	Description
users[]	list	A list of users.
next	string	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)
next	string	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 milliseconds format. * A time range could be specified up to 90 days. If not specified, the last 90 days is automatically set.
end_ts	int	Restricts the search scope to only retrieve calls which have been ended before the specified time in Unix milliseconds format. * A time range could be specified up to 90 days. If not specified, the last 90 days is automatically set.
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.

Query string example

?next=RtWWRdBTQlArEUdXWaNFE2p2FEd3FA~~&limit=3&role=dc_caller&start_ts=1574763116000&end_ts=1574763216000&end_result=no_answer

Response

If successful, this action returns a list of calls resources in the response body.

Status: 200 OK

{
    "Calls": [
        {
            "call_id": "25168092-A882-4173-8EED-158AA8542BFC",
            "call_type": "direct",
            "is_video_call": false,
            "state": "ended",
            "end_result": "completed",
            "user_role": "dc_caller",
            "participants": [
                {
                    "user_id": "Jeff",
                    "nickname": "OldBoy",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_22_512px.png",
                    "is_active": true,
                    "role": "dc_caller",
                    "metadata": {
                        "font_preference": "times new roman",
                        "font_color": "black"
                    }
                },
                {
                    "user_id": "Young",
                    "nickname": "Sportsman",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_23_512px.png",
                    "is_active": true,
                    "role": "dc_callee",
                    "metadata": {
                        "font_preference": "times new roman",
                        "font_color": "gray"
                    }
                }
            ],
            "started_by": "Jeff",
            "started_at": 1574763116000,
            "ended_by": "Young",
            "ended_at": 1574763117000,
            "duration": 1000,
            "custom_items": {
                "is_paid_call": "Y",
                "call_quality": "HIGH"
            }
        },
        ... # More calls
    ],
    "has_next": true,
    "next": "ansYQFFRQ1AIEUBXX1RcE2d0FUZSUlkJFVQRHB8"
}

List of response properties

Property name	Type	Description
calls[]	list	A list of the user's calls.
has_next	boolean	Indicates whether there is the next page of the user’s calls.
next	string	The value for the next parameter to retrieve the next page in the result set.

Retrieve a user's call summary

Retrieves the call summary of a specific user.

HTTP request

GET https://api-{application_id}.calls.sendbird.com/v1/users/{user_id}/call_summary

Parameters

The following table lists the parameters that this action supports.

Required

Property name	Type	Description
user_id	string	Specifies the unique ID of the target user.

Response

If successful, this action returns a call summary resources in the response body.

Status: 200 OK

{
    "last_call": {
        "call_id": "7F28206B-B49E-4ABD-A3AE-96DE4AB208EF",
        "started_at": 1575622652000,
        "ended_at": 1575622931000,
    },
    "call_count": {
        "direct_call": {
            "caller": 1,
            "callee": 0,
            "sum": 1
        },
        "total": 1
    }
}

List of response properties

Property name	Type	Description
last_call	nested object	The information of the last call that the user has made. A value of null indicates no calls have been made yet.
call_count	nested object	The information of how many calls were made by the user.
call_count.direct_call.caller	int	The total count of direct calls.
call_count.direct_call.callee	int	The total count of how many direct calls were made by the caller.
call_count.direct_call.sum	int	The total count of how many direct calls were received by the callee.
call_count.total	int	The total count of all types of calls.

Retrieve a list of a user's push tokens

Retrieves a specific user’s push tokens.

HTTP request

GET 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 target user.
token_type	string	Specifies the type of the push tokens to retrieve. Acceptable values are apns_voip, fcm_voip, and calls_apns_remote.

Response

If successful, this action returns a user resource and an array of the registered push tokens in the response body.

Status: 200 OK

{
    "user": {
        "user_id": "Kern",
        "nickname": "Basketball Player",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_74_512px.png",
        "metadata": {
            "font_preference": "times new roman",
            "font_color": "black"
        }
    },
    "type": "apns_voip",
    "tokens": [
        "d3f34e075e38f8f5693a6f4d9048dd0c8a0a79d79ea8c6e5de72bb4fbb163704"
    ]
}

Add a registration or device token

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.

Status: 200 OK

{
    "user": {
        "user_id": "Kern",
        "nickname": "Basketball Player",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_74_512px.png",
        "metadata": {
            "font_preference": "times new roman",
            "font_color": "black"
        }
    },
    "type": "apns_voip",
    "token": "a73e9r075e30f8f56a3a6f4d9048dd0ca43a7da79ea3c6e5de72bbw3bb1632a4"
}

Remove a user's push token

Removes a specific user’s push token.

HTTP request

DELETE https://api-{application_id}.calls.sendbird.com/v1/users/{user_id}/push/{token_type}/{token}

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 registration or device token to remove.

Response

If successful, this action returns a user resource and the removed push token in the response body.

Status: 200 OK

{
    "user": {
        "user_id": "Kern",
        "nickname": "Basketball Player",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_74_512px.png",
        "metadata": {
            "font_preference": "times new roman",
            "font_color": "black"
        },
        "sdk_version_info": ""
    },
    "token": "a73e9r075e30f8f56a3a6f4d9048dd0ca43a7da79ea3c6e5de72bbw3bb1632a4"
}

List of response properties

Property name	Type	Description
user	nested object	The user resource which encapsulates information about the specified user.
token	string	The unregistered token of the user.

Remove a certain type of push tokens

Removes a specific user’s certain type of push tokens.

HTTP request

DELETE 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 target user.
token_type	string	Specifies the type of the push tokens. Acceptable values are apns_voip, fcm_voip, and calls_apns_remote.

Response

If successful, this action returns a user resource and the type of unregistered push tokens in the response body.

Status: 200 OK

{
    "user": {
        "user_id": "Kern",
        "nickname": "Basketball Player",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_74_512px.png",
        "metadata": {
            "font_preference": "times new roman",
            "font_color": "black"
        },
        "sdk_version_info": ""
    },
    "type": "fcm_voip"
}

List of response properties

Property name	Type	Description
user	nested object	The user resource which encapsulates information about the specified user.
type	string	The type of the removed push tokens.

On this page

Resource representation Actions List users for Calls Retrieve a list of a user's calls Retrieve a user's call summary Retrieve a list of a user's push tokens Add a registration or device token Remove a user's push token Remove a certain type of push tokens