Version 1
Home
/
Notifications
/
API
Notifications v1
Notifications

Send a batch of notifications using a CSV file

Copy link

This API is used to send a notification to multiple users through either a Feed or Chat notification channel. You should call this API 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 the targets_filename property for up to 100,000 target users. See the guide below on how to use targets_filename to send a notification.

For real-time notifications, refer to this page.


Get started

Copy link

In order to send a batch of notifications using a CSV file, you need to 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

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.

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

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

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 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: 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.

OptionalTypeDescription

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.

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

Copy link

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

Copy link

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.