Notifications Guide v1
Notifications
Version 1

Notification logs

Copy link

Logs contain the holistic data on notifications and notification messages a target user receives. As for notifications, a Notification overview resource and Notification details resource contain information on how many notification messages have been sent out, when the notification arrived at the target user's channel, and how many users have clicked the message. Meanwhile, you can also retrieve all the Notification messages that a single target user has received from a specified time point.

These figures also can be monitors in the Logs page on Sendbird Dashboard.


Resource representation

Copy link

Depending on the call, a response may contain different resources as follows.

Notification overview

Copy link

A Notification overview resource contains general information on a notification. The following fields will be included in the response when you send a request for a list of Notification logs.

NameTypeDescription

notification_id

string

The unique ID of the notification.

template_key

string

The template key of the notification.

channels

array of object

A list of notification channels.

channels[*].key

string

The key of the channel.

channels[*].type

string

The type of the channel.

mode

string

The delivery mode of the notification. Options: real-time, batch.

title

string

The title of the notification. If not specified, the value is null.

tag

string

The tag of the notification that's used to send the notification. If not specified, the value is null.

sent_from

nested object

The entity that requested sending the notification.

sent_from.type

string

The type of entity sent the notification. Options: api, dashboard, clevertap, braze.

sent_from.value

string

Masked API token or an email-formatted Sendbird user ID, depending on sent_from.type.

metrics

nested object

The metrics data of the batch notifications. If mode is real-time, this value is null.

metrics.requested

integer

The number of requested notifications. If not aggregated yet, the value is null.

metrics.sent

integer

The number of sent notifications. If not aggregated yet, the value is null.

metrics.impressions

integer

The number of impressions for the notification. If not aggregated yet, the value is null.

metrics.clicked

integer

The number of clicks for the notification. If not aggregated yet, the value is null.

metrics.aggregated_at

integer

The timestamp in milliseconds when the metrics were newly aggregated. If not yet, the value is null.

created_at

integer

The timestamp in milliseconds when the notification was requested.

Notification details

Copy link

A Notification details resource contains more detailed information on a notification, such as its push notification settings, on top of the Notification overview resource. The following fields will be included in the response when you send a request for a single Notification log.

NameTypeDescription

push_template

nested object

The template for a push notification.

push_template.title

string

the title of the push notification.

push_template.body

string

the body of the push notification.

push_template.enable_push

boolean

Specifics whether to send a push notification.

fallback_message

string

The message that's used as the last notification when displaying the notification preview in a channel list.

priority

string

the priority of the notification, only supported in batch mode. Valid values are high, normal, and low.

Notification message

Copy link

A Notification message is an actual message that an end user receives as a result of a notification you've sent. Thus, the Notification message resource contains more data on the message and message event that each target user received. This is returned when requesting user logs.

NameTypeDescription

notification_id

string

The unique ID of the notification.

template_key

string

The template key of the notification.

channel

nested object

The channel of the notification.

channel.key

string

The key of the channel.

channel.type

string

The type of the channel.

mode

string

The delivery mode of the notification. Options: real-time, batch.

title

string

The title of the notification. If not specified, the value is null.

tag

string

The tag of the notification. If not specified, the value is null.

priority

string

The priority of the batch notification. Options: high, normal, low.

message_data

nested object

The data for the notification.

message_data.message_status

string

The status of the notification message. Valid values are SENT and READ.

message_data.channel_url

string

The unique URL of the channel where the message is sent to.

message_data.label

string

The label of the notification.

message_data.template_variables

nested object

The template variables used to send the notification.

message_data.event_logs

nested object

The event logs for the notification message.

message_data.event_logs.sent_at

long

Timestamp in milliseconds when the notification message was sent.

message_data.event_logs.impression_at

long

Timestamp in milliseconds when the notification message was marked as impression. (Default: 0)

message_data.event_logs.clicked_at

long

Timestamp in milliseconds when the notification message was marked as clicked. (Default: 0)

message_data.custom_event_logs

nested object

The custom event logs for the notification message.

message_data.custom_event_logs.{topic}

long

Timestamp in milliseconds when the notification message was marked by custom event topic.


Get a notification log

Copy link

This API retrieves all the logs on a single notification.

HTTP Request

Copy link
GET https://api-{application_id}.notifications.sendbird.com/v1/notifications/{notification_id}

Request body

Copy link
RequiredTypeDescription

notification_id

string

Specifies the unique ID of the notification to retrieve.

Response

Copy link

If successful, this action returns a Notification details resource in the response body.

{
    "notification_id": "7150392258387348737",
    "template_key": "template-01",
    "channels": [
        {
            "key": "shipt-demo-01",
            "type": "feed"
        }
    ],
    "mode": "batch",
    "title": "Batch Test 01",
    "tag": "",
    "sent_from": {
        "type": "dashboard",
        "value": "tyler.hammer@sendbird.com"
    },
    "metrics": {
        "requested": 2,
        "sent": 0,
        "impressions": 0,
        "clicked": 0,
        "aggregated_at": null
    },
    "created_at": 1704786362279,
    "push_template": {
        "title": "New Promotion Available",
        "body": "A new promotion is available! ",
        "enable_push": true
    },
    "fallback_message": "New Promotion Available",
    "priority": "normal"
}

List notifications

Copy link

This API retrieves all the logs on notifications that meet the specified conditions.

HTTP Request

Copy link
GET https://api-{application_id}.notifications.sendbird.com/v1/notifications

Request body

Copy link
OptionalTypeDescription

mode

string

Specifies the delivery mode of the notification. Required/Optional. Acceptable values are realtime and batch.

filter_by

string

Specifies the name of the property to apply filtering.

template_keys

string

Specifies a comma-separated string of one or more template keys to retrieve. Effective when filter_by is set to template_keys.

channel_keys

string

Specifies a comma-separated string of one or more channel keys to retrieve. Effective when filter_by is set to channel_keys.

tags

string

Specifies a comma-separated string of one or more tags to retrieve. Effective when filter_by is set to tags.

title

string

Specifies the title of the notification to retrieve. Effective when filter_by is set to title.

title_startswith

string

Specifies the prefix of the notification title to retrieve. Effective when filter_by is set to title_startswith.

start

integer

Specifies the start timestamp in milliseconds of the logs to retrieve. (Default: 0)

end

integer

Specifies the end timestamp in milliseconds of the logs to retrieve. (Default: current time)

limit

integer

Specifies the number of results to return per page. Acceptable values are 1 to 20, inclusive. (Default: 10)

reverse

boolean

Determines whether to sort the results in reverse chronological order. (Default: false)

token

string

Specifies a page token indicating the starting index of a chunk of results. If not specified, the index is set as 0.

Response

Copy link

If successful, this action returns a list of Notification overview resources in the response body.

{
    "notifications": [
        {
            "notification_id": "7150392258387348737",
            "template_key": "template-01",
            "channels": [
                {
                    "key": "shipt-demo-01",
                    "type": "feed"
                }
            ],
            "mode": "batch",
            "title": "Batch Test 01",
            "tag": "",
            "sent_from": {
                "type": "dashboard",
                "value": "tyler.hammer@sendbird.com"
            },
            "metrics": {
                "requested": 2,
                "sent": 0,
                "impressions": 0,
                "clicked": 0,
                "aggregated_at": null
            },
            "created_at": 1704786362279
        },
        {
            "notification_id": "7150383783817091713",
            "template_key": "template-03",
            "channels": [
                {
                    "key": "shipt-demo-01",
                    "type": "feed"
                }
            ],
            "mode": "realtime",
            "title": "NotificationsReview#2Demo",
            "tag": "test",
            "sent_from": {
                "type": "dashboard",
                "value": "tyler.hammer@sendbird.com"
            },
            "metrics": null,
            "created_at": 1704784341818
        },
        ...
    ],
    "next": "GEcZAVpOGlsES1cGXxwR"
}

Delete a notification

Copy link

This API allows you to delete a notification and its messages from the target user's channels. Notification deletion can also be performed on the Notifications tab on the Logs page on Sendbird Dashboard and this requires the logs' All permission. To learn more, see the Custom roles and permissions page,

Note: Message deletion is not processed and reflected in real-time.

HTTP Request

Copy link
DELETE https://api-{application_id}.notifications.sendbird.com/v1/notifications/{notification_id}/

Request body

Copy link
RequiredTypeDescription

notification_id

array of strings

Specifies the notification ID to delete a notification.

Response

Copy link

If successful, this action returns an empty body.