Push Templates

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:

Context Variables

Defaults

v1

When editing APN/Firebase settings, if you leave the notification_template or data_template field empty, default templates will be used.

v2

Editing data template is forbidden. There is no default for notification_template, it’s sent only if set. apn_template is introduced for apn templating under firebase.

APN default (v1):

{
  "aps" : {
    "alert": {
      "title": "{{ sender.name }} @ {{ channel.name }}",
      "body": "{{ truncate message.text 2000 }}"
    },
    "badge": {{ unread_count }},
    "category": "NEW_MESSAGE"
  },
  "stream": {
    "sender": "stream.chat",
    "type": "message.new",
    "version": "v1",
    "id": "{{ message.id }}",
    "cid": "{{ channel.cid }}"
  }
}

Firebase default notification template (v1):

{
  "title": "{{ sender.name }} @ {{ channel.name }}",
  "body": "{{ truncate message.text 2000 }}",
  "click_action": "OPEN_ACTIVITY_1",
  "sound": "default"
}

Firebase default data template (v1):

{
  "sender": "{{ sender.id }}",
  "channel": {
    "type": "{{ channel.type }}",
    "id": "{{ channel.id }}"
  },
  "message": "{{ message.id }}"
}

APN default and Firebase default APN template (v2):

{
  "aps": {
    "alert": {
      "title": "New message from {{ sender.name }}",
      "body": "{{ truncate message.text 2000 }}"
    },
    "mutable-content": 1,
    "category": "stream.chat"
  },
  "stream": {
    "sender": "stream.chat",
    "type": "message.new",
    "version": "v2",
    "id": "{{ message.id }}",
    "cid": "{{ channel.cid }}"
  }
}

Generic default data payload (v2):

{
  "sender": "stream.chat",
  "type": "message.new",
  "version": "v2",
  "message_id": "{{ message.id }}",
  "id": "{{ message.id }}",
  "channel_type": "{{ channel.type }}",
  "channel_id": "{{ channel.id }}",
  "cid": "{{ channel_cid }}"
}

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

| name | type | description | default | | ------------ | ------- | --------------------------------------------------------------------------------------------- | ----------------------------- | --- | | otherMembers | members | array | Which member array to implode | | | limit | integer | How many member names to show before adding the suffix | 3 | | nameField | string | Field name from which field to retrieve the member’s name. Note: does not support nesting | name | | separator | string | Separator to use for channel members |, | | suffixFmt | string | Format string to use for the suffix. Note: only %d is allowed for formatting | and %d other(s) |

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 }}
  }