Template

A template is the base of the Campaign feature in Sendbird Chat. It is a pre-defined message structure that frames the notifications users receive through various channels, such as SMS, push notifications, and in-app channel messages. Templates are created and managed in the Sendbird Dashboard, and you can retrieve templates you've created using the APIs below.

Resource representation

The following tables show the lists of properties in a template resource. This section is divided into two tables: the first table lists the general properties of a template, and the second table lists the properties that are specific to certain channels.

General properties

Property	Type	Description
key	string	The unique ID of the template.
template_key	string	The template key.
name	string	The template name.
is_archived	boolean	Specifies whether templates are active or archived.
created_at	int	The timestamp when the template was created, in Unix milliseconds format.
updated_at	int	The timestamp when the template’s latest version was last updated, in Unix milliseconds format.
version	int	The version of the template.
channels[].key	string	The unique key of channel.
channels[].type	string	The type of channel. Valid values are `alimtalk`, `sms`, `whatsapp` and `push`.
channels[].name	string	The name of channel.
channels[].content	object	A JSON object that specifies channel’s content. This object is excluded in in-app channels. If title or body doesn’t have value, it returns an empty object.
variable_schema[].key	string	The key of template variable.
variable_schema[].type	string	The data type of template variable.
variable_schema[].name	string	The name of template variable.
sequence	object	The order of channels within the template that determines to which channel a notification should be sent to first.
sequence.steps[].channels[].key	string	The unique channel keys of the channels included in the template.
sequence.steps[].channels[].type	string	The channel types of the channels included in the template,

Channel-specific properties

The following tables show the properties that are specific to certain channels.

In-app channel	Type	Description
channels[].categories[].name	string	The names of categories that are used for the in-app channel.
channels[].data_type	string	States whether template is data template or ui template. Valid values are `data_template` and `ui_template`.
channels[].data_template.key	string	The key of a data template.
channels[].data_template.value	string	The value of data template.
channels[].ui_template.body	object	A JSON object that contains the details of the UI template if `channels[].data_type` is `ui_template`. If not used, it returns an empty object.
channels[].message_retention_hours	int	The hours that message is kept in the channel.
channels[].is_category_filter_enabled	boolean	Specifies whether category filter is enabled or not.
channels[].is_template_label_enabled	boolean	Specifies whether label filter is enabled or not.

SMS	Type	Description
channels[].category	string	If the channel is sms, valid values are either `SMS` or `LMS`.

WhatsApp and Kakao Alim Talk	Type	Description
channels[].approval_status	string	If the channel type is `alimtalk` or `whatsapp`, `approval_status` returns one of the following values: `approved`, `pending`,and `disapproved`.

Actions

API endpoints are relative to the base URL allocated to the application. For example, the /notifications endpoint refers to https://api-{application_id}.notifications.sendbird.com/v1.

Note: If you want to know the ID and base URL of your application, sign in to your dashboard, go to Settings > Application > General, and then check the Application ID and API request URL.

It's recommended that the parameter values in API URLs be urlencoded, such as {user_id} and {channel_url}.

List of actions

Action	HTTP request
List templates	`GET` /notifications/templates Retrieves a paginated list of templates created within one Sendbird application.
Get a template	`GET` /notifications/templates/{template_key} Retrieves a detailed view of a designated template.

List templates

This API retrieves a paginated list of templates created within one Sendbird application. It provides a general view to all templates within its database, enabling you to utilize the information in and out of the dashboard. You can filter the results by adding parameters that show templates with certain keys or channels, making it easier to search designated templates.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Optional

Parameter name	Type	Description
order	string	Specifies the orders the template list by either `created_at` or `updated_at` timestamps.
reverse	boolean	Specifies the sorting order. If set to `true`, the order is descending while `false` ascending. (Default: `false`)
channel_key	string	Filters templates containing the specified channel key.
is_archived	boolean	Filters templates based on archive status. If not specified, it returns templates of all statuses.
keys	Comma-separated Strings	Filters templates by specific keys. An example can be `&keys=key1,key2`.
name_contains	string	Filters templates with the names containing the specified value.
key_contains	string	Filters templates with the keys containing the specified value.
category_id	int	Filters templates by the specified category ID.
limit	int	Limits the number of results per page. Acceptable values range from 1 to 100. (Default: `10`)
token	string	Pagination token from the previous response to fetch the next chunk of results.

Response

If successful, this action returns a list of template resources in the response body like the following:

Status: 200 OK

{
    "templates": [
        {
            "key": "promo1",
            "name": "Black Friday Promotion",
            "is_archived": false,
            "channels": [
                {
                    "key": "kakaotalk",
                    "type": "alimtalk",
                    "name": "kakao talk-target"
                }
            ]
        },
                {
            "key": "promo2",
            "name": "Cyber Monday Promotion",
            "is_archived": false,
            "channels": [
                {
                    "key": "whatsapp",
                    "type": "whatsapp",
                    "name": "whatsapp-brand"
                }
            ]
        },
        ...
    ]
}

Error

In the case of an error, an error object is returned.

Status: 400 Bad Request

{
    "code": 400111,
    "message": "Not valid value",
    "errors": [
        {
            "property": "property_name",
            "message": "Not valid value"
        }
    ]
}

Get a template

This API lets you fetch a detailed view of a designated template. This provides you with an in-depth view of a single template, enabling easier usage of templates.

HTTP request

GET https://api-{application_id}.notifications.sendbird.com/v1/notifications/templates/{template_key}

Parameters

The following table lists the parameters that this action supports.

Required	Type	Description
template_key	string	Specifies the unique key of the template to retrieve.

Optional	Type	Description
version	int	Narrows the search scope to the templates with the specified version.

Response

If successful, this action returns a template resource in the response body like the following:

Status: 200 OK

{
    "key": "payload-test",
    "name": "payload-test",
    "created_at": 1726734831843,
    "updated_at": 1726734831843,
    "is_archived": false,
    "version": 2,
    "sequence": {
        "steps": [
            {
                "channels": [
                    {
                        "key": "data",
                        "type": "feed"
                    },
                    {
                        "key": "push",
                        "type": "push"
                    }
                ]
            },
            {
                "channels": [
                    {
                        "key": "kakao",
                        "type": "alimtalk"
                    }
                ]
            },
            {
                "channels": [
                    {
                        "key": "sms-korea",
                        "type": "sms"
                    }
                ]
            }
        ]
    },
    "variable_schema": [
        {
            "key": "booking_number",
            "type": "string",
            "name": "booking_number01"
        },
        {
            "key": "booking_date",
            "type": "string",
            "name": ""
        }
    ],
    "channels": [
        {
            "key": "data",
            "type": "feed",
            "data_type": "data_template",
            "message_retention_hours": 4320,
            "categories": [
                {
                    "name": "All"
                }
            ],
            "is_category_filter_enabled": false,
            "is_template_label_enabled": true,
            "data_template": [
                {
                    "key": "key",
                    "value": "value"
                }
            ],
            "ui_template": {}
        },
        {
            "key": "push",
            "type": "push",
            "content": {
                "title": "title",
                "body": "body",
                "data": {}
            }
        },
        {
            "key": "kakao",
            "type": "alimtalk",
            "content": {
                "templateContent": "Payment completed",
                "templateMessageType": "BA",
                "templateEmphasizeType": "NONE",
                "templateTitle": null,
                "templateSubtitle": null,
                "templateHeader": null,
                "templateItem": null,
                "templateItemHighlight": null,
                "templateImageName": null,
                "templateImageUrl": null,
                "buttons": null
            },
            "approval_status": "approved"
        },
        {
            "key": "sms-korea",
            "type": "sms",
            "category": "SMS",
            "content": {
                "title": "",
                "body": "test body"
            }
        }
    ]
}

Error

In the case of an error, an error object is returned.

Status: 400 Bad Request

{
    "code": 400201,
    "message": "Not found",
    "errors": [
        {
            "property": "template_key",
            "message": "Not found"
        }
    ]
}

On this page

Resource representation

General properties Channel-specific properties

Actions List templates

HTTP request Parameters Response

Get a template

HTTP request Parameters Response