Platform API
Quick Start

Quick Start

Using the Platform API, you can directly interact with the different types of resources which represent data associated with chat activities in your SendBird application. The 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 API adds flexibility and abilities to your service from the server side.

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


Base URL

The base URL used for the Platform API is formatted as the following:

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

To get the ID and the allocated base URL of your application, sign in to your dashboard, select the application, open the Overview, and then check the App credentials > App ID, API request URL.


Headers

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

Light Color Skin
Copy
Content-Type: application/json, charset=utf8
Api-Token: {API_TOKEN}
  • Content-Type: every request must include a Content-Type header.
  • Api-Token: an API token is required for SendBird server to identify and authenticate your SendBird application. 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.

Multipart requests

If your request contains a file, you should send a Multipart request. To make that request, specify multipart/form-data in the Content-Type header, as well as a boundary, which is a delimiter string that separates each data field.

HTTP
Python
cURL
Light Color Skin
Copy
Content-Type: multipart/form-data; boundary={your_unique_boundary_string}

--{your_unique_boundary_string}
Content-Disposition: form-data; name="property1"

[value1]
--{your_unique_boundary_string}
Content-Disposition: form-data; name="property2"

[value2]
--{your_unique_boundary_string}
Content-Disposition: form-data; name="file"; filename="{file_name}"
Content-Type: {Content-Type}

[binary contents of the file]
--{your_unique_boundary_string}--
Light Color Skin
Copy
import os
import requests
api_headers = {'Api-Token': '{api_token}'}
data = {
    'property1': {value1},
    'property2': {value2}
}
filepath = os.path.join(os.path.dirname(__file__), FILE_PATH, '{file_name}')
upload_files = {'file': ('{file_name}', open(filepath, 'rb'))}
res = requests.post('{api_request_URL}', 
        headers=api_headers, data=data, files=upload_files)
Light Color Skin
Copy
curl -X {HTTP Method} 
    -H "Api-Token: {api_token}" 
    -H "Content-Type: multipart/form-data; boundary={your_unique_boundary_string}" 
    -F "property1={value1}" 
    -F "property2={value2}" 
    -F "file=@{file_path}"
    "{api_request_URL}"
Python request example
Light Color Skin
Copy
# python: Create User API
import os
import requests
api_headers = {'Api-Token': '{api_token}'}
data = {
    'user_id': '{user_id}',
    'nickname': '{nickname}',
    'issue_access_token': true
}
filepath = os.path.join(os.path.dirname(__file__), FILE_PATH, '{file_name}')
upload_files = {'profile_file': ('{file_name}', open(filepath, 'rb'))}
res = requests.post('https://api-{application_id}.sendbird.com/v3/users', 
        headers=api_headers, data=data, files=upload_files)

Authentication

Using an API token

To make a call to the Platform API, you must authenticate a request using the API token of your SendBird application. You can find the token in the dashboard under Overview > App Credentials, which is actually the master API token. The master API token is generated when an application has been created, and it can't be revoked or changed.

Using the master API token, you can additionally generate an API token, revoke other API token, or retrieve a list of API tokens. As stated above, any of API tokens must be included in your HTTP Request Header for authentication.

Note: This usage has been changed from our old Server API, which previously required the token to be included in the payload.

Request Header
Light Color Skin
Copy
"Api-Token": {API_TOKEN}

DO NOT request any Platform API from your client app. If your API token information is compromised, you risk losing all your data.

Using HTTP Basic authentication

Authenticate with HTTP Basic authentication when you want to delete or list all applications, or create one. In these scenarios, you can authenticate your request with your sign-in details instead of your API tokens. Generate a Basic Auth Header by inputting your sign-in email and password.

If you create a basic auth header manually, then do the following:

  1. Combine your email and password with a single colon (:). For example, api@sendbird.com:1234
  2. Encode the resulting string using the RFC2045-MIME variant of Base64, no more than 76 characters per line. For example, type echo -n 'api@sendbird.com:1234' | base64 on the command line to encode.
  3. Prepend the authorization method Basic and a space to the encoded string, which is used as a value for an Authorization field. For example, Basic YXBpQHNlbmRiaXJkLmNvbToxMjM0
  4. Assign the resulting authorization information to the Authorization field in your HTTP header. For example, Authorization: Basic YXBpQHNlbmRiaXJkLmNvbToxMjM0

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.

In the following URL, the value of the user_id parameter should be urlencoded. For example, user_id@email.com is urlencoded to user_id%40email.com.

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

Note: If you want to know the ID and base URL of your application, sign in to your dashboard, select the application, open the Overview, and then check the App credentials > App ID, API request URL.

Like the following, you can encode URLs in most languages.

JavaScript
Python
Light Color Skin
Copy
encodeURIComponent("api@sendbird.com");
Light Color Skin
Copy
import urllib
urllib.quote('api@sendbird.com', safe='')

which returns:

Light Color Skin
Copy
api%40sendbird.com

Therefore, your full request looks like:

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/users/api%40sendbird.com