Push Templates in v3

Templates in v3

For both Firebase and APNs, 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

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

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

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:

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

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

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

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:

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

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:

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

Enabling and Customizing Push Templates

The Upsert Push Template REST endpoint allows you to enable push notifications for supported event types and optionally define custom templates.

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 200 }}\"},\"badge\":{{ unread_count }},\"sound\":\"default\",\"mutable-content\":1,\"content-available\":0}}}}"
}