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

Push Notification Configuration for Conversations


Using push notifications with your Conversations implementation drives your customers to re-engage with your app. With Twilio Conversations, you can configure pushes for:

  • New Messages
  • New Media Messages (new since October 2021)
  • Conversations you've joined
  • Conversations you've left

Conversations integrates Apple Push Notifications (iOS) and Firebase Cloud Messaging (Android and browsers) using the Push credentials configured on your Twilio account. The content and payload of your push notifications will be different depending on the event that precipitates them.

Conversations Service instances provide some configuration options that allow push notification configuration on a per Service instance basis. These options allow for:

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

Table of Contents


Push Notification Types

push-types page anchor

The following push notifications can be configured for a Conversations Service instance:

Push Notification TypeDescription
New MessageThis is sent to each chat participant in a Conversation whenever a new Message is posted.
New Media MessageThis is sent to each chat participant in a Conversation whenever a new message is posted with Media (instead of text).
Added to ConversationThis is sent to chat participants that have been added to a Conversation
Removed from ConversationThis is sent to chat participants that have been removed from a Conversation
(information)

Info

The default enabled flag for new Service instances for all push notifications is false. This means that push notifications will be disabled until you explicitly set the flag to true.


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
${PARTICIPANT}Will be replaced with the FriendlyName of the Participant's underlying User who triggered the push notification (if any). The User's Identity will be used if no FriendlyName has been set. For Proxy Participants engaged via a non-chat channel, the MessagingBinding.Address will be used instead. When group texting, the MessagingBinding.Address will be used, or the MessagingBinding.ProjectedAddress if the Participant uses a Twilio phone number and has no underlying User.
${PARTICIPANT_FRIENDLY_NAME}Synonym of ${PARTICIPANT}.
${PARTICIPANT_IDENTITY}Synonym of ${PARTICIPANT}.
${PARTICIPANT_SID}Will be replaced with the Sid of the Participant who triggered the push notification (if any). The Participant's Identity will be used if no Sid is available.
${CONVERSATION}Will be replaced with the UniqueName, FriendlyName or ConversationSid (if they exist, in that order of priority). These properties are tied to the Conversation related to the push notification.
${CONVERSATION_FRIENDLY_NAME}Will be replaced with the FriendlyName, UniqueName or ConversationSid (if they exist, in that order of priority). These properties are tied to the Conversation related to the push notification.
${CONVERSATION_SID}Will be replaced with the ConversationSid. This property is tied to the Conversation related to the push notification.
${CONVERSATION_UNIQUE_NAME}Will be replaced with the UniqueName, or the FriendlyName, or ConversationSid (in that order) of the conversation to which this push pertains.
${MESSAGE}Will be replaced with the body of the actual Message. Only used for notifications of type: New Message
${MEDIA_COUNT}Sent exclusively for New Media Message pushes; counts the number of media files included. Presently, this will never be higher than 1; support for multiple media on the same message is coming soon.
${MEDIA}Sent exclusively for New Media Message pushes; presents the filename of the first media attached to the message.
(information)

Info

The maximum length of the entire notification payload is 110 characters. This limit is applied after the notification payload is constructed and the variable data is 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.

(information)

Info

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${CONVERSATION}:${PARTICIPANT}: ${MESSAGE}
New Media MessageYou have a new message in ${CONVERSATION} with ${MEDIA_COUNT} media files: ${MEDIA}
Added to ConversationYou have been added to the conversation ${CONVERSATION} by ${PARTICIPANT}
Removed from Conversation${PARTICIPANT} has removed you from the conversation ${CONVERSATION}

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
  • AddedToConversation
  • RemovedFromConversation

The following are the configuration parameters used:

parameter namedescription
[type].EnabledSet true to send this type of push notification. Default: false
[type].TemplateThe customer template string for the notification type.
[type].SoundThe sound push payload parameter that will be set for this notification type, appropriately to the target platform.
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.
NewMessage.WithMedia.EnabledSet true to send pushes for media messages. Default: false.
NewMessage.WithMedia.TemplateA specific template for new media message pushes, different and independent of NewMessage.Template.

Badge count refers to a counter on an app's icon that displays how many unread notifications there are for that app. Currently, only APNS push notifications for iOS will use this and include the badge property in the payload.

The badge count setting applies only to the NewMessage notification type. If enabled, the value of this property will represent the count of one-to-one Conversations the User participates in where there are unread Messages for the User.

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

Configure New Message Push Notifications

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

_16
// Download the helper library from https://www.twilio.com/docs/node/install
_16
// Find your Account SID and Auth Token at twilio.com/console
_16
// and set the environment variables. See http://twil.io/secure
_16
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16
const authToken = process.env.TWILIO_AUTH_TOKEN;
_16
const client = require('twilio')(accountSid, authToken);
_16
_16
client.conversations.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_16
.configuration
_16
.notifications()
_16
.update({
_16
'addedToConversation.enabled': true,
_16
'addedToConversation.sound': 'default',
_16
'addedToConversation.template': 'There is a new message in ${CONVERSATION} from ${PARTICIPANT}: ${MESSAGE}'
_16
})
_16
.then(notification => console.log(notification.addedToConversation));

Output

_26
{
_26
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26
"chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26
"log_enabled": true,
_26
"added_to_conversation": {
_26
"enabled": false,
_26
"template": "You have been added to a Conversation: ${CONVERSATION}",
_26
"sound": "ring"
_26
},
_26
"new_message": {
_26
"enabled": false,
_26
"template": "You have a new message in ${CONVERSATION} from ${PARTICIPANT}: ${MESSAGE}",
_26
"badge_count_enabled": true,
_26
"sound": "ring",
_26
"with_media": {
_26
"enabled": false,
_26
"template": "You have a new message in ${CONVERSATION} with ${MEDIA_COUNT} media files: ${MEDIA}"
_26
}
_26
},
_26
"removed_from_conversation": {
_26
"enabled": false,
_26
"template": "You have been removed from a Conversation: ${CONVERSATION}",
_26
"sound": "ring"
_26
},
_26
"url": "https://conversations.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Configuration/Notifications"
_26
}

In early versions of Conversations, media messages didn't trigger push notifications. Enable them now with this incantation.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.conversations.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.configuration
_15
.notifications()
_15
.update({
_15
'newMessage.withMedia.enabled': true,
_15
'newMessage.withMedia.template': '${PARTICIPANT} sent you a file: ${MEDIA}'
_15
})
_15
.then(notification => console.log(notification.newMessage));

Output

_26
{
_26
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26
"chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26
"log_enabled": true,
_26
"added_to_conversation": {
_26
"enabled": false,
_26
"template": "You have been added to a Conversation: ${CONVERSATION}",
_26
"sound": "ring"
_26
},
_26
"new_message": {
_26
"enabled": false,
_26
"template": "You have a new message in ${CONVERSATION} from ${PARTICIPANT}: ${MESSAGE}",
_26
"badge_count_enabled": true,
_26
"sound": "ring",
_26
"with_media": {
_26
"enabled": false,
_26
"template": "You have a new message in ${CONVERSATION} with ${MEDIA_COUNT} media files: ${MEDIA}"
_26
}
_26
},
_26
"removed_from_conversation": {
_26
"enabled": false,
_26
"template": "You have been removed from a Conversation: ${CONVERSATION}",
_26
"sound": "ring"
_26
},
_26
"url": "https://conversations.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Configuration/Notifications"
_26
}

Setting additional notification types requires including them in your configuration request. For instance, to include the AddedToConversation push notification type, you can add the following 3 rows to your curl request.


_10
'AddedToConversation.Enabled=true'
_10
'AddedToConversation.Template=You are now a participant of ${CONVERSATION}! Added by ${PARTICIPANT}'
_10
'AddedToConversation.Sound=default'


Rate this page: