Calls Platform API v1

Calls Platform API

Calls

Platform API

Version 1

Home

Calls

Platform API

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

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

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
}

Try API requests