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.

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.