Apply Stella API to Chatbot

Stella API allows an external application to trigger the following types of bot actions in Stella:

The common use case is when you want to activate Stella to send a message to a user based on the action of your external application. For example, you want to send a purchase confirmation message to a WhatsApp user after that person has completed a purchase on your online store and provided the WhatsApp number.

Getting Hands-on

This procedure will teach you how to test the Stella API (i.e. POST) on Postman.

Send Response

  1. Create a new request on Postman and add https://bot.stellabot.com/sendResponses to the request URL.

Create a new Postman request

  1. Change the request type to POST.

  2. Generate an access token with bot:sendResponses permission and put it to "VALUE" under "Params". Mark accessToken under "KEY".

Input Postman request Params
  1. Head to "Body" and choose "raw" and "JSON".

Select Postman Request Body Type
  1. Paste the body code of "Send Responses". The code below is just a sample, you should edit the response according to your needs. You can find out the JSON for the response object in the advanced tab of the response builder. You can also generate different types of responses on Stella.
{
  "channelId": "5ece50e72efaabd58ef55027",
  "fbUserRef": null,
  "memberId": "5ece50f3bf385b25c4e08db5",
  "recipientId": null,
  "messagingType": "MESSAGE_TAG",
  "messagingTag": "CONFIRMED_EVENT_UPDATE",
  "response": [
    {
      "type": "TEXT",
      "text": "Hello World"
    },
    {
      "type": "IMAGE",
      "url": "https://miro.medium.com/max/1200/1*mk1-6aYaf_Bes1E3Imhc0A.jpeg"
    }
  ]
}
  1. You should be able to find the channelID from your channel and recipientID/memberID/fbUserRef from the member page.

Input Postman Request Body
  1. Click "Send". It should return the following 200 response:
  • Successful:
{
  "ok": 1,
  "member": "5ece50f3bf385b25c4e08db5",
  "sendResults": [
    {
      "result": [
        {
          "result": {
            "recipient_id": "10152368852405295",
            "message_id": "m_U0EmmN476hlyPr-0iH2cXMcrTLJ5HeVUQjzqok8vkkF8wnJpPkagYbXU5hr0bXWHM5PPYjgd9RWG10K0oujeHQ"
          },
          "messageEvent": {
            "from": "124830722411862",
            "to": "10152368852405295",
            "data": {
              "text": "Hello World"
            },
            "type": "TEXT",
            "timestamp": 1583292367324,
            "messageId": "  -0iH2cXMcrTLJ5HeVUQjzqok8vkkF8wnJpPkagYbXU5hr0bXWHM5PPYjgd9RWG10K0oujeHQ"
          }
        },
        {
          "result": {
            "recipient_id": "10152368852405295",
            "message_id": "m_U0EmmN476hlyPr-0iH2cXMcrTLJ5HeVUQjzqok8vkkF8wnJpPkagYbXU5hr0bXWHM5PPYjgd9RWG10K0oujeHQ"
          },
          "messageEvent": {
            "from": "124830722411862",
            "to": "10152368852405295",
            "data": {
              "url": "https://miro.medium.com/max/1200/1*mk1-6aYaf_Bes1E3Imhc0A.jpeg"
            },
            "type": "IMAGE",
            "timestamp": 1583292367324,
            "messageId": "  -0iH2cXMcrTLJ5HeVUQjzqok8vkkF8wnJpPkagYbXU5hr0bXWHM5PPYjgd9RWG10K0oujeHQ"
          }
        }
      ]
    }
  ]
}
  • Failure:
{
  "ok": 0,
  "err_code": 108,
  "err": "Either memberId or recipientId or fbUserRef is required.\""
}

You can also check out the list of error code here.

Redirect Member To Node

  1. Create a tree node in a tree and add this tree to the channel you will use for this POST request.

  2. Create a new request on Postman and add https://bot.stellabot.com/redirectMemberToNode to the request URL.

Create a new Postman request

  1. Change the request type to POST.

  2. Generate an access token with bot:redirectMemberToNode permission and put it to "VALUE" under "Params". Mark accessToken under "KEY".

Input Postman request Params
  1. Head to "Body" and choose "raw" and "JSON".

Select Postman Request Body Type
  1. Paste the body code of "Redirect Member To Node". The code below is just a sample, you should change the tree & nodeCompositeId to the ones in the tree node you created in step 1.
{
  "channelId": "5ece50e72efaabd58ef55027",
  "fbUserRef": null,
  "memberId": "5ece50f3bf385b25c4e08db5",
  "recipientId": null,
  "redirect": {
    "tree": "5ecf6cfba3b6643c33a64079",
    "nodeCompositeId": "j4Bivxm0GWhnNV1m",
    "runPreAction": true,
    "sendResponse": null,
    "runPostAction": false
  },
  "meta": {
    "name": "Sanuker",
    "orderId": "5ecf6be76fcfda6b139d802c"
  }
}
  1. You should be able to find the channelID from your channel and recipientID/memberID/fbUserRef from the member page.

Input Postman Request Body
  1. Click "Send". It should return the following 200 response:
  • Successful:
{
  "ok": 1,
  "member": "5ece50f3bf385b25c4e08db5",
  "sendResults": [
    {
      "result": [
        {
          "result": {
            "recipient_id": "10152368852405295",
            "message_id": "m_U0EmmN476hlyPr-0iH2cXMcrTLJ5HeVUQjzqok8vkkF8wnJpPkagYbXU5hr0bXWHM5PPYjgd9RWG10K0oujeHQ"
          },
          "messageEvent": {
            "from": "124830722411862",
            "to": "10152368852405295",
            "data": {
              "text": "Hello World"
            },
            "type": "TEXT",
            "timestamp": 1583292367324,
            "messageId": "  -0iH2cXMcrTLJ5HeVUQjzqok8vkkF8wnJpPkagYbXU5hr0bXWHM5PPYjgd9RWG10K0oujeHQ"
          }
        },
        {
          "result": {
            "recipient_id": "10152368852405295",
            "message_id": "m_U0EmmN476hlyPr-0iH2cXMcrTLJ5HeVUQjzqok8vkkF8wnJpPkagYbXU5hr0bXWHM5PPYjgd9RWG10K0oujeHQ"
          },
          "messageEvent": {
            "from": "124830722411862",
            "to": "10152368852405295",
            "data": {
              "url": "https://miro.medium.com/max/1200/1*mk1-6aYaf_Bes1E3Imhc0A.jpeg"
            },
            "type": "IMAGE",
            "timestamp": 1583292367324,
            "messageId": "  -0iH2cXMcrTLJ5HeVUQjzqok8vkkF8wnJpPkagYbXU5hr0bXWHM5PPYjgd9RWG10K0oujeHQ"
          }
        }
      ]
    }
  ]
}
  • Failure:
{
  "ok": 0,
  "err_code": 108,
  "err": "Either memberId or recipientId or fbUserRef is required.\""
}

You can also check out the list of error code here.

Advacned

As mentioned in the previous section, Redirect Member to Node allows you to redirecting a member to a specific node in the tree, and execute all or partial components of the node. It is useful for performing complex operations on a member and keeping all the bot logic in the tree instead of hardcoding in an api.

In some cases, you might want to send customized messaage to customers instead of a standardized message. Therefore, this advanced guide is going to demonstrate how you can send message with variables using Redirect Member to Node.

Introduction

In this example, we would like to send an order confirmation to customers on WhatsApp using Redirect Member to Node. The message will include variables such as the purchased item and the order number.

To do this, you will need to make use of meta object to pass the variables to the node using API. The variables will be saved to the member's TempData. After that, the variables can be extracted and applied to the response you are going to send out.

Meta Object

While applying Redirect Member to Node, you can also use API to pass meta object to the targeted node. In this example, the Meta Object contains two info: the orderID and item, which we would like to later apply to the response as variables.

For more details about how to construct the request, please refer to BotAPI.

{
 "channelId": "611492017e746925434536d",
 "recipientId": "65874121234",
 "redirect": {
  "tree": "60ff7a60fe96167111244s",
  "nodeCompositeId": "gQEytkyMjZdwR69N"
 },
 "meta": {
  "orderID": "FP123456789",
  "item": "Graphic T-shirt"
 },
 "accessToken": "ACCESS_TOKEN",
 "headers": {
  "Content-Type": "application/json",
  "Origin": "https://bot.stellabot.com"
 }
}

Template Message Submission

Before we start building the node, we need to first submit a Template Message to WhatsApp for approval.

  1. Follow the this guide for drafting and submitting your template messsage to WhatsApp.

  1. While creating the template, you can make use of the parameter placeholders in the format of {{1}}.

Example:

Your order {{1}} is ready! It will be deilvered within 3 days.

Item: {{2}}

Please contact our hotline if you have any questions.

Create a Node

  1. In Stella, select Bot Builder and first create a new tree.

  1. Create a tree node, this tree node will be used for Redirect Member to Node. End users will be redirected to this node, and the components of this node will be executed.

Create a Pre-action - Saving Meta Object

  1. Create a new pre-action.

  1. Insert the following code into the pre-action. It is for saving the Meta Object in the member's tempData.
return new Promise((resolve) => {
  this.member.botMeta.tempData.orderID = this.agendaMeta.orderID
  this.member.botMeta.tempData.item = this.agendaMeta.item
  resolve({ member: this.member })
})

In Members, you can view the tempData in a member's profile.

Apply Variable to Response

  1. Create a new response.

  1. Select WhatsApp Message Template as the response type, adn select the template you have just created.

  1. The following code can let you have access to the variables saved in tempData.
{{botMeta.tempData.orderID}}
  1. While filling in the variables of the Template Message, you can insert the above code in the corresponding field and get the relevant info from tempData.

  1. Now, you can test by sending the API request of Redirect Member to Node to a tester and see if it can display the expected order confirmation message.
← Apply Agenda to ChatbotApply Web Event to Webchat Chatbot →