Overview
Sunshine Conversations supports a number of methods to proactively engage with customers, the simplest method being via our Notification API.
Alternatively, conversations can be initiated from the business side for an existing user by leveraging the Link User To Channel API. This guide section describes how all outbound messaging methods work on the platform, and details which one to use for your use case.
Notification API
The Notification API lets businesses send proactive messages to a user without needing a prior conversation with that user. With the Notification API, you can send outbound messages to users proactively using a channel specific ID (for example, a phone number). Your notification can leverage any message type supported by the channel being used to include files, images, emojis, etc.
The Notification API is easy to integrate, reducing sending message to a single API call. The Notification API integrates with any business system and upon a user reply, gives agents full conversation context by exposing original messages as seen on the user side. Businesses can also track the progress of the delivery of all business-initiated messages.
Unlike the Conversations API, there are no up-front MAU costs for sending outbound messages — a per message usage fee is used instead. An MAU is only charged when a user responds to your proactive message. See our pricing page for more details.
Use cases
The Sunshine Conversations Notification API helps you deliver better customer experiences at scale. Its streamlined API keeps technical load to a minimum, making it easy to reach one or many customers and keep them engaged with personalized messages adapted to any business need. You can use the Notification API to send structured messages such as:
- Scheduled appointment updates & reminders
- Service interruption notifications
- Security break alerts & 2-Factor authentication messages
- Real-time flight updates & check-in reminders
- Fraud alerts for credit cards & checking accounts
- Product shipment & delivery confirmations
- Account activity alerts
- IoT driven alerts from connected devices
- Ticket purchase confirmation & electronic ticket delivery
- Incomplete signup or checkout nudges & reminders
- Monthly invoice updates & payment reminders
Now you can keep the conversation alive with customers who have disengaged and are showing signs of churning. Send personalized messages and get a dialogue going again and have messages automatically delivered to your customer’s preferred channel.
Channel Availability
The Notification API is available on:
How to send a notification
To send a notification to a user on WhatsApp or over SMS simply make a request to the Notifications endpoint. For example :
Request
POST /v1.1/apps/5963c0d619a30a2e00de36b8/notifications{
"destination": {
"integrationId": "5e1f438bf99fb467810c0ab9",
"destinationId": "+15145555333"
},
"author": {
"role": "appMaker"
},
"message": {
"type": "text",
"text": "Check this out!"
}
}
In response, a notification id is generated to track the notification during the delivery process. See the webhook section on how to track the delivery of a notification. This id is not persisted and is valid until the notification is delivered.
Response
{
"notification": {
"_id": "e361392f-7dd3-4bdb-8844-d0d002ac7f72"
}
}
Existing Sunshine Conversations Users
If your users already exist in Sunshine Conversations, you can add a new channel to an existing user by using the Link User To Channel API. Note that whenever a notification is sent, Sunshine Conversations will use the channel id to match existing users according to currently linked channels.
Notifying your customers on WhatsApp is simplified with the Notification API which also supports WhatsApp Message Templates.
WhatsApp Message Templates can be sent to a user by making a similar request to the Notifications endpoint. See the WhatsApp guide page for more detail on WhatsApp’s policy regarding outbound messaging and for more usage example.
Send a text template:
POST /v1.1/apps/5963c0d619a30a2e00de36b8/notifications{
"destination": {
"integrationId": "5e1f438bf99fb467810c0ab9",
"destinationId": "+15145555333"
},
"author": {
"role": "appMaker"
},
"messageSchema": "whatsapp",
"message": {
"type": "template",
"template": {
"namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
"name": "sample_hsm",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Sample Notification"
},
{
"type": "text",
"text": "Sample Notification"
}
]
}
]
}
}
}
Using correctedDestinationId
When communicating with users in countries that change their mobile format (such as Brazil adding a 9th digit to mobile numbers), appMakers might notice that WhatsApp adjusts the phone number format to align with its stored format. Consequently, you could end up with two distinct users - one with the initial number format used and another with the WhatsApp-corrected format.
When you are provided with a correctedDestinationId, it is important to update the phone number format in your end-user’s profile within your notification list accordingly. Sunshine Conversations will not automatically update or merge users for you, but will supply the correctedDestinationId for your usage.
To clean up your users and conversations, please implement the following process if you send a notification AND notification:delivery:user (or notification:delivery:failure) contains a correctedDestinationId:
-
Unlink the bad client from the user (the one that matches
destinationId) using Unlink App User From Channel. The target user for this request will be present in thematchResultof the webhook payload. -
Link the user to the client that you know is correct with Link App User to Channel. Calling this API triggers a channel transfer. Depending on whether or not a client already exists with the
correctedDestinationId, this API triggers a merge, or a client theft. See Channel Transfer for more details.
Going forward, refrain from using the faulty destinationId; instead, always use correctedDestinationId.
SMS
If your business has a phone number for a user, reaching out to the user via SMS is simple. Use the Notification endpoint to easily send your outbound message. The user should receive a text message and be able to reply right away.
Webhooks
Three delivery event webhooks are available to receive notification delivery status: notification:delivery:channel, notification:delivery:failure and notification:delivery:user. Read more details on delivery events on Sunshine conversation here.
Webhook Body notification:delivery:channel / notification:delivery:failure
{
"trigger": "notification:delivery:channel" | "notification:delivery:failure",
"app": {
"_id": "5babc57a79ace012bba4781a"
},
"version": "v1.1",
"timestamp": 1480001440.731,
"destination": {
"type": "messagebird|twilio|whatsapp",
"integrationId": "5b354bdab42a1d61143ccc26",
"destinationId": "+15145555555"
},
"isFinalEvent": true|false,
"externalMessages": [
{
"id": "a121392f-7dd3-4bdb-8844-fa3rd2ac7f72"
}
],
"notification": {
"_id": "e361392f-7dd3-4bdb-8844-d0d002ac7f72"
},
"matchResult": {
"appUser": {
"_id": "5b354bdab42a1d61143ccc26",
"userId": "bob@email.com",
"conversationStarted": true
},
"conversation": {
"_id": "075354bdab42a1d61143cc362"
},
"client": {
"integrationId": "5b354bdab42a1d61143ccc26",
"externalId": "15145555555",
"id": "e6eb2653-e143-4c1a-be58-bdd6afgh35ff",
"displayName": "+1 514-555-5555",
"status": "active",
"raw": {
"profile": {
"name": "Some Person"
},
"from": "15145555555"
},
"lastSeen": "2024-03-15T20:19:23.851Z",
"linkedAt": "2024-02-28T16:02:10.219Z",
"_id": "65df5902e111c3e8f8edee28",
"platform": "whatsapp",
"active": true,
"blocked": false,
"primary": true
}
},
[error]: { … }
}
Webhook Body notification:delivery:user
{
"trigger": "notification:delivery:user",
"app": {
"_id": "5babc57a79ace012bba4781a"
},
"version": "v1.1",
"timestamp": 1480001440.731,
"isFinalEvent": true,
"destination": {
"type": "messagebird|twilio|whatsapp",
"integrationId": "5b354bdab42a1d61143ccc26",
"destinationId": "+15145555555"
},
"externalMessages": [
{
"id": "a121392f-7dd3-4bdb-8844-fa3rd2ac7f72"
}
],
"notification": {
"_id": "e361392f-7dd3-4bdb-8844-d0d002ac7f72"
},
"matchResult": {
"appUser": {
"_id": "5b354bdab42a1d61143ccc26",
"userId": "bob@email.com",
"conversationStarted": true
},
"conversation": {
"_id": "075354bdab42a1d61143cc362"
},
"client": {
"integrationId": "5b354bdab42a1d61143ccc26",
"externalId": "15145555555",
"id": "e6eb2653-e143-4c1a-be58-bdd6afgh35ff",
"displayName": "+1 514-555-5555",
"status": "active",
"raw": {
"profile": {
"name": "Some Person"
},
"from": "15145555555"
},
"lastSeen": "2024-03-15T20:19:23.851Z",
"linkedAt": "2024-02-28T16:02:10.219Z",
"_id": "65df5902e111c3e8f8edee28",
"platform": "whatsapp",
"active": true,
"blocked": false,
"primary": true
}
}
}
Context on replies
When sending notifications, message:appMaker webhooks are not triggered like those triggered by messages sent by the business through the Conversation API.
Instead, when a user sends a message, the messages sent using the Notification API since the last user message are included in the message:appUser webhook under the recentNotifications key.
The recent notifications allows agents to have the full context when replying to app user messages. The full conversation record is also available via the Get messages API.
Furthermore, WhatsApp Message Templates can be reconstructed to reflect the message as seen by the user instead of only providing a template name. See Message Template Reconstruction in our WhatsApp guide to enable this feature.
Payload example for message:appUser webhook with notification context:
{
"trigger": "message:appUser",
"app": {
"_id": "5babc57a79ace012bba4781a"
},
"version": "v1.1",
"messages": [
{
"type": "text",
"text": "This is a user reply to a notification",
"role": "appUser",
"received": 1552571286.396,
"name": "Alice",
"authorId": "4a9006a2b1a17bebf00542ab",
"_id": "5c8a5b96bac2a4128e5225ec",
"source": {
"type": "whatsapp",
"integrationId": "5b354bdab42a1d61143ccc26"
}
}
],
"appUser": {
"_id": "4a9006a2b1a17bebf00542ab",
"conversationStarted": true
},
"conversation": {
"_id": "0a01d368966f45bb6bd7d41c"
},
"recentNotifications": [
{
"_id": "5c8a5b90fa8624128cc5ba32",
"role": "appMaker",
"type": "text",
"text": "This is a sample notification.",
"authorId": "00udkjb3sjnQkjH2n0h7",
"avatarUrl": "https://www.gravatar.com/avatar/00000000000000000000000000000000.png?s=200&d=mm",
"received": 1552571280.984,
"source": {
"type": "notification"
}
}
]
}
Outbound messaging on SDKs
To initiate a conversation with a user on your mobile app or website, you first need to ensure that the conversation exists. By default, the SDKs delays creation of the user until a first message is sent. In order to proactively reach out to a user, your application or website must use the createConversation method on iOS, Android, or Web. This method instruct the SDK to proactively create a user and conversation in the platform. Once the conversation is started, you can send a message to that user like any other.
Example flow on Web Messenger
- A user navigates to your online store in their browser. They do not have a registered account with your website, and the user is browsing anonymously.
- When the page loads, you call the init method to initialize the Web Messenger and display the call to action in the bottom right hand corner of the screen, in case the user needs to reach out for support. The SDK is now initialized in anonymous mode, but the user and conversation record do not yet exist.
- The user doesn’t need any help, and instead completes a transaction anonymously. This is an important event in your user flow, and you determine that now is the correct time to reach out to the user.
- Your website calls the createConversation method to signal to Sunshine Conversations that you would like to reach out to the user.
- The SDK creates a user and conversation, and signals your server with a
conversation:startwebhook event. The SDK opens a websocket connection to receive business messages. - Your server retrieves the user’s ID from the webhook payload, and sends a message via the Post Message API.
- The message is received by the browser, and displays an unread indicator over the messaging button.
- The user clicks the button and is able to view the message, and reply if necessary.
Example flow on iOS
- A user downloads your application from the App Store, and is promted to create an account before they can continue.
- When the application launches, you call +initWithSettings:completionHandler: to initialize the SDK.
- When the user completes the sign-up flow, your application creates an account with your own server, and is returned a JWT for the newly created user.
- Your application calls +login:jwt:completionHandler: to identify the user on the SDK and provide the JWT generated in the previous step. The user is now authenticated in Sunshine Conversations, but the user and conversation record do not yet exist.
- During your sign-up flow, or at some other point that you have deemed appropriate, your application requests user notification permission in order to send push notifications to the user. (This step is required if you intend to reach out to the user after they have already closed your application).
- The user makes a purchase in your application, and opts in to receive status updates on their order. This is an important event in your user flow, and you determine that now is the correct time to create the user.
- Your application calls the +createConversationWithName: method to signal that you would like to reach out to the user at some point in the future.
- The SDK creates a user and conversation, and signals your server with a
conversation:startwebhook event. The push notification token obtained in step 5 is automatically associated to the user and stored alongside their profile information. - Your server retrieves the user’s userId from the webhook payload, and matches it with the
userIdprovided at login time in step 4. - At a later time, the status of the user’s order is updated, and your system decides that the user should be notified.
- Your server sends a message via the Post Message API, using the
userIdthat was assigned in step 4. - The user receives a push notification with the contents of your message, and can tap it to open the conversation screen to view the message history, and reply if necessary.