Creating and Managing Apps

Sunshine Conversations apps act as interfaces for individual business to communicate over messaging channels like Facebook Messenger, SMS and the Sunshine Conversations Web Messenger. A single Sunshine Conversations app aggregates communication with users over any number of channels and delivers messages to and from those users via the REST API and webhooks.

You don’t have to manage your Sunshine Conversations apps through the dashboard. Sunshine Conversations offers a series of app management APIs that can be used to create and manage apps programmatically.

Creating an App

Creating an app requires the account scope (see authentication section). To create an app, use the create app endpoint, supplying the proper Authentication header, and a displayName for your app in the request body.

const apiInstance = new SunshineConversationsApi.AppsApi();
const data = new SunshineConversationsApi.AppCreateBody();
data.displayName = 'My app';

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

The response to the create app request will contain the app’s id, which is used to reference the app in other API paths.

App Settings

Conversation Retention Seconds

The conversationRetentionSeconds setting dictates a period of time after which an inactive conversation will have its messages deleted. The deletion behavior is similar to when a conversation’s messages are deleted, meaning the messages will be deleted, but the conversation and any associated participants will remain. There is a separate API that can be used to fully delete a conversation. As long as a conversation continues to receive regular activity, messages will not expire. Activities that will prevent message expiration include:

Conversations that are created before conversationRetentionSeconds is set will not be affected by this setting until a new activity is detected.

If conversationRetentionSeconds is left unset, no automatic message deletion will take place. The setting may be set to 0 in order to disable automatic message deletion upon new message activity. If nonzero, the minimum setting is 1 hour (3600 seconds).

Echo Postbacks

echoPostback controls whether a message should be added to the conversation history when a postback button is clicked. When enabled, a user message is silently added to the conversation, without a corresponding conversation:message webhook being triggered.

The echoPostback setting works with any channel that supports postback actions natively (including Facebook Messenger, Twitter DM, Telegram, LINE and all Sunshine Conversations SDKs). In some channels Sunshine Conversations offers partial support for postback buttons via text fallback. For these channels, the user needs to answer with a message matching the postback action text. In this case, the user’s message will always be added to the conversation history.

If echoPostback is set to true, pressing a postback button generates and stores a message within the Sunshine Conversations thread. When set to false and a postback button is activated, it initiates a postback webhook without storing any message in Sunshine Conversations. Channels such as Messenger will continue to render the activated postback if that is their default behavior, since this is beyond the control of Sunshine Conversations.

Configuring Webhooks

To create a webhook for a given app, create a custom integration, specifying the target URL of your server, and a list of triggers to subscribe to.

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 */);

When specifying a target URL, Sunshine Conversations will make a HTTP HEAD request to the provided URL in order to verify that the domain exists and that there is a service running.

For example, if you specify a target URL of https://my-server.some-domain.com/path/to/my/handler, Sunshine Conversations will issue the following request and parse the response:

curl -I https://my-server.some-domain.com/path/to/my/handler

If the initial HEAD request fails, Sunshine Conversations will issue a second request to the domain and parse the response:

curl -I https://my-server.some-domain.com

Distributing App Credentials

If your software needs to distribute credentials that give access to an app, you can use the app keys APIs to manage the list of API keys for an app. Similar to creating an app, the account scope is required to manage an app’s API keys. To create an app key, call the create key API and specify a name for the key:

const apiInstance = new SunshineConversationsApi.AppKeysApi();
const data = new SunshineConversationsApi.AppKeyCreateBody();
data.displayName = 'My app key';

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

The returned API key id and secret is used as authentication to make requests to access the app’s data.

Integrating Messaging Channels

Now that you have prepared your app, the next step is to add messaging channels. See the Configuring Messaging Channels guide.