Receiving Messages

Sunshine Conversations’ architecture is centered on the concept of a conversation. A conversation is an exchange of messages between one or more users and your systems.

This design makes it really easy for you to take advantage of all of the context present in communication with your users. When the user sends you a message, the message and its associated metadata is written to the conversation and sent to your business systems.

In addition to receiving these messages from within Sunshine Conversations’ business integrations, your software can receive the messages via a webhook.

Message Webhooks

Webhooks are a way to extend the Sunshine Conversations platform beyond the built-in feature set. You can use webhooks to build your own Sunshine Conversations chat clients, to integrate more deeply with your favorite CRM, or to build a bot.

Here is an example JSON payload that will be posted to all webhooks listening to new messages events when a user sends a message in a conversation:

{
    "app": {
        "id": "5698edbf2a43bd081be982f1"
    },
    "webhook": {
        "id": "5e554d2cac66fb73a3c01869",
        "version": "v2"
    },
    "events": [
        {
            "id": "0ca7d56ba7b2e081e479fe9e",
            "type": "conversation:message",
            "createdAt": "2020-02-25T18:06:37.547Z",
            "payload": {
                "conversation": {
                    "id": "13f32c6cf7d0d38e6e0eba93",
                    "type": "personal"
                },
                "message": {
                    "id": "5e55622dac66fb73a3c01877",
                    "received": "2020-02-25T18:06:37.547Z",
                    "content": {
                        "type": "text",
                        "text": "Hello world"
                    },
                    "author": {
                        "type": "user",
                        "userId": "cbec0073faeda4dfcd21d0f1",
                        "displayName": "Web User cbec0073faeda4dfcd21d0f1",
                        "user": {
                            "id": "cbec0073faeda4dfcd21d0f1"
                        }
                    },
                    "source": {
                        "type": "web",
                        "integrationId": "5d83a25d9916b64a83ed25e8"
                    }
                }
            }
        }
    ]
}

The payload contains information on the message, the user who sent it and all associated metadata. You can receive webhooks for a variety of events that occur in Sunshine Conversations. See the webhooks reference for more details and the full list of triggers and their associated payloads.

Configuring Via the Integrations Directory

If you won’t be managing many Sunshine Conversations apps, it’s probably easiest for you to configure webhooks via the UI using our integrations directory.

Visiting the Webhook page allows you to quickly enable support for an app. Once you turn on the feature, you’ll be able to specify a target URL endpoint as well as what events you want to be notified on.

Create a webhook

Once the webhook is configured, the target URL will start receiving notifications from Sunshine Conversations when the events occur.

Configuring Via API

Every app you create on Sunshine Conversations needs to have webhooks individually enabled for it. If you’re using account provisioning or simply want your software to be in control over Sunshine Conversations’ configuration, we’ve made it easy to use our API to set up webhooks for every app you’ve created.

To create a webhook using the Sunshine Conversations API simply create a custom integration with a webhook:

const apiInstance = new SunshineConversationsApi.IntegrationsApi();
const data = new SunshineConversationsApi.Integration();

data.type = 'custom';
data.webhooks = [{
    target = 'http://example.com/callback';
    triggers = ['conversation:message'];
}];

apiInstance.createIntegration(appId, data)
    .then(response => /* success */)
    .catch(error => /* failure */);

The target parameter is the URL that accepts webhooks in your system and the triggers parameter allows you to specify a list of all the events you want to be notified on.

Note that although each app you create needs to have its own webhook configuration, the target does not have to be unique. Your system can set the same target URL to receive webhooks from every Sunshine Conversations app pointing to it.

Our API Reference provides full details on how to configure and manage webhooks for your app using our API.

Retrieving Conversation History

Every message sent or received through Sunshine Conversations is available via the List Messages API in the conversation object as long as they haven’t been deleted from the system.

To access the conversation history, simply make a GET request targeting a particular conversation. For example:

const apiInstance = new SunshineConversationsApi.MessagesApi();
const opts = {}; // Can contain parameters for applying cursor pagination.

apiInstance.listMessages(appId, conversationId, opts)
    .then(response => /* success */)
    .catch(error => /* failure */);

This returns the last 100 messages of the conversation. Cursor pagination can be used to retrieve messages before or after a certain message record.

Message Author Name

When you receive a message from an user, it will always have a displayName associated with it. This name will be generated depending on the following logic:

  • If the user has a givenName or surname, use that as the message name (ex: “John Johnson”)
  • If the useAnimalNames setting is set to true, generate an animal name (ex: “Optimistic Ferret”)
  • If the user has an externalId, use ${channel} User ${externalId} as the message name (ex: “iOS User usr_AB23A”)
  • If the message is from a messaging channel (excluding SDKs) use ${channel} User ${externalId} as the message name (ex: “WhatsApp User 1234567890”)
  • If the message is from an SDK, use ${channel} User ${userId} as the message name (ex: “Android User 097491b5b2d5388e43f20354”)
  • If the message is from the API directly, use User ${userId} as the message name (ex: “User 097491b5b2d5388e43f20354”)

Next Steps