Receiving Messages

Sunshine Conversations’ architecture is centered on the concept of a conversation. A conversation is an exchange of messages between a particular appUser and your systems. Each appUser created in your app’s context has a single conversation. This conversation is initialized at the same moment as the appUser is created.

This design makes it really easy for you to take advantage of all of the context present in communication with your appUser. When the appUser 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 fantastic 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.

When a webhook trigger is triggered, a JSON payload will be posted to the URL configured in your webhook object. Here is an example payload for when an appUser sends a message:

{
    "trigger": "message:appUser",
    "app": {
        "_id": "5698edbf2a43bd081be982f1"
    },
    "version": "v1.1",
    "messages": [
        {
            "text": "Hi! Do you have time to chat?",
            "type": "text",
            "role": "appUser",
            "received": 1547492967.683,
            "name": "Steve",
            "authorId": "f341b4d4ff879cbc04a7ac63",
            "_id": "5c3cde67eef2c036b9af23db",
            "source": {
                "type": "messenger"
            }
        }
    ],
    "appUser": {
        "_id": "f341b4d4ff879cbc04a7ac63",
        "conversationStarted": true
    }
}

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 add 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 to have your software be in control over Sunshine Conversations’ configuration, we’ve made it easy to use our API to configure webhooks for each app you’ve created.

To create a webhook using the Sunshine Conversations API simply call the webhooks.create() function:

smooch.webhooks
    .create({
        target: 'http://example.com/callback',
        triggers: ['message:appUser']
    })
    .then((response) => {
        // async code
    });

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 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 to a particular user’s messages endpoint. For example:

smooch.appUsers
    .getMessages({
        userId: 'c7f6e6d6c3a637261bd9656f',
        query: {
            before: 1471995721
        }
    })
    .then((response) => {
        // async code
    });

This returns the last 100 messages as of UNIX timestamp 1471995721 or 23 Aug, 2016 - 23:42:01 GMT. You can also specify a timestamp after to retrieve the 100 messages sent or received after the timestamp.

Message Author Name

When you receive a message from an appUser, it will always have a name 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 a userId, use ${channel} User ${userId} 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 ${appUserId} as the message name (ex: “Android User 097491b5b2d5388e43f20354”)
  • If the message is from the API directly, use User ${appUserId} as the message name (ex: “User 097491b5b2d5388e43f20354”)

Next Steps