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 appUsers 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 account provisioning APIs that can be used to create and manage apps programmatically.

• Creating an App
• Configuring Webhooks
• Distributing App Credentials
• Integrating Messaging Channels

Creating an App

Creating an app requires the account scope - this can either be signed with a user account key, or a service account key. To create an app, use the create app endpoint, supplying the proper Authentication header, and a name for your app in the request body.

curl https://api.smooch.io/v1.1/apps \
  -X POST \
  -d '{"name": "My App"}' \
  --user 'keyId:keySecret'

The response to the create app request will contain the app’s _id, which can be used to initialize the Web and Mobile SDKs, and is also used to reference the app in other API paths.

Configuring Webhooks

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

curl https://api.smooch.io/v1.1/apps/55c8d9758590aa1900b9b9f6/webhooks \
  -X POST \
  -d '{"target": "https://my-server.some-domain.com/path/to/my/handler"}' \
  --user 'keyId:keySecret'

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:

curl https://api.smooch.io/v1.1/apps/55c8d9758590aa1900b9b9f6/keys \
  -X POST \
  -d '{"name": "My Key"}' \
  --user 'keyId:keySecret'

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.