Sending Messages

Sunshine Conversations allows you to send text, image and structured messages to your users. Each of the messages you send becomes a part of the conversation between your user and your business system.

You can send messages using our integrated business systems, this allows you to start communicating with your customers using your favourite software.

Alternatively, you can use the Sunshine Conversations API to send messages or notifications from within your own software.

Sending Text Messages with the API

In order to send a message to a user, you’ll need the user’s ID. Typically, you’ll obtain this from the webhook that delivers a user’s message to your software, alternatively you can obtain this ID by manually creating users or by copying it from the dashboard log tab.

With the user ID in hand, you can easily send a simple text message:

smooch.appUsers
    .sendMessage({
        appId: 'APP_ID',
        userId: 'APP_USER_ID',
        name: 'Jack Bauss',
        email: 'boss@business.com',
        message: {
            type: 'text',
            text: 'Hello, world!',
            role: 'appMaker',
            metadata: {} // optional object
        }
    })
    .then(() => {
        // async code
    });

In the code above, text contains the message payload, while name and email are optionally used to identify the “sender” of the message that should be displayed to the user receiving the message. Sunshine Conversations uses the email parameter to look up and provide an avatar for the message sender using gravatar, if one is available.

To learn more about the various parameters of this API, read its reference documentation.

Automatic message delivery

When responding to users that have multiple channels linked, either via the Linking API or the Web Messenger, Sunshine Conversations uses the following channel targeting logic to ensure delivery of messages:

  • First, send the message to the preferred channel. The preferred channel is the last channel used by the user.
  • If the message is left unread for 5 minutes and the preferred channel was not push-capable, send the message to the second-best channel. This means the second most recently used channel that is push-capable (A channel that will trigger a device notification when receiving a message).
  • Finally, send the message to all silent channels, channels that support receiving messages without a notification (currently only Facebook messenger).

Here’s a visual representation of the automatic message delivery logic:

Built-in delivery logic

Targeting a specific channel

Using the Sunshine Conversations API, you can also bypass the automatic delivery logic and target a channel specifically. Note that for this to work, the user needs to have a client linked to the targeted channel.

smooch.appUsers
    .sendMessage({
        appId: 'APP_ID',
        userId: 'APP_USER_ID',
        message: {
            type: 'text',
            text: 'Hey Messenger user',
            role: 'appMaker',
            name: 'Jack Bauss',
            email: 'boss@business.com',
            destination: {
                integrationType: 'messenger'
            }
        }
    })
    .then(() => {
        // async code
    });

Sending Typing Activity with the API

In some cases, user experience in a conversation can be improved by letting the user know that “typing” is in progress and that a message will soon be on its way. Sunshine Conversations provides a convenient API that you can use to signal these events to messaging channels that support this feature.

smooch.appUsers
    .typingActivity('APP_USER_ID', {
        type: 'typing:start'
    })
    .then(() => {
        // async code
    });

When you call this function with ‘typing:start’, a typing activity indicator will be displayed on the supported channel. To cancel it, call ‘typing:stop’. Alternatively, the indicator will be stopped the moment you send another message on the channel. You can read more about this function, and its behaviour in the API reference.

Sending Notifications with the API

Sometimes, it’s necessary for a business to reach out before a customer initiates a conversation. With the Notification API, you can send outbound messages to users proactively on WhatsApp, SMS and MessageBird using a channel specific ID (for example, a phone number).

smooch.notifications
    .postNotification({
        appId: '5963c0d619a30a2e00de36b8',
        notification: {
            destination: {
                integrationId: '080d1897b8a5eb17513498b074f37a0a',
                destinationId: '+15145555333'
            },
            author: {
                role: 'appMaker'
            },
            message: {
                type: 'text',
                text: 'Check this out!'
            }
        }
    })
    .then((response) => {
        // async code
    });

In the code above, the role supplied must always be appMaker. Furthermore, while this particular example message payload represents a text message, an additional messageSchema field can be provided, which permits the sending of templated messages.

To learn more about the various parameters of this API, read its reference documentation.

Next steps

Once you’re able to send text messages to users with Sunshine Conversations, move on to sending structured messages that can significantly enrich the conversation experience.