Send a notification through Platform API

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.

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.

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.

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.

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

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.

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

If successful, this action returns the following:

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

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.

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

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,[email protected],25,M
user-2,[email protected],30,F
user-3,[email protected],30,F

--{boundary}--

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/messages

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

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

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
}

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

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

The following table lists the parameters that this action supports.

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