All products
Calls
/
Platform API

Call

A call allows voice or video communication between users. Currently, Sendbird Calls only supports a 1-to-1 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, 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 milliseconds.

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

  • It's recommended that the parameter values in API URLs be 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/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_ids

string

Searches for calls that include one or more users in the parameter value. The string should consist of multiple urlencoded user IDs separated by commas ( for example, ?user_ids=urlencoded_id_1, urlencoded_id_2).

* The user_id can be used interchangeably with this parameter, but can only specify one user ID. When both the user_id and the user_ids are specified, the user_ids will be ignored and only the user_id will be effective.

between_two_user_ids_only

string

Searches for calls between two users in the parameter value. The string should consist of only the two urlencoded user IDs separated by commas.

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, in Unix milliseconds. 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 less than the specified value, in Unix milliseconds. 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 any of the specified value. Acceptable values are limited to current and ended.

end_result

string

Specifies a comma-separated 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 completed, canceled, declined, connection_lost, no_answer, timed_out, and unknown.

Query string example
Light Color Skin
Copy
?next=sWzRa3BTQlArEUBXWnNPF2p2FEd3yZ~~&limit=3&call_ts=1574763116000&search_scope_from_call_ts=10000&end_result=completed,canceled&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": 437782,
            "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/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/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. The key must not have a comma (,) and its length is limited to 128 characters. The value must be a string and its length is limited to 128 characters. This parameter can have up to 10 custom items.

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/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
}