API Quickstart


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.

First, create a new page.

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 “App User Messages” as the trigger.

Create a webhook

As soon as you “Confirm and Save”, you’ll be able to inspect the 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 smooch-core package for Node.js (available via npm). Ruby, Python & Java API libraries are also available.

The smooch-core package will handle creating an app scope JWT and authenticating calls to the REST API.

Install it with npm npm install smooch-core

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.

To send a message to the user, take the appUser’s _id property from the webhook payload, and POST a message to https://app.smooch.io/v1.1/appusers/{appUser._id}/messages. Here’s an example of calling the POST Message endpoint with smooch-core:

const Smooch = require('smooch-core');

const KEY_ID = 'your_key_id'; // e.g. 'app_5deaa3531c7f940010cc4ba4'
const SECRET = 'your_secret_key'; // e.g. 'tHyBAxPQIX_8CQNEefdc8L8B'

const smooch = new Smooch({
    keyId: KEY_ID,
    secret: SECRET,
    scope: 'app'

// POST Message
        userId: appUserId,
        message: {
            type: 'text',
            text: 'Live long and prosper',
            role: 'appMaker'
    .then((response) => {
        console.log('API RESPONSE:\n', response);
    .catch((err) => {
        console.log('API ERROR:\n', err);

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, Ruby, Python 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.