Business Messaging Guide v2
Business Messaging
Version 2

Business Messaging Platform APIs

Copy link

Sendbird Business Messaging API allows you to directly interact with data resources associated with notification activities in your Sendbird application. The Business Messaging API is designed to use standard HTTP protocols and return JSON payloads in response to HTTP requests. It's internally implemented based on the RESTful principles. While Sendbird Chat UIKit for Business Messaging handles many of the requests and responses at the client side, the API allows for more flexibility and adds more functionalities to your service from the server side.

Sendbird Business Messaging currently supports only one API endpoint to send a notification. After creating and designing a template in Sendbird Dashboard, you can send the notification to up to 10,000 users.

Note: The Business Messaging API is not designed for client-side use. Use Sendbird Chat UIKit for Business Messaging instead.


Base URL

Copy link

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

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

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


Headers

Copy link

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

Content-Type: application/json; charset=utf8
Api-Token: {notifications_api_token}
  • Content-Type: every request must include a Content-Type header.
  • Api-Token: The Business Messaging API token is required for the Sendbird server to authenticate your API requests.

Authentication

Copy link

Your API requests must be authenticated by the Sendbird server using the API token of your Sendbird application. For this, you can use the Business Messaging API token in your dashboard under Settings > Business Messaging > Authentication, which is generated when an application has been created. The Business Messaging API token can be revoked or changed only by Sendbird upon request.

"Api-Token": {notifications_api_token}

Note: Do not send any Business Messaging API requests from your app. If your API token information is leaked in the process of exchanging data, you could lose all your data by malicious API calls.


Actions

Copy link

API endpoints are relative to the base URL allocated to your application. In this page, the /notifications endpoint refers to https://api-{application_id}.notifications.sendbird.com.

Note: To get 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 URL encoded, such as {template.key}.

List of actions

Copy link
ActionHTTP request

Send a notification

POST /v1/notifications/messages
Sends a notification in real-time to a specific notification channel.

Send a batch of notifications with a CSV file

POST /v1/storage/targets_files/{file_key}/presigned_urls
Generate a pre-signed URL.
POST /v1/notifications/messages
Sends a notification message to a mass of target users specified in the CSV file.

List target files

GET /v1/storage/targets_files
Lists all target files.


Error response

Copy link

This section contains the list of error codes and responses for Notification's Platform API calls.

  • Error response: a JSON format which is used for the Sendbird server to send an error response to a client's request.

  • Error codes: HTTP status of each error with the corresponding error detail. Error codes in the 4xx range indicate a client-side error while codes in the 5xx range indicate a Sendbird server-side error.

Error response

Copy link

All errors return a 200, 400, or 500 HTTP response. The details of each error are included in the message field.

{
    "error": boolean,
    "code": int,
    "message": string
}

List of error properties

Copy link
Property nameTypeDescription

error

boolean

Indicates an error has occurred.

code

int

Indicates a 200, 400, or 500 HTTP response of an error.

message

string

The description of an error.

Error codes

Copy link

The following table lists client or server-side errors that the Business Messaging API returns in response to calls. For more information, see Error codes for Platform API for Sendbird Chat.

HTTP status codeError detail

207
(partial success)

207100 (PartialSuccess)
Part of the request failed using the single mode.

400
(bad request)

400111 (InvalidValue)
The request failed because it exceeded 10 target users which is the maximum number for single mode.

400
(bad request)

400111 (InvalidValue)
The request failed because it exceeded 10,000 target users which is the maximum number for multi mode.

400
(bad request)

403100 (PermissionDenied)
The request failed because the API token doesn’t have permission to request this API.

400
(bad request)

403101 (ServiceDoesNotActivated)
The request failed because Sendbird Business Messaging isn't turned on.