Business Messaging Server Side v2

Business Messaging

Version 2

Send a notification through Platform API

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

Notification mode

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.

Send a notification

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

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

Request body

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

Properties

Required	Type	Description
template	nested object	Specifies the template used to send the notification.
template.key	string	Specifies the key of the template that's 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.

Optional	Type	Description
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.
push_template	nested object	Specifies the template for a push notification that overrides the default push notification settings in Sendbird Dashboard.
push_template.title	string	Specifies the title in the push notification template. This is a required property if you wish to configure `push_template`.
push_template.body	string	Specifies the body in the push notification template. This is a required property if you wish to configure `push_template`.
push_template.enable_push	bool	Determines whether to send a push notification. This is a required property if you wish to configure `push_template`.
fallback_message	string	Specifies a message that's used as the last notification when displaying the notification preview in a channel list. It's also used as an alternative text when a notification could not be displayed properly.
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

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 type	Description
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`.

RealtimeBatch

{
    "template": {
        "key": "my-first-template",
        "variables": {
            "user-1@sendbird.com": {
                "user_name": "Jasmine",
                "navigation_bar": {
                    "url": "https://example.com/image1.png",
                    "width": "800",
                    "height": "800"
                }
            }
        }
    },
    "mode": "realtime",
    "targets": ["user-1@sendbird.com"],
    "push_template": {
        "title": "push title",
        "body": "push body",
        "enable_push": true
    },
    "fallback_message": "Your order has been shipped."
}

Response

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

Send a batch of notification messages with a CSV file

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.

Step 1 Generate a pre-signed URL

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

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

Parameters

The following table lists the parameter that this action supports.

Required

Parameter name	Type	Description
file_key	string	Specifies the unique identifier of the file.

Request body

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

Properties

Optional	Type	Description
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

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.

Status: 200 OK

{
  "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

Property name	Type	Description
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

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

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

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

Multipart request

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.

HTTP

--{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}--

Python request example

import requests

app_id = "<YOUR_APP_ID>"
api_token = "<YOUR_NOTIFICATION_API_TOKEN>"
file_key = "<YOUR_FILE_KEY>"
csv_file = """user_id,attr.email,attr.age,attr.gender
user-1,user-1@sendbird.com,25,M
user-2,user-2@sendbird.com,30,F
"""

# 1. Generate a pre-signed URL for uploading a CSV file
response = requests.post(
    f"https://api-{app_id}.notifications.sendbird.com/v1/storage/targets_files/{file_key}/presigned_urls",
    headers={"Api-Token": api_token},
)

url: str = response.json()["url"]
fields: dict = response.json()["fields"]

# 2. Upload a CSV file to the pre-signed URL
response = requests.post(
    url,
    files={
        **{key: (None, value) for key, value in fields.items()},
        "file": (None, csv_file, "text/csv"),
    },
)

Step 3 Send a notification to users in the CSV file

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

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

Request body

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

Properties

Required	Type	Description
template	nested object	Specifies the template used to send the notification.
template.key	string	Specifies the key of the template that's used to send the notification.
mode	string	Specifies which mode is used to send the notification, depending on the number of recipients. - `batch`: The number of recipients is greater than one and less than 100,000. The notification isn't sent in real-time but it can be sent to a large group of target users at once without running into rate limit issues. - `realtime`: There's only one recipient and the notification is sent directly to the target user in real-time. To learn more about real-time mode, refer to this page.
targets_filename	string	Specifies the name of a CSV file containing target user IDs to send the notification to. You can only use this property when the `mode` is set to `batch`. It's also a required property if `targets` is not specified. To learn more about CSV file specifications, refer to How to create a CSV file below.

Optional	Type	Description
push_template	nested object	Specifies the template for a push notification that overrides the default push notification settings in Sendbird Dashboard.
push_template.title	string	Specifies the title in the push notification template. This is a required property if you wish to configure `push_template`.
push_template.body	string	Specifies the body in the push notification template. This is a required property if you wish to configure `push_template`.
push_template.enable_push	bool	Determines whether to send a push notification. This is a required property if you wish to configure `push_template`.
fallback_message	string	Specifies a message that's used as the last notification when displaying the notification preview in a channel list. It's also used as an alternative text when a notification could not be displayed properly.
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.

How to create a CSV file

You can send notifications to multiple recipients by importing a CSV file containing user information. The maximum number of users you can have in a single CSV file is 100,000. See the following CSV file formatting requirements:

The first row in the file must have column names.
Only alphabets, numbers, underscores, hyphens, and periods are allowed in column names.
One column must be named user_id and it must contain user IDs of the target recipients.

You can add more columns to the file that contain user information such as user name, nickname, or even image URLs. These additional user information need to be the value for each variable key that you set in the template. If you wish to import images, each image must have the same width and height in order to be displayed properly.

Response

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

List target files

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

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Optional

Parameter name	Type	Description
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

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.

Status: 200 OK

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

List of response properties

Property name	Type	Description
files[]	array of objects	An array of files 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.

On this page

Send a notification

HTTP request Request body Response

Send a batch of notification messages with a CSV file

Step 1 Generate a pre-signed URL Step 2 Upload a CSV file Step 3 Send a notification to users in the CSV file

List target files

HTTP request Parameters Response