Using push notifications with your Conversations implementation drives your customers to re-engage with your app. With Twilio Conversations, you can configure pushes for:
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:
Table of Contents
The following push notifications can be configured for a Conversations Service instance:
| Push Notification Type | Description |
|---|---|
| New Message | This is sent to each chat participant in a Conversation whenever a new Message is posted. |
| New Media Message | This is sent to each chat participant in a Conversation whenever a new message is posted with Media (instead of text). |
| Added to Conversation | This is sent to chat participants that have been added to a Conversation |
| Removed from Conversation | This is sent to chat participants that have been removed from a Conversation |
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.
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 markup for a limited set of variables:
| Template Variable | Description |
|---|---|
${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. |
The maximum length of the entire notification payload is 178 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 178 characters are then used as the notification payload.
Variables can be used multiple times within a template, but each variable will contribute to the maximum number of available characters.
| Push Notification Type | Default Template |
|---|---|
| New Message | ${CONVERSATION}:${PARTICIPANT}: ${MESSAGE} |
| New Media Message | You have a new message in ${CONVERSATION} with ${MEDIA_COUNT} media files: ${MEDIA} |
| Added to Conversation | You have been added to the conversation ${CONVERSATION} by ${PARTICIPANT} |
| Removed from Conversation | ${PARTICIPANT} has removed you from the conversation ${CONVERSATION} |
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:
NewMessageAddedToConversationRemovedFromConversationThe following are the configuration parameters used:
| parameter name | description |
|---|---|
| [type].Enabled | Set true to send this type of push notification. Default: false |
| [type].Template | The customer template string for the notification type. |
| [type].Sound | The sound push payload parameter that will be set for this notification type, appropriately to the target platform. |
| NewMessage.BadgeCountEnabled | true 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.Enabled | Set true to send pushes for media messages. Default: false. |
| NewMessage.WithMedia.Template | A 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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateServiceNotification() {11const notification = await client.conversations.v112.services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.configuration.notifications()14.update({15"addedToConversation.enabled": true,16"addedToConversation.sound": "default",17"addedToConversation.template":18"There is a new message in ${CONVERSATION} from ${PARTICIPANT}: ${MESSAGE}",19});2021console.log(notification.addedToConversation);22}2324updateServiceNotification();
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",4"log_enabled": true,5"added_to_conversation": {6"enabled": false,7"template": "You have been added to a Conversation: ${CONVERSATION}",8"sound": "ring"9},10"new_message": {11"enabled": false,12"template": "You have a new message in ${CONVERSATION} from ${PARTICIPANT}: ${MESSAGE}",13"badge_count_enabled": true,14"sound": "ring",15"with_media": {16"enabled": false,17"template": "You have a new message in ${CONVERSATION} with ${MEDIA_COUNT} media files: ${MEDIA}"18}19},20"removed_from_conversation": {21"enabled": false,22"template": "You have been removed from a Conversation: ${CONVERSATION}",23"sound": "ring"24},25"url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Configuration/Notifications"26}
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateServiceNotification() {11const notification = await client.conversations.v112.services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.configuration.notifications()14.update({15"newMessage.withMedia.enabled": true,16"newMessage.withMedia.template":17"${PARTICIPANT} sent you a file: ${MEDIA}",18});1920console.log(notification.newMessage);21}2223updateServiceNotification();
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"log_enabled": true,5"added_to_conversation": {6"enabled": false,7"template": "You have been added to a Conversation: ${CONVERSATION}",8"sound": "ring"9},10"new_message": {11"enabled": false,12"template": "You have a new message in ${CONVERSATION} from ${PARTICIPANT}: ${MESSAGE}",13"badge_count_enabled": true,14"sound": "ring",15"with_media": {16"enabled": false,17"template": "You have a new message in ${CONVERSATION} with ${MEDIA_COUNT} media files: ${MEDIA}"18}19},20"removed_from_conversation": {21"enabled": false,22"template": "You have been removed from a Conversation: ${CONVERSATION}",23"sound": "ring"24},25"url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/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.
1'AddedToConversation.Enabled=true'2'AddedToConversation.Template=You are now a participant of ${CONVERSATION}! Added by ${PARTICIPANT}'3'AddedToConversation.Sound=default'