Platform API
Calls Call

Call

A call allows voice or video communication between users. Currently, SendBird Calls only supports a one-to-one call known as direct call.

Note: Right now, the Calls API supports retrieving calls and actions for custom items. Other actions should be done from the Calls SDK.

Resource representation

Property nameTypeDescription

call_id

long

A unique identifier for the call.

call_type

string

The type of the call.

is_video_call

string

Indicates whether the call is a video call.

state

string

The state of the call.

end_result

string

The result of how the call has ended. Valid values are completed, canceled, declined, connection_lost, no_answer, late_answer, timed_out, and unknown.

user_role

string

The user's role in the call. This appears either as dc_caller or as dc_callee when a user_id parameter is specified in a request.

participants

nested object

The users who have participated in the call.

started_by

string

The ID of the user who dialed the call.

started_at

long

The timestamp of when the call was dialed, in Unix milliseconds.

ended_by

string

The IDs of the specific users who get a notification for the message.

ended_at

long

The timestamp of when the call was ended, in Unix milliseconds.

duration

int

The period from the call was accepted to when the call was ended, measured in seconds.

custom_items[]

array

An array of custom key-value items which store addtional information for the call.

Actions

  • API endpoints are relative to the base URL allocated to your application. In this page, the /direct_calls endpoint refers to https://api-{application_id}.calls.sendbird.com/v1/direct_calls.

Note: If you want to know your application ID, sign in to your dashboard, go to the Settings > Application > General, and then check the Credentials > Application ID.

  • It's recommended that the parameter values in API URLs are urlencoded, such as {user_id}.
ActionHTTP request

Retrieve a list of direct calls

GET /direct_calls
Retrieves all direct calls within the application.

Retrieve a direct call

GET /direct_calls/{call_id}
Retrieves a specific direct call.

Update custom items of a direct call

PUT /direct_calls/{call_id}/custom_items
Updates custom items of a specific direct call.

Delete custom items of a direct call

DELETE /direct_calls/{call_id}/custom_items
Deletes custom items of a specific direct call.


Retrieve a list of direct calls

Retrieves all direct calls within the application.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.calls.sendbird.com/v1/users/direct_calls

Parameters

The following table lists the parameters that this action supports.

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

user_id

string

Specifies the unique ID of the target user.

call_ts

long

Specifies the timestamp to be the reference point of the query, in Unix milliseconds. If specified along with the search_scope_from_call_ts, this parameter sets a time range and restricts the search scope to only retrieve calls of which started_at or ended_at is within the range.

search_scope_from_call_ts

long

Specifies the scope to add to the call_ts and determine the search scope range, in Unix milliseconds.

duration_range_min

int

Specifies the minimum value of the duration to restrict the search scope to only retrieve calls of which duration is equal to or greater than the specified value. This should be specified in conjunction with the duration_range_max parameter.

duration_range_max

int

Specifies the maximum value of the duration to restrict the search scope to only retrieve calls of which duration is equal to or less than the specified value. This should be specified in conjunction with the duration_range_min parameter.

state

int

Restrict the search scope to only retrieve calls of which state matches the specified value. Acceptable values are limited to current and ended.

end_result

string

Restricts the search scope to only retrieve calls of which end result matches the specified value. Acceptable values are limited to completed, canceled, declined, connection_lost, no_answer, late_answer, timed_out, and unknown.

Query string example
Light Color Skin
Copy
?next=sWzRa3BTQlArEUBXWnNPF2p2FEd3yZ~~&limit=3&start_ts=1574763116000&search_scope_from_call_ts=10000&end_result=no_answer&duration_range_min=5000&duration_range_max=10000

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "Calls": [
        {
            "call_id": "25168092-A882-4173-8EED-158AA8542BFC",
            "call_type": "direct",
            "is_video_call": false,
            "state": "ended",
            "end_result": "completed",
            "participants": [
                {
                    "user_id": "Kern",
                    "nickname": "Basketball Player",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_74_512px.png",
                    "is_active": true,
                    "role": "dc_caller",
                    "metadata": {
                        "location": "Seattle",
                        "marriage": "Y"
                    }
                },
                {
                    "user_id": "Julia",
                    "nickname": "Yogini",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_94_512px.png",
                    "is_active": true,
                    "role": "dc_callee",
                    "metadata": {
                        "location": "Bali",
                        "marriage": "N"
                    }
                }
            ],
            "started_by": "Kern",
            "started_at": 1574763463000,
            "ended_by": "Julia",
            "ended_at": 1574763467000,
            "duration": 4000,
            "custom_items": {
                "is_paid_call": "Y",
                "call_quality": "HIGH"
            }
        },
        ... # More calls
    ],
    "has_next": true,
    "next": "ansYQFFRQ1AIEUBXX1RcE2d0FUZSUlkJFVQRHB8"
}
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 direct call

Retrieves a specific direct call.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.calls.sendbird.com/v1/users/direct_calls/{call_id}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

call_id

string

Specifies the unique ID of the target call.

Query string example
Light Color Skin
Copy
?with_sorted_meta_array=true

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "call_id": "25168092-A882-4173-8EED-158AA8542BFC",
    "call_type": "direct",
    "is_video_call": false,
    "state": "ended",
    "end_result": "completed",
    "participants": [
        {
            "user_id": "Kern",
            "nickname": "Basketball Player",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_74_512px.png",
            "is_active": true,
            "role": "dc_caller",
            "metadata": {
                "location": "Seattle",
                "marriage": "Y"
            }
        },
        {
            "user_id": "Julia",
            "nickname": "Yogini",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_94_512px.png",
            "is_active": true,
            "role": "dc_callee",
            "metadata": {
                "location": "Bali",
                "marriage": "N"
            }
        }
    ],
    "started_by": "Kern",
    "started_at": 1574763463000,
    "ended_by": "Julia",
    "ended_at": 1574763467000,
    "duration": 4000,
    "custom_items": {
        "is_paid_call": "Y",
        "call_quality": "HIGH"
    }
}

Update custom items of a direct call

Updates custom items of a specific direct call. A direct call can have custom key-value items which store additional information for the call.

Note: When a direct call is created, its custom items have no values by default.

HTTP request

Light Color Skin
Copy
PUT https://api-{application_id}.calls.sendbird.com/v1/users/direct_calls/{call_id}/custom_items

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

call_id

string

Specifies the unique ID of the target call.

custom_items

nested object

Specifies a JSON object that has key-value custom items to update. A key must not have a comma (,).

mode

string

Determines whether to update the existing custom items or add new custom items. Acceptable values are the following:
- upsert (default): The existing items are updated with new values when there are already custom items with the keys.
- insert: New key-value custom items are added when there are no items with the keys.

Response

If successful, this action returns custom items including the updated or added ones in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "call_id": "25168092-A882-4173-8EED-158AA8542BFC",
    "updated": [
        "satisfaction_score",
        "satisfaction_comment"
    ],
    "custom_items": {
        "is_paid_call": "Y",
        "call_quality": "HIGH",
        "satisfaction_score": "5",
        "satisfaction_comment": "Good quality!",
    },
    "affected_at": 1574763467896
}
Property nameTypeDescription

call_id

string

The unique ID of the target call.

updated

array

An array of the keys for updated custom items.

custom_items

nested object

The custom items including the updated or added ones.

affected_at

long

The time of when the specified custom items have been updated, in Unix milliseconds.


Delete custom items of a direct call

Deletes custom items of a specific direct call.

HTTP request

Light Color Skin
Copy
DELETE https://api-{application_id}.calls.sendbird.com/v1/users/direct_calls/{call_id}/custom_items

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

keys

array

Specifies the keys of custom items to delete. If not specified, all custom items of the direct call are deleted.

Response

If successful, this action returns custom items excluding the deleted ones in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "call_id": "25168092-A882-4173-8EED-158AA8542BFC",
    "deleted": [
        "satisfaction_score",
        "satisfaction_comment"
    ],
    "custom_items": {
        "is_paid_call": "Y",
        "call_quality": "HIGH",
    },
    "affected_at": 1574763468135
}