Calls Platform API v1

Calls Platform API

Version 1

Direct call

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

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

Property name	Type	Description
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

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

Action	HTTP 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. The retrieved list of direct calls are sorted in reverse order, meaning the newest direct call appears first and the oldest last.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Optional

Parameter name	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.
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: `1000`)
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`.

Query string example

?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

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

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

Retrieves a specific direct call.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Required

Property name	Type	Description
call_id	string	Specifies the unique ID of the target call.

Query string example

?with_sorted_meta_array=true

Response

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

Status: 200 OK

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

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

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.

Required

Parameter name	Type	Description
call_id	string	Specifies the unique ID of the target call.

Request body

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

Properties

Required	Type	Description
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.

Optional	Type	Description
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

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

Property name	Type	Description
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

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.

Required

Property name	Type	Description
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

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

On this page

Resource representation Actions Retrieve a list of direct calls Retrieve a direct call Update custom items of a direct call Delete custom items of a direct call