Application

You can create one application per service, regardless of the platform. For example, an app released in both Android and iOS would require only one application to be created. You can manage individual applications, as well as your apps in general, using the Platform API.

When you're ready to start building, you should understand that Sendbird application has some restrictions on its functionalities to maintain the stability of chat service and also gives you ways to work with the application users. With the following information, you can integrate SendBird to your own application for us to work better together.

Property name Type Description
app_id string The unique App ID of the application.
name string The name of the application.
icon_url string The URL of the application's icon.
api_token string The API token of the application.
ccu int The number of concurrently connected users within the application.
mau int The number of monthly active users within the application.
dau int The number of daily active users within the application.

Default settings

To prevent some users' abnormal activities, SendBird application has the following limits on the number of messages per second which a user can send and a channel can display.

Imposed on Limit If exceeded
User 5 messages per second Excess messages are not sent to a channel, and not saved in the database
Channel 5 messages per second Excess messages are not displayed in a channel, but saved in the database

The limits above are basic numbers of our premium features, spam flood protection and smart throttling, which could be adjusted in some situations. Currently in the dashboard, paying customers can control the limit of the smart throttling.

  • API endpoints are relative to the allocated base URL for your app. In this section, the /applications endpoint refers to https://{region_identifier}.sendbird.com/v3/applications.

Note: If you want region_identifier for your app, sign in to the SendBird Dashboard, select the application, open the Overview, and see the App Credentials > API URL.

  • Requests to the same endpoint can perform different actions based on the type of authentication included in the header.
HTTP Basic Auth
Action HTTP request Description
Create an application POST /applications Creates an application.
List applications GET /applications Returns a list of all applications.
Delete all applications DELETE /applications Deletes all applications.
Authorization with API token
Action HTTP request Description
View the application GET /applications/info Returns information about an application.
Delete the application DELETE /applications Deletes an application.
View CCU GET /applications/ccu Returns the number of concurrently connected users.
View MAU GET /applications/mau Returns the number of monthly active users.
View DAU GET /applications/dau Returns the number of daily active Users.
View daily message count GET /applications/messages/daily_count Returns the total number of messages sent on a given date.
Add a push configuration POST /applications/push/{push_type} Registers a push configuration
List push configurations GET /applications/push/{push_type} Returns a list of an application's registered Push Configurations.
Delete the push configuration DELETE /applications/push/{push_type} Deletes an application's Push Configuration.
View an API token GET /applications/api_tokens/{api_token} Returns information about an API token.
Revoke the API token DELETE /applications/api_tokens/{api_token} Revokes an API token.
Authorization with Master API token
Action HTTP request Description
View an API token GET /applications/api_tokens/{api_token} Returns information of an API token.
Issue an API token POST /applications/api_tokens Issues an API token.
Revoke the API token DELETE /applications/api_tokens/{api_token} Revokes an API token.
List API tokens GET /applications/api_tokens Returns a list of API tokens issued.

Create an application

Creates an application. You must use HTTP Basic Auth.

POST https://{region_identifier}.sendbird.com/v3/applications
Property name Type Description
name string The name of the application. The length is limited to 128 bytes.
Request body example
{
    "name": "New SendBird Application"
}

Returns an application representation.

Status: 200 OK
{
    "icon_url": "",
    "api_token": "5add197438b9bc373af63a0f043daa93820dc474",
    "app_id": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "New SendBird Application"
}

List applications

Returns a list of all applications. You must use HTTP Basic Auth.

GET https://{region_identifier}.sendbird.com/v3/applications
Parameter name Type Description
token string A token that specifies the index of the first result. If not specified, the index is set as 0.
limit int The number of results returned per page. Acceptable values are 1 to 100, inclusive. (Default: 10)
Status: 200 OK
{
    "applications": [
        {
            "icon_url": "",
            "api_token": "80af23e7ec3a57fa2c92c219faf9e8f1e5bd4a6c",
            "app_id": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "name": "My Application"
        },
        {
            "icon_url": "",
            "api_token": "5add197438b9bc373af63a0f043daa93820dc474",
            "app_id": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "name": "New SendBird Application"
        },
        {
            "icon_url": "",
            "api_token": "a57443d25be53da3242e6d5db0b6e324e26bc127",
            "app_id": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "name": "Application for next project"
        }
    ],
    "next": ""
}
Property name Type Description
applications[] list Returns a list of applications.
next string The token for the next chunk of results.

Delete all applications

Deletes all applications. You must use HTTP Basic Auth.

DELETE https://{region_identifier}.sendbird.com/v3/applications
Status: 200 OK
{}

View the application

Returns information about an application. You must authorize with your API token.

GET https://{region_identifier}.sendbird.com/v3/applications/info

Returns an application representation.

Status: 200 OK
{
    "icon_url": "",
    "api_token": "a57443d25be53da3242e6d5db0b6e324e26bc127",
    "app_id": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "Application for next project"
}

Delete the application

Deletes an application. You must authorize with your API token.

DELETE https://{region_identifier}.sendbird.com/v3/applications
Status: 200 OK
{}

View CCU

Returns the number of concurrently connected users within the application. You must authorize with your API token.

GET https://{region_identifier}.sendbird.com/v3/applications/ccu
Status: 200 OK
{
    "ccu": 327               
}
Property name Type Description
ccu int The number of concurrently connected users.

View MAU

Returns the number of monthly active users within the application. You must authorize with your API token.

GET https://{region_identifier}.sendbird.com/v3/applications/mau
Parameter name Type Description
date string The date of reference.
Request example
?date=2016-01-05
Status: 200 OK
{
    "mau": 52778
}

View DAU

Returns the number of daily active users within the application. You must authorize with your API token.

GET https://{region_identifier}.sendbird.com/v3/applications/dau
Parameter name Type Description
date string The date of reference.
Request example
?date=2016-01-05
Status: 200 OK
{
    "dau": 1826
}

View daily message count

Returns the total number of messages sent on a given day for a range of dates. You must authorize with your API token.

GET https://{region_identifier}.sendbird.com/v3/applications/messages/daily_count
Parameter name Type Description
start_date string The earliest date to return results of.
end_date string The end date to return results of.
Request example
?start_date=2017-01-10&end_date=2017-01-16
Status: 200 OK
{
    "message_count": {
        "2017-01-16": 156,
        "2017-01-15": 175,
        "2017-01-14": 238,
        "2017-01-13": 188,
        "2017-01-12": 293,
        "2017-01-11": 299,
        "2017-01-10": 283
    }
}
Property name Type Description
message_count nested object The number of messages sent within the application on a given date.

Add a GCM push configuration

Registers/unregisters a GCM (Google Cloud Messaging or Firebase Cloud Messaging) push configuration. To send push notifications to Android devices, first register the GCM push configuration. You can also register these configurations through the SendBird Dashboard.

POST https://{region_identifier}.sendbird.com/v3/applications/push/gcm
Property name Type Description
gcm_sender_id string The GCM Sender ID.
gcm_api_key string The GCM API Key.
Status: 200 OK
{
    "push_configurations": [
        "6646a4d45610dfb0c772f14134610c6ff3121e59"
    ]
}
Property name Type Description
push_configurations list A list of push configurations.
push_configurations.id string A unique ID that identifies the push configuration. This value is automatically generated by SendBird.

Add an APNS push configuration

Registers/unregisters an APNS (Apple Push Notification Service) push configuration. To send push notifications to iOS devices, first register the APNS push configuration. You can also register these configurations through the SendBird Dashboard.

Note: You should send a Multipart request.

POST https://{region_identifier}.sendbird.com/v3/applications/push/apns
Property name Type Description
has_unread_count_badge boolean Whether to send unread count badges.
apns_cert_development file Include this field if you are in development stage. This is a .p12 file. Make sure you attach the correct (development, not production) version of your .p12 file, or else you receive an error.
apns_cert_production file Include this field if you are in production stage. This is a .p12 file. Make sure you attach the correct (production, not development) version of your .p12 file, or else you receive an error.
Request example
Content-Type: multipart/form-data; boundary=--some_boundary_delimiter_string
Content-Length: (Length of content)

----some_boundary_delimiter_string
Content-Disposition: form-data; name="has_unread_count_badge"

(boolean)
----some_boundary_delimiter_string
Content-Disposition: form-data; name="apns_cert_development"; filename="certificate_file.p12"
Content-Type: application/x-pkcs12

(certificate)
----some_boundary_delimiter_string--

Note: If you find that you cannot upload a APNS push certificate from the Platform API or Dashboard, you may be experiencing buggy behavior caused by the KeyChain application on Mac OS X.

If you use a single .csr file (the very first file that you upload to the Apple Developer Account page), you receive the same .cer file even when requesting separate files for Development and Production stages.

To solve this problem, generate another .csr file and upload it to your Apple Developer Account. Then, retry the .p12 generation steps that you followed before, and try uploading the newly generated .p12 file to SendBird.

Status: 200 OK
{
    "push_configurations": [
        {
            "id": "065c7f1c0e98b9eac8792e7da9211ce30e3923f1"
        }
    ]
}
Property name Type Description
push_configurations list A list of push configurations.
push_configurations.id string A unique ID that identifies the push configuration. This value is automatically generated by SendBird.

List push configurations

Returns a list of an application's registered push configurations. push_type is either gcm or apns.

GET https://{region_identifier}.sendbird.com/v3/applications/push/{push_type}
Status: 200 OK
{
    "push_configurations": [
        {
            "gcm_api_key": "BBBBEEuCTTE:APA91bE8HPMm-xQa5RT4RaPXi-UdmGNfjDUAaFRryNbth7k4uLZGK9TufYqZXLBf82I3DHyH-L5QlNef1t60WxocozV3uWIRQkESW69XgKyrRQEBH8vKlE9C5rkDtUJDFavEgFmiICvw",
            "push_type": "GCM",
            "id": "fbdd6d0071217ac71b5d8acab65d615cfab3f7b1",
            "gcm_sender_id": "69982227377"
        },
        {
            "gcm_api_key": "CCCCEEuCTTE:APA91bE8HPMm-xQa5RT4RaPXi-UdmGNfjDUAaFRryNbth7k4uLZGK9TufYqZXLBf82I3DHyH-L5QlNef1t60WxocozV3uWIRQkESW69XgKyrRQEBH8vKlE9C5rkDtUJDFavEgFmiICvw",
            "push_type": "GCM",
            "id": "065c7f1c0e98b9eac8792e7da9211ce30e3923f1",
            "gcm_sender_id": "69981117377"
        }
    ]
}
Property name Type Description
push_configurations list A list of push configurations.

Delete the push configuration

Deletes the application's push configuration. push_type is either gcm or apns.

DELETE https://{region_identifier}.sendbird.com/v3/applications/push/{push_type}/{push_configuration_id}
Status: 200 OK
{
    "push_configurations": [
        "7757a4d45610dfb0c772f14134610c6ff3121e59"
    ]
}
Property name Type Description
push_configurations list A list of push configurations (as strings).

View an API token

Returns information of an API token.

Note: You cannot view information of other API token unless requesting with a Master API token.

GET https://{region_identifier}.sendbird.com/v3/applications/api_tokens/{api_token}
Status: 200 OK
{
    "token": "0123456789abcdef01234567890abcdef0123456",
    "created_at": 1500000000000
}

Revoke the API token

Revokes the API token.

Note: You cannot revoke other API token unless requesting with a Master API token.

DELETE https://{region_identifier}.sendbird.com/v3/applications/api_tokens/{api_token}
Status: 200 OK
{}

Issue an API token

Issues an API token.

Note: Only a request with Master API token can issue API token.

You can issue new API token with a Master API token, separate or revoke an existing API token, and manage up to 10 API tokens. With new API token, you can use most of Platform APIs as the Master API token can do, except for managing other API tokens. (Maximum number of additional API tokens is 10, which means you can have 11 API tokens including Master API token.)

POST https://{region_identifier}.sendbird.com/v3/applications/api_tokens
Status: 200 OK
{
    "token": "0123456789abcdef01234567890abcdef0123456",
    "created_at": 1500000000000
}

List API tokens

Returns a list of API tokens issued.

Note: Only a request with Master API token can list up API tokens.

GET https://{region_identifier}.sendbird.com/v3/applications/api_tokens/
Status: 200 OK
{
    "api_tokens": [
        {
            "token": "0123456789abcdef01234567890abcdef0123456",
            "created_at": 1500000001234
        },
        {
            "token": "abcdef0123456789abcdef01234567890abcdef0",
            "created_at": 1500000000000
        }
    ]
}