Customizing Notifications

Push delivery rules, providers and device registration are documented in the Push Notification documentation; this page covers notification templates. Once push notifications are enabled for your app, you can customize the templates to match your app’s needs. This lets you control how notifications appear on users' devices. You can do this through the dashboard or via the API, as shown below:

Enabling and Customizing Push Templates

The Upsert Push Template REST endpoint allows you to enable push notifications notification type and optionally define custom templates. Supported event types include message.new, message.updated, reaction.new and more.

Following is a sample payload for enabling push notifications with default template:

{
  "enable_push": true,
  "event_type": "message.new",
  "push_provider_type": "apn",
  "push_provider_name": "apn"
}

Following is a sample payload for enabling push notifications with custom template:

{
  "enable_push": true,
  "event_type": "message.new",
  "push_provider_type": "firebase",
  "push_provider_name": "firebase",
  "template": "{\"data\":{\"version\":\"v2\",\"sender\":\"stream.chat\",\"type\":\"{{ event_type }}\",\"id\":\"{{ message.id }}\",\"message_id\":\"{{ message.id }}\",\"channel_type\":\"{{ channel.type }}\",\"channel_id\":\"{{ channel.id }}\",\"cid\":\"{{ channel.cid }}\",\"receiver_id\":\"{{ receiver.id }}\"},\"android\":{\"priority\":\"high\"},\"apns\":{\"payload\":{\"aps\":{\"alert\":{\"title\":\"New message from {{ sender.name }}\",\"body\":\"{{ truncate message.text 150 }}\"},\"badge\":{{ unread_count }},\"sound\":\"default\",\"mutable-content\":1,\"content-available\":0}}}}"
}

Available Fields:

Default Templates

Push v3 supports templating for both Firebase and APNs. Configuring templates is optional — if no custom templates are provided, Stream will automatically use the default templates for Firebase and APNs.

Firebase default template

{
  "data": {
    "version": "v2",
    "sender": "stream.chat",
    "type": "{{ event_type }}",
    "id": "{{ message.id }}",
    "message_id": "{{ message.id }}",
    "channel_type": "{{ channel.type }}",
    "channel_id": "{{ channel.id }}",
    "cid": "{{ channel.cid }}",
    "receiver_id": "{{ receiver.id }}"
  },
  "android": {
    "priority": "high"
  },
  "apns": {
    "payload": {
      "aps": {
        "alert": {
          "title": "New message from {{ sender.name }}",
          "body": "{{ truncate message.text 150 }}"
        },
        "badge": {{ unread_count }},
        "sound": "default",
        "mutable-content": 1,
        "content-available": 0
      }
    }
  }
}

By default, there is only a data message and no notification field in the android payload.

If a template is set, then the template will be processed and put into the notification key in the payload. To see available fields and their description please follow FCM documentation.

Following is a sample android template with notification:

{
  "android": {
    "notification": {
      "title": "{{ sender.name }} @ {{ channel.name }}",
      "body": "{{ truncate message.text 150 }}",
      "click_action": "OPEN_ACTIVITY_1",
      "sound": "default"
    },
    "priority": "high"
  }
}

APN default template

{
  "payload": {
    "aps": {
      "alert": {
        "title": "You have a new message",
        "body": "{{ truncate message.text 150 }}"
      },
      "badge": {{ unread_count }},
      "sound": "default",
      "mutable-content": 1,
      "content-available": 0
   },
    "stream": {
      "version": "v2",
      "sender": "stream.chat",
      "type": "{{ event_type }}",
      "id": "{{ message.id }}",
      "cid": "{{ channel.cid }}",
      "receiver_id": "{{ receiver.id }}"
    }
  }
}

Context Variables

For both Firebase and APN, the payload that is being sent is rendered using the handlebars templating language, to ensure full configurability for your app.

Stream provides the following variables in the template rendering context:

Limitations

There are some limitations that Stream imposes on the push notification handlebars template to make sure no malformed payloads are being sent to push providers.

1: Custom Arrays Can't Be Indexed

For example, given the context:

{
  "sender": {
    "name": "Bob",
    "some_array": ["foo", "bar"]
  }
}

And the template:

"title": {{ sender.some_array.[0] }}

The rendered payload will be:

"title": ""

2: Interpolating Whole Lists and Objects Isn't Allowed

For example, given the context:

{
  "sender": {
    "name": "bob",
    "some_array": ["foo", "bar"],
    "address": {
      "street": "willow str"
    }
  }
}

And the template:

"title": "{{ sender.some_array }} {{ sender.address }}"

The rendered payload will be:

"title": "[] {}"

3: Unquoted fields that aren't in the context will be rendered as empty strings

For example, given the context:

{
  "sender": {
    "name": "bob"
  }
}

And the template:

"title": {{ sender.missing_field }}

The rendered payload will be:

"title": ""

Advanced Use Cases

For advanced use cases (e.g. A list of channel members in the notification title, conditional rendering, etc), Stream provides some handlebars helper functions.

Helper Functions

Most of the functions above are straight forward, except for implodeMembers , which will be detailed further.

The full function signature is: {{implodeMembers otherMembers|members [limit=] [separator=] [nameField=] [suffixFmt=]}}

Function Parameters

Data-only push notifications

Data-only push notifications carry no UI alert—just a small key/value payload your app handles. Use them to poke the app to sync or fetch fresh data: send only a data payload (no notification body). On iOS, mark the APNs/FCM message as silent (content-available: 1) and delivery is opportunistic and not guaranteed. On Android, data messages go to your background handler; if work is long or the OS is aggressive, escalate priority and hand off to a foreground service. Keep payloads tiny and idempotent, and treat them as a trigger to fetch real content—not as a guaranteed delivery mechanism.

They are also particularly useful whenever we want to consume and display the notification ourselves, without involving the operating system directly.

Provided below is an example notification template configuration that we can use to allow for data-only notifications on both iOS and Android:

{
  "data": {
    "version": "v2",
    "sender": "stream.chat",
    "type": "{{ event_type }}",
    "id": "{{ message.id }}",
    "channel_type": "{{ channel.type }}",
    "channel_id": "{{ channel.id }}",
    "cid": "{{ channel.cid }}",
    "receiver_id": "{{ receiver.id }}",
    "my_custom_notification_body": "BODY: {{ truncate message.text 150 }}"
  },
  "android": {
    "priority": "high"
  },
  "apns": {
    "headers": {
      "apns-push-type": "background",
      "apns-priority": "5"
    },
    "payload": {
      "aps": {
        "content-available": 1
      },
      "stream": {
        "title": "New message from {{ sender.name }}",
        "body": "{{ truncate message.text 150 }}"
      }
    }
  }
}

Since we are no longer relying on apns.payload.aps.alert to control our body and title, we have to have a way to ingest it within our data. However, since both of these are blacklisted fields to set to our data object they have to be set in the stream object directly and used from there for these types of notifications.

Whenever crafting custom payload templates, it is very important to keep the version to v2, which is done for backwards compatibility reasons.

Another important part to understand is the fact that data-only push notifications must not exceed 4KB. Due to this, we have to be careful never to send the full payload (and only handpick certain parts of it that we need). We also have to be careful to truncate the text in the event of having very, very long messages whose text might go above this limit.

Examples

Let's put these helpers to use in a few examples:

Example 1

Rendering channel members in the notification title. Each member's name is stored in the  fullName  field.

What we want to achieve:

{
  "aps": {
    "alert": {
      "title": "Bob Jones, Jessica Wright, Tom Hadle and 4 other(s)",
      "body": "Bob Jones: Hello there fellow channel members"
    },
    "badge": 0
  }
}

How we will achieve it: using  implodeMembers  with a custom name field (leaving others empty so that defaults will be used):

{
  "aps": {
    "alert": {
      "title": "{{implodeMembers otherMembers nameField="fullName"}}",
      "body": "{{ sender.fullName }}: {{ message.text }}"
    },
    "badge": {{ unread_count }}
  }
}

Example 2

Rendering channel members in the notification title. Each member's name is stored in the  nested   details.name  field.

What we want to achieve:

{
  "aps": {
    "alert": {
      "title": "Bob Jones, Jessica Wright, Tom Hadle and 4 other(s)",
      "body": "Bob Jones: Hello there fellow channel members"
    },
    "badge": 0
  }
}

How we will achieve it: since  implodeMembers  doesn't support nested fields, we need to use a bunch of helpers such as  each , ifLte . Note how the use of  ~  will trim the whitespaces so that the title in rendered in a single row:

{
  "aps": {
    "alert": {
      "title": "
      {{~#each otherMembers}}
        {{#ifLte @index 2}}
          {{~this.details.name}}{{#ifLt @index 2 }}, {{/ifLt~}}
        {{~else if @last~}}
          {{{ " " }}} and {{remainder otherMembers 3}} other(s)
        {{~/ifLte~}}
      {{/each~}}",
      "body": "{{ sender.details.name }}: {{ message.text }}"
    },
    "badge": {{ unread_count }}
  }