Send a notification

This API is used to send a notification to either a Feed or Chat notification channel.

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.
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.
targets	array of strings	Specifies the user IDs of target users to send the notification to.

Optional	Type	Description
mode	string	Specifies which mode to send the notification in depending on the number of recipients. - `auto` (default): Sendbird decides which mode to send the notification depending on the number of target users. - `single`: The number of recipients is less than ten and the notification is sent directly to the target users in real-time. - `multi`: The number of recipients is greater than ten and less than 10,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.
notification_group	string	Specifies a key that aggregates notifications into one group. This key is used in the Notifications log page on Sendbird Dashboard to manage multiple notifications as one notification group.
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`.
channel_key	string	Specifies the key of the target channel to send the notification to.
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.

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.

Request body example

{
    "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"
                }
            },
            "user-2@sendbird.com": {
                "user_name": "Jane",
                "navigation_bar": {
                    "url": "https://example.com/image2.png",
                    "width": "800",
                    "height": "800"
                }
            }
        }
    },
    "targets": ["user-1@sendbird.com", "user-2@sendbird.com"],
    "mode": "auto",
    "notification_group": "marketing-20230305",
    "push_template": {
        "title": "push title",
        "body": "push body",
        "enable_push": true
    },
    "channel_key": "channel template key",
    "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.