Send a notification in real-time

This API is used to send a notification to a single user through either a Feed or Chat notification channel. You should call this API if you only have one recipient. The notification will be sent in real-time to one target user by setting mode to realtime.

For batch notifications, refer to this page.

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`: To learn more about batch mode, refer to this page.
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`.

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

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