Calls Platform API v1
Calls Platform API
Calls Platform API
Version 1

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

Copy link

The following table shows the list of properties in a user resource.

Property nameTypeDescription

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

Copy link
  • 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

Copy link
ActionHTTP 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

Copy link

Retrieves a list of Calls users in your Sendbird application.

HTTP request

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

Parameters

Copy link

The following table lists the parameters that this action supports.

Optional
Parameter nameTypeDescription

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.

?token=YXYWRFBTQlArEUBXWFNeF2p2FEFdUA~~&limit=3

Response

Copy link

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": {
                "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

Copy link
Property nameTypeDescription

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

Copy link

Retrieves all the calls that a specific user has made.

HTTP request

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

Parameters

Copy link

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the unique ID of the target user.

OptionalTypeDescription

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 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.

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

Response

Copy link

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

{
    "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

Copy link
Property nameTypeDescription

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

Copy link

Retrieves the call summary of a specific user.

HTTP request

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

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Property nameTypeDescription

user_id

string

Specifies the unique ID of the target user.

Response

Copy link

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

{
    "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

Copy link
Property nameTypeDescription

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

Copy link

Retrieves a specific user’s push tokens.

HTTP request

Copy link
GET https://api-{application_id}.calls.sendbird.com/v1/users/{user_id}/push/{token_type}

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

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

Copy link

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

{
    "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

Copy link

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

Copy link
POST https://api-{application_id}.calls.sendbird.com/v1/users/{user_id}/push/{token_type}

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

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

Copy link

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

{
    "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

Copy link

Removes a specific user’s push token.

HTTP request

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

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

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

Copy link

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

{
    "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

Copy link
Property nameTypeDescription

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

Copy link

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

HTTP request

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

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

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

Copy link

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

{
    "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

Copy link
Property nameTypeDescription

user

nested object

The user resource which encapsulates information about the specified user.

type

string

The type of the removed push tokens.