/ Platform API
Platform API
    Chat Platform API v3
    Chat Platform API
    Chat Platform API
    Version 3

    Prepare to use API

    Copy link

    Sendbird's Chat Platform API allows you to directly work with data resources related to your Sendbird application’s chat activities. The Chat API uses standard HTTP protocols where JSON payloads are returned in response to the HTTP requests. It is internally implemented based on the RESTful principles. While the native SDKs handle many of the requests and responses at the client side, the Chat API allows for more flexibility and adds additional functionalities to your service from the server side.

    Note: The Chat API isn't designed for client side use. Use the corresponding Chat SDKs instead.


    Base URL

    Copy link

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

    https://api-{application_id}.sendbird.com/v3
    

    To get the ID and the allocated base URL of your Sendbird application, sign in to your dashboard, select the application, go to Settings > Application > General, and then check the Application ID, and API request URL.


    Headers

    Copy link

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

    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.

    Multipart requests

    Copy link

    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.

    When sending a multiple file message, we recommend you use other methods, such as a cURL request.

    HTTPPythoncURL
    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="property3"; filename="{file_name}"
    Content-Type: {Content-Type}
    
    [binary contents of the file]
    --{your_unique_boundary_string}--
    
    # python: Create User API
    import os
    import requests
    api_headers = {'Api-Token': '{master_api_token or secondary_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, json=data, files=upload_files)
    

    Authentication

    Copy link

    Your API requests must be authenticated by Sendbird server using any of the API tokens from your Sendbird application. To do 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 list secondary API tokens. For most API requests, a secondary API token can be used instead of the master API token. As said before, any one of the API tokens must be included in your HTTP request headers for authentication.

    Note: Previously, our old Server API required the payload to include a token.

    "Api-Token": {master_api_token or secondary_api_token}
    

    Note: DON'T send any Chat 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 from malicious API calls.


    URL encoding

    Copy link

    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.

    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, go to Settings > Application > General, and then check the Application ID, and API request URL.

    In most languages, you can encode URLs in a similar way as the following:

    JavaScriptPython
    encodeURIComponent("api@sendbird.com");
    

    It should return: bash,chat/v3/platform-api/prepare-to-use-api-153 api%40sendbird.com Your full request should look like the following. bash,chat/v3/platform-api/prepare-to-use-api-157 GET https://api-{application_id}.sendbird.com/v3/users/api%40sendbird.com