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 users and your business system.

You can send messages using our integrated business systems, this allows you to start communicating with your customers using your favorite 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:

const apiInstance = new SunshineConversationsApi.MessagesApi();
const data = new SunshineConversationsApi.MessagePost();
data.author = {
    type: 'business'
};
data.content = {
    type: 'text',
    text: 'Hello, world!',
};
data.metadata = {}; // optional object

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

In the code above, content contains the message payload, while the author object is used to identify the “sender” of the message. 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 to a conversation, 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).

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. When sending a message, a destination object can be used to target a channel with either an integrationType or integrationId. Note that for this to work, the user needs to have a client linked to the targeted channel on the targeted conversation.

const apiInstance = new SunshineConversationsApi.MessagesApi();
const data = new SunshineConversationsApi.MessagePost();
data.author = {
    type: 'business'
};
data.content = {
    type: 'text',
    text: 'Hello, world!',
};
data.destination = SunshineConversationsApi.Destination();
data.destination.integrationId = "029c31f25a21b47effd7be90"; // the targeted channel
data.metadata = {}; // optional object


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

Silent Messages

In some cases the conversation with a user might proceed through an external channel, outside of Sunshine Conversations. You can populate the messages into the Sunshine Conversations record without triggering notifications for the users using silent messages. Using the example above, specifying an integrationType of none will create a silent message that will not trigger message delivery to the user.

data.destination = SunshineConversationsApi.Destination();
data.destination.integrationType = 'none'; // a silent message

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.

const apiInstance = new SunshineConversationsApi.ActivitiesApi();
const data = new SunshineConversationsApi.ActivityPost();
data.author = {
    type: 'business'
};
data.type = 'typing:start';

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

When you call this function with ‘typing:start’, a typing activity indicator will be displayed on the supported channel. On most platforms, the indicator will automatically time out, it can also be canceled by sending ‘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.

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.