Platform API
Calls Quick Start

Quick Start

Using Calls Platform API, you can directly interact with the different types of resources which represent data associated with call activities in your SendBird application. The Calls API is designed to use standard HTTP protocols and return JSON payloads in response to HTTP requests and is internally implemented based on the RESTful principles. While the native SDKs handle many of the requests and responses at the client-side, the Calls API adds flexibility and abilities to your service from the server-side.

Note: The Calls API is not designed for client side use. Use the corresponding Chat SDKs instead.


Base URL

The base URL used for the Chat API is formatted as shown below:

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

To get your SendBird application ID, sign in to your dashboard, select the application, go to the Settings > Application > General, and then check the Credentials > Application ID.


Headers

A typical HTTP request to the Chat API includes the following headers:

Light Color Skin
Copy
Content-Type: application/json, charset=utf8
Api-Token: {master_api_token or secondary_api_token}
  • Content-Type: every request must include a Content-Type header.
  • Api-Token: either the master API token or a secondary API token is required for SendBird server to authenticate your API requests. An exception occurs when you attempt to perform certain actions outside the scope of the current application such as creating a new application, or retrieving a list of SendBird applications, in which case you should provide Basic Authentication.

Authentication

Your API requests must be authenticated by SendBird server using any of API tokens of your SendBird application. For this, you can use the master API token in your dashboard under Settings > Application > General > API tokens, which is generated when an application has been created. The master API token can't be revoked or changed.

Using the master API token, you can generate a secondary API token, revoke a secondary API token, or retrieve a list of secondary API tokens. For most of API requests, a secondary API token can be used instead of the master API token. As stated above, any of API tokens must be included in your HTTP request headers for authentication.

Request Header
Light Color Skin
Copy
"Api-Token": {master_api_token or secondary_api_token}

DO NOT send any Calls API requests from your client app. If your API token information is leaked in the process of exchanging data, you could lose all your data by malicious API calls.


URL encoding

When sending requests over HTTP, you should encode URLs into a browser-readable format. URL encoding replaces unsafe non-ASCII characters with a % followed by hex digits to ensure readability.

For example, if you are making a request to the following URL for a user whose ID is user_id@email.com, the ID should be urlencoded to user_id%40email.com.

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

As a result, the URL will be shown as below:

Light Color Skin
Copy
GET https://api-{application_id}.calls.sendbird.com/v1/users/user_id%40email.com/calls