Send a batch of notifications using a CSV file

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.

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.

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.

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

The following table lists the parameter that this action supports.

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

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

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

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.

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

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

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"),
    },
)

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.

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

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

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.

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.