Custom Inbox Integration

Webhooks

Validation

All the webhook event would come with a signature ("X-Stella-Signature") in the header for validation purposes. Each webhook event could be validated using the following method.

  1. Using the HMAC-SHA256 algorithm with the channel secret as the secret key, compute the digest for the request body.
  2. Confirm that the Base64-encoded digest matches the signature in the X-Stella-Signature request header.

Inbound Messages

Stella would relay all the events it receives to your designated webhook in 2 forms.

Raw Inbound Messages

By subscribing to this webhook, your would receive the raw events that we are receiving Noted that on Messenger, the event structure would have slight modification.

Sample from WhatsApp

Text

{
  "contacts": [
    {
      "profile": {
        "name": "Roy"
      },
      "wa_id": "85260903521"
    }
  ],
  "messages": [
    {
      "from": "85260903521",
      "id": "ABGGhSYJA1IfAgo6qRe8bWPLEpxD",
      "text": {
        "body": "Hello"
      },
      "timestamp": "1599536864",
      "type": "text"
    }
  ]
}

Video

{
  "contacts": [
    {
      "profile": {
        "name": "Roy"
      },
      "wa_id": "85260903521"
    }
  ],
  "messages": [
    {
      "from": "85260903521",
      "id": "ABGGhSYJA1IfAgo6koySp3Sro3ro",
      "timestamp": "1599537042",
      "type": "video",
      "video": {
        "id": "e8a85916-2386-49dc-8f05-1cd0527bfb68",
        "mime_type": "video/mp4",
        "sha256": "586cc370c535661c16e662f9cd2987215a878efd929073230de7cf5ec0c867ff"
      }
    }
  ]
}

Normalized Inbound Messages

By subscribing to this webhook, your would receive the normalized events that Stella pre-processed for all supported platforms.

Sample from WhatsApp

Text

{
  "from": "85260903521",
  "to": "85268227287",
  "timestamp": "1599536864",
  "type": "TEXT",
  "data": {
    "text": "Hello"
  }
}

Video

{
  "from": "85260903521",
  "to": "85268227287",
  "timestamp": "1599536864",
  "type": "MISC",
  "data": {
    "attachments": [{
      "type": "VIDEO",
      "waMediaId": "e8a85916-2386-49dc-8f05-1cd0527bfb68",
    }],
  }
}

Outbound Mesages

Bot Replied Messages

When the member (end-user) liveChat property is false, Stella would send the messages sent by chatbot to your designated webhook.

Manual Messages

All the messages sent via Stella sendResponse API would also send to your designated webhook as type MANUAL.

Relay Messages

When the member (end-user) liveChat property is true, Stella would relay the messages from and to the corresponding pairing channels, and these messages would be send to your designated webhook as type RELAY.

body
PropertyTypeDescription
typeStringCan be either BOT, MANUAL or RELAY. Indicating whether the outbound message is from the chatbot or from API
messageEventObjectmessageEvent object container the normalised message
appStringID of the app
channelStringID of the chanel
messageEvent
PropertyTypeDescription
fromStringID of the sender
toStringID of the receipient
timestampNumberUnix timestamp
typeStringMessage type*
dataObjectMessage data for the corresponding message type*
messageIdStringMessage ID from the external platform (this property might not exists)

*Please refer to the official documentation for all the message types and the structure of the corresponding message data here

Sample event
{
  type: "BOT",
  app: "app-id",
  channel: "channel-id",
  messageEvent: {
    from: "1332323131312",
    to: "443232332323",
    timestamp: 1599093015000,
    type: "TEXT",
    data: {
      text: "Hello World"
    },
    messageId: "gBGHYoUiNWZwfwIJbtM1ryHfqTdp"
  }
}

Deauthorize

When user remove the the Inbox Solution integration from his Stella app, an event would be send to the designated webhook URL.

Sample Event
{
  "account": "account-id",
  "timestamp": 1599527673000
}

APIs

Authorization

A query parameter access_token is required for all API's authorization. The access token can be generated on the Stella platform. For fine-tuning authorization, access_token with speecific scopes could be generated.

Integration API

Create Integration

Scopes: admin:app, api:admin, integration:admin, integration:write

API endpoint
PUT /integration?access_token=some-access-token
Request body

The expected body is of type JSON, all fields can be customised except the field id is reserved for internal use. The integration object should store all the credientials required of third-party integration, which could be used in the bot flow later on.

Response body
PropertyTypeDescription
okNumber1 means successful and 0 means unsuccessful
integrationIdStringID of the integration in Stella
errorObjectError object contains message field for a detailed description of the error
Sample Request
PUT '/integration?access_token=some-access-token' \
--header 'Content-Type: application/json' \
--data '{
  "accessToken": "some-token",
  "clinetId": "33233323332113",
  "clientKey": "1dasd#%5rsDD"
}'
Sample Response
{
  ok: 1,
  integrationId: "ad2T3wdsd2Gff"
}

Delete Integration

Scopes: admin:app, api:admin, integration:admin, integration:delete

API endpoint
DELETE /integration/:integrationId?access_token=some-access-token
Request parameters
PropertyTypeDescription
integrationIdStringid of the integration (required)
Response body
PropertyTypeDescription
okNumber1 means successful and 0 means unsuccessful
errorObjectError object contains message field for a detailed description of the error
Sample Request
DELETE /integration/ad2T3wdsd2Gff?access_token=some-access-token
Sample Response
{
  ok: 1
}

List Integrations

Scopes: admin:app, api:admin, integration:admin, integration:read

API endpoint
GET /integrations?access_token=some-access-token
Request parameters
PropertyTypeDescription
integrationIdStringid of the integration (required)
Response body
PropertyTypeDescription
okNumber1 means successful and 0 means unsuccessful
integrations[Object]List of integration objects under the calling OAuth client
errorObjectError object contains message field for a detailed description of the error
Sample Request
DELETE /integration/ad2T3wdsd2Gff?access_token=some-access-token
Sample Response
{
  ok: 1
}

File API

Get File From WhatsApp Media ID

Scopes: admin:app, api:admin, file:admin, file:waGet

API endpoint
GET /file/whatsapp/:mediaId?channel=wa-channel-id&access_token=some-access-token
Request parameters
PropertyTypeDescription
mediaIdStringid of the file received from WhatsApp webhook when receiving inbound voice, image, video, file messages (required)
channelStringid of the WhatsApp channel on Stella (required)
Response body
PropertyTypeDescription
okNumber1 means successful and 0 means unsuccessful
urlStringPublic URL of the requested media
errorObjectError object contains message field for a detailed description of the error

Send API

Send Responses

Scopes: admin:app, api:admin, bot:admin, bot:sendResponses

Please refer here for detailed documentation.

Member API

Get Member

Scopes: admin:app, api:admin, member:admin, member:read

API endpoint
GET /member?member_id=member-id&external_id=extenal-id&access_token=some-access-token
Request parameters
PropertyTypeDescription
external_idStringPlatform-specific ID of the member i.e. PSID for Messenger, phone number (WAID) for WhatsApp, etc. (Either external_id or member_id is required)
member_idStringID of the member in Stella (Either external_id or member_id is required)
Response body
PropertyTypeDescription
okNumber1 means successful and 0 means unsuccessful
memberObjectmember object in Stella. Please see the documentation on Member for more details
errorObjectError object contains message field for a detailed description of the error
Sample Request
GET /member?external_id=external-id&access_token=some-access-token
Sample Response
{
  ok: 1,
  member: {
    "_id" : "5efaeba88bb86af1c4dad0b5",
    "externalId" : "85260903521",
    "app" : "app-id",
    "channel" : "channel-id",
    "platform" : "whatsapp",
    "profile" : {
        "name" : "Roy"
    },
    "tags" : [],
    "meta" : {},
    "botMeta" : {
        "subscribe" : true,
        "liveChat" : false,
        "tempData" : {}
    },
    "botId" : "",
    "admin" : null,
    "group" : null,
    "fbId" : null,
    "firstName" : "Roy",
    "lastName" : null,
    "name" : null,
    "profilePic" : null,
    "gender" : null,
    "locale" : null,
    "email" : null,
    "profilePicString" : null,
    "createdAt" : 1593502632638.0,
    "etag" : "d-ofrj2T5gf2N6yqpvr/eQdNgcqUs",
    "_version" : 2
  }
}

Toggle LiveChat

Scopes: admin:app, api:admin, member:admin, member:write

API endpoint
PATCH /member/live_chat?access_token=some-access-token
Request body
PropertyTypeDescription
externalIdStringPlatform-specific ID of the member i.e. PSID for Messenger, phone number (WAID) for WhatsApp, etc. (Either externalId or memberId is required)
memberIdStringID of the member in Stella (Either externalId or memberId is required)
liveChatBooleanUpdate member's liveChat property to true or false
Response body
PropertyTypeDescription
okNumber1 means successful and 0 means unsuccessful
memberIdStringID of the member in Stella
errorObjectError object contains message field for a detailed description of the error
Sample Request
PATCH '/member/live_chat?access_token=some-access-token' \
--header 'Content-Type: application/json' \
--data '{
  "appId": "app-id",
  "externalId": "33233323332113",
  "liveChat": true
}'
Sample Response
{
  ok: 1,
  memberId: "some_member_id"
}
← LUISData Source →