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

Direct call

Copy link

This page explains the key functions of direct call consisting of how to retrieve a direct call or a list of direct calls, update custom items, and delete custom items of a 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

Copy link

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

Property nameTypeDescription

call_id

string

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.

* Some end results are shown differently on the Dashboard. The following respectively lists the corresponding end results shown in the dashboard: completed, canceled, declined, dropped, missed, timed out, and interrupted.

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

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.


Actions

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

List of actions

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

Copy link

Retrieves all direct calls within the application. The retrieved list of direct calls are sorted in reverse order, meaning the newest direct call appears first and the oldest last.

HTTP request

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

Parameters

Copy link

The following table lists the parameters that this action supports.

Optional
Parameter nameTypeDescription

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, an error will be returned.

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 of the query start time in Unix milliseconds. If this parameter isn't specified, the last 90 days starting from the time of query are searched by default.

search_scope_from_call_ts

long

Specifies the query range starting from the set call_ts timestamp in milliseconds. This parameter is only used when call_ts is specified and can be set to a value ranging from one second to 90 days. (Default: 86400000, which means a day)

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

string

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.

?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

Copy link

If successful, this action returns a list of call 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",
            "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": {
            "font_preference": "times new roman",
            "font_color": "black"
                    }
                },
                {
                    "user_id": "Julia",
                    "nickname": "Yogini",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_94_512px.png",
                    "is_active": true,
                    "role": "dc_callee",
                    "metadata": {
            "font_preference": "times new roman",
            "font_color": "gray"
                    }
                }
            ],
            "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"
}

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 direct call

Copy link

Retrieves a specific direct call.

HTTP request

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

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Property nameTypeDescription

call_id

string

Specifies the unique ID of the target call.

Response

Copy link

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

{
  "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": {
        "font_preference": "times new roman",
        "font_color": "black"
      }
    },
    {
      "user_id": "Julia",
      "nickname": "Yogini",
      "profile_url": "https://sendbird.com/main/img/profiles/profile_94_512px.png",
      "is_active": true,
      "role": "dc_callee",
      "metadata": {
        "font_preference": "times new roman",
        "font_color": "gray"
      }
    }
  ],
  "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

Copy link

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

Copy link
PUT https://api-{application_id}.calls.sendbird.com/v1/direct_calls/{call_id}/custom_items

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

call_id

string

Specifies the unique ID of the target call.

Request body

Copy link

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

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.

OptionalTypeDescription

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

Copy link

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

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

List of response properties

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

Copy link

Deletes custom items of a specific direct call.

HTTP request

Copy link
DELETE https://api-{application_id}.calls.sendbird.com/v1/direct_calls/{call_id}/custom_items

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Property nameTypeDescription

keys

array

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

Response

Copy link

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

{
  "call_id": "25168092-A882-4173-8EED-158AA8542BFC",
  "deleted": ["satisfaction_score", "satisfaction_comment"],
  "custom_items": {
    "is_paid_call": "Y",
    "call_quality": "HIGH"
  },
  "affected_at": 1574763468135
}

List of response properties

Copy link
Property nameTypeDescription

call_id

string

The unique ID of the target call.

deleted

array

An array of the keys for deleted custom items.

custom_items

nested object

The custom items after deleting.

affected_at

long

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