API Quickstart

Introduction

This quickstart guide will walk you through getting started with Sunshine Conversations’ REST API. When you complete the guide, you’ll know how to connect Facebook Messenger to Sunshine Conversations and send an automated response to any Facebook Messenger user who sends you a message.

You can also find the complete code for this walkthrough here.

Create a new Facebook page

This guide uses the Sunshine Conversations Dashboard to configure Facebook Messenger. It is also possible to configure this via the integration API.

Create a new Facebook page for a fictional character

Connect Facebook to Sunshine Conversations

If you haven’t already, sign up for a Sunshine Conversations account, and create an app.

Create app

Once you have an app, you can connect Facebook Messenger from the Integration Directory.

Once you’ve authorized Sunshine Conversations to your Facebook account, select the page you created above and save.

Select Facebook page

Now, whenever someone sends a message to your Facebook page, it will be sent to Sunshine Conversations. At this point, if you try to message your page you’ll see an entry in the log corresponding to this message. Great! Now let’s get those message to your server.

Deploy a server

Next, you need to deploy a server and expose a POST /messages endpoint to receive user messages. All you want to do for now is log those messages.

We wrote our server in Node.js and used a service called ngrok to create a secure tunnel to localhost. If you need inspiration, check out the complete code.

Create a webhook

Once your server is listening for requests, create a webhook from the dashboard. In the webhook URL field, enter the full URL for your /messages endpoint (e.g. https://MY-NGROK-DOMAIN.ngrok.io/messages). Pick “Conversation Messages” as the trigger.

Create a webhook

As soon as you “Confirm and Save”, Sunshine Conversations will make an HTTP HEAD request to the root domain of the provided URL in order to verify that the domain exists and that a service is running.

Once the creation of the webhook is complete, you’ll be able to inspect new messages you’re receiving from Facebook users. Try sending a message to your Facebook page as a Facebook user. Once you check your server logs, you’ll see the payload in all of its JSON glory.

API Requests

To send an answer back, we’ll need to call the Sunshine Conversations REST API. Sunshine Conversations provides the sunshine-conversations-client package for Node.js (available via npm). A Java API library is also available.

The sunshine-conversations-client package will handle creating an app scope JWT and authenticating calls to the REST API.

Install it with npm npm install sunshine-conversations-client

Send a message to a user with the REST API

Each time a webhook payload is received by your server on the /messages route, you can use the REST API to send a message back to the Facebook user who triggered that webhook.

To send a message via the REST API, you’re going to call the POST Message endpoint. We need to identify the user we want to send the message to. Take a look at the webhook payload you’ll be receiving.

You’ll also need some Basic Auth credentials. If you haven’t done so, create an API Key under the Settings of your new app and select “Create new API key” to generate one. Use your API Key ID as the Basic Auth username and the API Key Secret as the password. You can also use a JSON Web Token (JWT) as a bearer token to authenticate yourself.

To send a message to the user, take the conversation’s and app’s id property from the webhook payload, and POST a message to https://api.smooch.io/v2/apps/{appId}/conversations/{conversationId}/messages. Here’s an example of calling the POST Message endpoint with sunshine-conversations:

const SunshineConversationsApi = require('sunshine-conversations-client');

const defaultClient = SunshineConversationsApi.ApiClient.instance;
const basicAuth = defaultClient.authentications['basicAuth'];
basicAuth.username = 'your_key_id'; // e.g. 'app_5deaa3531c7f940010cc4ba4'
basicAuth.password = 'your_secret_key'; // e.g. 'tHyBAxPQIX_8CQNEefdc8L8B'

const apiInstance = new SunshineConversationsApi.MessagesApi();

sendMessage(appId, conversationId);

async function sendMessage(appId, conversationId) {
    let messagePost = new SunshineConversationsApi.MessagePost();
    messagePost.setAuthor({ type: 'business' });
    messagePost.setContent({ type: 'text', text: 'Live long and propser' });
    let response = await apiInstance.postMessage(appId, conversationId, messagePost);
    console.log('API RESPONSE:\n', response);
}

You can also take a look at the complete code.

Great! Now, whenever someone sends a message to your Facebook page from a Facebook user account, you should receive your auto response back.

Facebook Messenger 🎉

Next steps

  • If you’re writing in JavaScript or Java, use our API libraries, which are helpful packages that wraps calls to Sunshine Conversations APIs.

  • Now that you’ve had a taste of Sunshine Conversations, it’s time to deep dive into our reference documentation to explore the possibilities. You can find it here.

  • Take a look at the other channels we support. We’re constantly adding new channels and keeping up with the latest rich messaging features.

  • If you’re building an integration between Sunshine Conversations and your product, checkout the guides on sending and receiving messages, and you will probably want to configure webhooks via the REST API.

  • If you want to make Sunshine Conversations’ messaging capabilities an integral part of your product, take a look at our guides for Creating and Managing apps and Configuring Messaging Channels.

  • If you’re building a bot, Sunshine Conversations’ REST API is a great place to start, but you don’t have to develop it alone! Check out some of the Bot Platforms that plug into Sunshine Conversations.