Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Push Notification Configuration for Programmable Chat


Programmable Chat integrates APN (iOS) and GCM/FCM (Android and browsers) Push Notifications for certain events. Not all implementations need every possible event to trigger push notifications. Additionally, the content and payload of your push notifications will differ based on requirements and use cases.

Chat Service instances provide some configuration options which allow push configuration on a per Service instance basis. These options allow for:

  • Selecting which of the eligible Chat events should trigger push notifications
  • Specifying the payload template for each message type (overriding the default template)
(warning)

Warning

It is not currently possible to selectively register for various push notification message types on the client SDKs (iOS and Android). This capability is planned and will be delivered in a future release of the relevant SDKs.

Table of Contents


Push Notification Types

push-types page anchor

The following Push Notifications can be configured for a Chat Service instance:

Push Notification TypeDescription
New MessageThis is sent to all members within a Channel when a new Message is posted to the Channel
Added to ChannelThis is sent to Users that have been added to a Channel
Invited to ChannelThis is sent to Users that have been invited to join a Channel
Removed from ChannelThis is sent to Users that have been removed from a Channel they were a Member of

Note: The default enabled flag for new Service instances for all Push Notifications is false. This means that Push will be disabled until you explicitly enable it.

Note: You may configure a sound parameter value for each of the Push Notification types (detailed below).


Push Notification Templates

push-templates page anchor

Each of the Push Notification types has a default template for the payload (or notification body). Each of these templates can be overridden per Service instance via the Push Notification configuration. The templating employs very simple markup for a limited set of variables:

Template Variables

template-variables page anchor
Template VariableDescription
${USER}Will be replaced with the FriendlyName of the User who triggered the Push Notification (if any). The User's Identity will be used if no FriendlyName has been set.
${USER_FRIENDLY_NAME}Will be replaced with the FriendlyName of the User who triggered the Push Notification (if any). The User's Identity will be used if no FriendlyName has been set.
${USER_IDENTITY}Will be replaced with the Identity of the User who triggered the Push Notification.
${USER_SID}Will be replaced with the Sid of the User who triggered the Push Notification (if any). The User's Identity will be used if no Sid is available.
${CHANNEL}Will be replaced with the UniqueName, FriendlyName or ChannelSid (if they exist, in that order of priority). These properties are tied to the Channel related to the Push Notification.
${CHANNEL_FRIENDLY_NAME}Will be replaced with the FriendlyName, UniqueName or ChannelSid (if they exist, in that order of priority). These properties are tied to the Channel related to the Push Notification.
${CHANNEL_SID}Will be replaced with the ChannelSid. This property is tied to the Channel related to the Push Notification.
${CHANNEL_UNIQUE_NAME}Will be replaced with the UniqueName or ChannelSid (if they exist, in that order of priority). These properties are tied to the Channel related to the Push Notification.
${MESSAGE}Will be replaced with the body of the actual Message. Only used for notifications of type: New Message

Note: The maximum length of the entire notification payload is 110 characters. This substring is applied after the notification payload is constructed and the variables data applied. Thus, freeform text and the variable data are compiled into a string and the first 110 characters are then used as the notification payload.

Note: Variables can be used multiple times within a template, but each variable will contribute to the maximum number of available characters.

Push Notification TypeDefault Template
New Message${CHANNEL};${USER}: ${MESSAGE}
Added to ChannelYou have been added to channel ${CHANNEL} by ${USER}
Invited to Channel${USER} has invited you to join the channel ${CHANNEL}
Removed from Channel${USER} has removed you from the channel ${CHANNEL}

Configure Push Notifications

push-configuring page anchor

Each Push Notification type can be configured for a Service instance. The configuration allows each notification type to be enabled or disabled. This also handles custom template configuration as per the templating mechanism described above.

The following are the eligible notification type names:

  • NewMessage
  • AddedToChannel
  • InvitedToChannel
  • RemovedFromChannel

The following are the configuration parameters used:

parameter namedescription
Notifications.[type].Enabledtrue if this type of push notification should be sent, false if not. Default: false
Notifications.[type].TemplateThe customer template string for the notification type.
Notifications.[type].SoundThe "sound" push payload parameter that will be set for this notification type.
Notifications.NewMessage.BadgeCountEnabledtrue if the NewMessage notification type should send a badge count value in the push payload. This parameter is only applicable to the NewMessage type. Please note that this is currently only used by the iOS APNS push notification type.

This setting is only for the NewMessage notification type. Currently, only APNS push notifications for iOS will use this and include the badge property in the payload. If enabled, the value of this property will represent the count of 1:1 Channels the User is a Member of which have any unread Messages for the User.

If Notifications.NewMessage.BadgeCountEnabled is set to true, decrements to the count of 1:1 Channels with unread messages will be sent to all registered iOS endpoints for that User.

Configure NewMessage Push Notifications

configure-newmessage-push-notifications page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.chat.v2.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_14
.update({
_14
'notifications.addedToChannel.enabled': true,
_14
'notifications.addedToChannel.sound': 'default',
_14
'notifications.addedToChannel.template': 'A New message in ${CHANNEL} from ${USER}: ${MESSAGE}'
_14
})
_14
.then(service => console.log(service.friendlyName));

Output

_57
{
_57
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_57
"consumption_report_interval": 100,
_57
"date_created": "2015-07-30T20:00:00Z",
_57
"date_updated": "2015-07-30T20:00:00Z",
_57
"default_channel_creator_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_57
"default_channel_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_57
"default_service_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_57
"friendly_name": "friendly_name",
_57
"limits": {
_57
"channel_members": 500,
_57
"user_channels": 600
_57
},
_57
"links": {
_57
"channels": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels",
_57
"users": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Users",
_57
"roles": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Roles",
_57
"bindings": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Bindings"
_57
},
_57
"notifications": {
_57
"log_enabled": true,
_57
"added_to_channel": {
_57
"enabled": false,
_57
"template": "notifications.added_to_channel.template"
_57
},
_57
"invited_to_channel": {
_57
"enabled": false,
_57
"template": "notifications.invited_to_channel.template"
_57
},
_57
"new_message": {
_57
"enabled": false,
_57
"template": "notifications.new_message.template",
_57
"badge_count_enabled": true
_57
},
_57
"removed_from_channel": {
_57
"enabled": false,
_57
"template": "notifications.removed_from_channel.template"
_57
}
_57
},
_57
"post_webhook_url": "post_webhook_url",
_57
"pre_webhook_url": "pre_webhook_url",
_57
"pre_webhook_retry_count": 2,
_57
"post_webhook_retry_count": 3,
_57
"reachability_enabled": false,
_57
"read_status_enabled": false,
_57
"sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_57
"typing_indicator_timeout": 100,
_57
"url": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_57
"webhook_filters": [
_57
"webhook_filters"
_57
],
_57
"webhook_method": "webhook_method",
_57
"media": {
_57
"size_limit_mb": 150,
_57
"compatibility_message": "new media compatibility message"
_57
}
_57
}

Setting additional notification types requires including them in your configuration request. For instance, to include the AddedToChannel Push Notification type, you can add


_10
'Notifications.AddedToChannel.Enabled=true'
_10
'Notifications.AddedToChannel.Template=You are now a Member of ${CHANNEL}! Added by ${USER}'
_10
'Notifications.AddedToChannel.Sound=default'

to your curl request.

Next: Notifications on iOS


Rate this page: