Business Messaging Guide v2
Business Messaging
Version 2

Send a notification through Platform API

Copy link

These APIs are used to send a notification to either a single user or multiple users through an in-app notification channel. Depending on the number of recipients, the value of mode should differ: realtime and batch.

Note: Sendbird Business Messaging supports both v1 and v2 APIs. The v2 API is used for sending notifications, while the v1 API is used for other RESTful APIs.

Notification mode

Copy link

There are two types of notification mode, determined by the size of the recipients.

  • realtime: This mode targets a single user and the notification message will be sent in real time. The notification will be sent in real-time to one target user by setting mode to realtime.

  • batch: This mode targets a large group of users, specified with their user ID or in a CSV file. You should use batch mode if you have more than one and up to 100,000 target users. By setting mode to batch, you can send a notification at once without running into rate limit issues. When batch is specified, you can use either the targets property for up to 10,000 target users or upload a CSV file and specify its URL in the targets_filename property for up to 100,000 target users. To use a CSV file, you need to send a request to a separate endpoint. To learn more, refer to the dedicated set of instructions at the bottom of this page.

List of actions

Copy link
ActionHTTP request

Send a notification

Sends a notification in real-time to a specific notification channel.

* This request should be made to v2 API, while other RESTful APIs for Business Messaging are supported in v1.

Send a batch of notification messages with a CSV file

Sends a notification to multiple users using a CSV file.


Send a notification

Copy link

This API allows you to send a notification in either realtime or batch mode. If you wish to send a batch notification with targets_filename, see the Send a batch of notification messages with a CSV file section.

HTTP request

Copy link
POST https://api-{application_id}.notifications.sendbird.com/v1/notifications/messages

Note: This request should be made to API v2 while other RESTful APIs for Sendbird Business Messaging are supported in v1.

Request body

Copy link

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

template

nested object

Specifies the template used to send the notification.

template.key

string

Specifies the unique key of the template that will be used to send the notification.

mode

string

Specifies which mode is used to send the notification, depending on the number of recipients.
- realtime: There's only one recipient and the notification is sent directly to the target user in real-time.
- batch: There are multiple recipients of the notification and messages will be sent in a series of batches. To learn more about batch mode, refer to this section.

targets

array of strings

Specifies the user IDs of target users to send the notification to. If the value of mode is set to realtime, you can assign only one user ID to targets. If the value is batch, you can assign up to 10,000 user IDs to targets. When mode is batch, you can either use this field or targets_filename with a CSV file. To use a CSV file, refer to this section.

OptionalTypeDescription

template.variables

nested object

Specifies the customizable variables in a template.

template.variables.{user_id}

nested object

Specifies the user IDs to send the notification to and key-value items to store additional variables for each user ID. To learn more, refer to Template variables below.

template.notification_push_data

nested object

Specifies the custom key-value pairs to be included in the push notification. This can contain a maximum of five pairs.

priority

string

Specifies the delivery priority level of a batch notification. Acceptable values are high, normal, and low. (Default: normal)
* This is effective only when mode is set to batch.

title

string

Specifies the title used to send the notification. This field can be used as a label to organize and manage individual notifications.

tag

string

Specifies a key that groups notifications together. This key is used in the Analytics page on Sendbird Dashboard to sort and categorize notifications.

Template variables

Copy link

The variables that you set in the template need to be specified as key-value items for each user ID in the template.variables.{user_id} object. For every variable key, you need to assign the value in the request body. There are three types of variables: String, Image, and Action. See the table below on what variables you need to set in the request body.

Variable typeDescription

String

Specifies the texts used in the body of the template and the text buttons. These texts are subject to change each time the notification is sent.

Image

Specifies the images used in the template. These images are subject to change each time the notification is sent. Within the image variable, you need to assign values to the url, width, and height keys.

Action

Specifies the actions to execute when a UI component in the template is tapped on the mobile app. These actions are subject to change each time the notification is sent. Within the action variable, you need to assign values to the type and data keys. There are two types of action values to the variable key: web link and in-app link. For web link, you need to assign web to type and for in-app link, you need to assign custom to type.

RealtimeBatchBatch-CSV
{
    "template": {
        "key": "appointment-reminder",
        "variables": {
            "sendbird-user_1": {
                "name": "Bob Barker",
                "appointment_number": "32893"
            }
        },
        "notification_push_data": {  
          "key": "value1",
          "key2": "value2"
        }
    },
    "targets": ["sendbird-user_1"], 
    "mode": "realtime",
    "tag": "appointments",
    "title": "Appointment Reminder"
}

Response

Copy link

If successful, this action returns the following:

RealtimeBatch
{
    "notification_id": "7190607145580961921",
    "template_key": "appointment-reminder",
    "channels": [
        {
            "key": "message-center",
            "type": "feed"
        },
        {
            "key": "push",
            "type": "push"
        }
    ],
    "mode": "realtime",
    "title": "Appointment Reminder",
    "tag": "appointments",
    "sent_from": {
        "type": "api",
        "value": "************************************82aa"
    },
    "created_at": 1714374338539
}

Send a batch of notification messages with a CSV file

Copy link

If you aim to send a notification to up to 100,000 target users, set the notification mode to batch and use a CSV file to list up the recipients. In order to do so, first, generate a pre-signed URL and upload a CSV file containing all the user IDs. Follow the steps below.

How to create a CSV file

Copy link

You can send notifications to multiple recipients by importing a CSV file containing information on targets and template variables.

This CSV file must include the following information:

  • The first row must contain column names, such as user_id and your variable keys.
  • A column named user_id must be included, containing user_id for all recipients.
  • Variable keys and values corresponding to each recipient. They must match the keys set in the template.
  • Column names may only contain letters, numbers, underscores, hyphens, and periods.
  • Each CSV file must contain all variable keys and their values for each user ID.

Note: The maximum number of users you can have in a single CSV file is 100,000.

user_id,variable_key_1,variable_key_2
user-1,value-1,value-2
user-2,value-3,value-4
...

Step 1 Generate a pre-signed URL

Copy link

A CSV target file can only be uploaded when sending a notification in batch mode and you must generate a pre-signed URL for every CSV file before uploading it to the Sendbird server and sending a notification.

HTTP request

Copy link
POST https://api-{application_id}.notifications.sendbird.com/v1/storage/targets_files/{file_key}/presigned_urls

Parameters

Copy link

The following table lists the parameter that this action supports.

Required
Parameter nameTypeDescription

file_key

string

Specifies the unique identifier of the file.

Request body

Copy link

The following table shows the property of an HTTP request that this action supports.

Properties
OptionalTypeDescription

overwrite_duplicate_key

bool

Determines whether to overwrite the file_key when a file with the same key already exists in the server. If set to false, an error is returned when there's an existing file with the same key. (Default: false)

Response

Copy link

If successful, this action returns the following response properties. In the case of an error, an error object is returned. A detailed list of error codes is available here.

{
  "url": "https://mesg-notifications-usw2-prod.s3.amazonaws.com/",
  "fields": {
    "Expires": "2023-06-16T00:28:11.622661+00:00",
    "Content-Type": "text/csv",
    "key": "us-1/notification/AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA/bcaa7e5451712f755bcc93a14be59e24bb02b3ac",
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-credential": "XXXXXXXXXXXXXXXXXXXX/20230517/us-west-2/s3/aws4_request",
    "x-amz-date": "20230517T002811Z",
    "policy": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=",
    "x-amz-signature": "a06cce4764553c93b2dfdbd6ab14a586b3aa65464ca35a2270309df12f6b0dae"
  },
  "file_key": "notification-targets.csv"
}

List of response properties

Copy link
Property nameTypeDescription

url

string

The URL used to upload a file.

fields

object

Additional fields in the form of key-value pairs. They can include properties such as expires, content-type, key, x-amz-algorithm, x-amz-credential, x-amz-date, policy, and x-amz-signature. These properties should be passed as part of the subsequent HTTP POST request.

file_key

string

The unique identifier of the file.

In the case of an error, an error object is returned. A detailed list of error codes is available here.

Step 2 Upload a CSV file

Copy link

Once you've generated a pre-signed URL, you can now upload your CSV file containing a list of user IDs to the URL. When uploading the file, you need to send a multipart request. To learn more about CSV file specifications, see How to create a CSV file below.

Headers

Copy link

The multipart HTTP request to the Chat API must include the following header.

Content-Type: multipart/form-data; boundary={boundary}

Multipart request

Copy link

Since your request contains a file, you need to send the following multipart request. As shown in the example below, specify multipart/form-data and boundary, which is a delimiter string that separates each data field, in the Content-Type header.

HTTPPython request example
--{boundary}
Content-Disposition: form-data; name="Expires"

2023-06-16T00:28:11.622661+00:00
--{boundary}
Content-Disposition: form-data; name="Content-Type"

text/csv
--{boundary}
Content-Disposition: form-data; name="key"

us-1/notification/AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA/bcaa7e5451712f755bcc93a14be59e24bb02b3ac
--{boundary}
Content-Disposition: form-data; name="x-amz-algorithm"

AWS4-HMAC-SHA256
--{boundary}
Content-Disposition: form-data; name="x-amz-credential"

XXXXXXXXXXXXXXXXXXXX/20230517/us-west-2/s3/aws4_request
--{boundary}
Content-Disposition: form-data; name="x-amz-date"

20230517T011949Z
--{boundary}
Content-Disposition: form-data; name="policy"

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=
--{boundary}
Content-Disposition: form-data; name="x-amz-signature"

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
--{boundary}
Content-Disposition: form-data; name="file"
Content-Type: text/csv

user_id,attr.email,attr.age,attr.gender
user-1,user-1@sendbird.com,25,M
user-2,user-2@sendbird.com,30,F
user-3,user-2@sendbird.com,30,F

--{boundary}--

Step 3 Send a notification to users in the CSV file

Copy link

Once the file's been uploaded to the server, you can use the targets_filename property to send a notification to up to 100,000 users.

HTTP request

Copy link
POST https://api-{application_id}.notifications.sendbird.com/v1/notifications/messages

Note: This request should be made to API v2 while other RESTful APIs for Sendbird Business Messaging are supported in v1.

Request body

Copy link

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

template

nested object

Specifies the template used to send the notification.

template.key

string

Specifies the unique key of the template that will be used to send the notification.

mode

string

Specifies which mode is used to send the notification, depending on the number of recipients.
- realtime: There's only one recipient and the notification is sent directly to the target user in real-time.
- batch: There are multiple recipients of the notification and messages will be sent in a series of batches. To learn more about batch mode, refer to this section.

targets_filename

string

Specifies the unique FILE_KEY you've set in Step 1. To use this field, set the mode to batch.

OptionalTypeDescription

template.variables

nested object

Specifies the customizable variables in a template.

template.variables.{user_id}

nested object

Specifies the user IDs to send the notification to and key-value items to store additional variables for each user ID. To learn more, refer to Template variables below.

template.notification_push_data

nested object

Specifies the custom key-value pairs to be included in the push notification. This can contain a maximum of five pairs.

priority

string

Specifies the delivery priority level of a batch notification. Acceptable values are high, normal, and low. (Default: normal)
* This is effective only when mode is set to batch.

title

string

Specifies the title used to send the notification. This field can be used as a label to organize and manage individual notifications.

tag

string

Specifies a key that groups notifications together. This key is used in the Analytics page on Sendbird Dashboard to sort and categorize notifications.

Response

Copy link

If successful, this action returns a notification resource in the response body. In the case of an error, an error object is returned. A detailed list of error codes is available here.

{
    "notification_id": "7190607145580961921",
    "template_key": "appointment-reminder",
    "channels": [
        {
            "key": "message-center",
            "type": "feed"
        },
        {
            "key": "push",
            "type": "push"
        }
    ],
    "mode": "batch",
    "priority": "normal",
    "title": "Appointment Reminder",
    "tag": "appointments",
    "sent_from": {
        "type": "api",
        "value": "************************************82aa"
    },
    "created_at": 1714374338539
}

List target files

Copy link

You can retrieve a list of all uploaded target files in the Sendbird application using this API.

HTTP request

Copy link
GET https://api-{application_id}.notifications.sendbird.com/v1/storage/targets_files

Parameters

Copy link

The following table lists the parameters that this action supports.

Optional
Parameter nameTypeDescription

token

string

Specifies a page token that indicates the starting index of results to retrieve. If not specified, the index is set to 0.

limit

int

Specifies the number of results to return per page. Acceptable values are 1 to 100, inclusive. (Default: 100)

Response

Copy link

If successful, this action returns a list of files resources in the response body. In the case of an error, an error object is returned. A detailed list of error codes is available here.

{
    "files": [
        {
            "file_key": "notification-targets.csv",
            "file_size": 1024,
            "expires_at": 1686878790,
            "uploaded_at": 1684286791
        }
    ],
    "next": "YXEZR1VVQVErEUBXWFNeF2p3FkFVVA~~"
}

List of response properties

Copy link
Property nameTypeDescription

files[]

array of objects

An array of file resources.

files.file_key

string

Specifies the unique identifier of the file.

files.file_size

number

Specifies the size of the target file.

files.expires_at

long

The time at which the target file expires in Unix milliseconds format from the time of file uploading is complete. (Default: 30 days)

files.uploaded_at

long

The time at which the target file was uploaded through the pre-signed URL in Unix milliseconds format.

next

string

The value that can be used in the token parameter to retrieve the next page in the result set.