Webhook service

To use fulfillment in a production system, you should implement and deploy a webhook service. To handle fulfillment, your webhook service needs to accept JSON requests and return JSON responses as specified in this guide. The detailed processing flow for fulfillment and webhooks is described in the fulfillment overview document.

Webhook service requirements

The following requirements must be met by your webhook service:

• It must handle HTTPS requests. HTTP is not supported.
• Its URL for requests must be publicly accessible.
• It must handle POST requests with a JSON WebhookRequest body.
• It must respond to WebhookRequest requests with a JSON WebhookResponse body.

Webhook request

When an intent configured for fulfillment is matched, Pingstreams sends an HTTPS POST webhook request to your webhook service. The body of this request is a JSON object with information about the matched intent.

In addition to the end-user query, many integrations also send some information about the end-user as well. For example, an ID to uniquely identify the user.

Here is a sample request:

{
  "token": "THE-CONVERSATION-TOKEN",
  "payload": {
    "intent": {
      "intent_display_name": "THE-INTENT-NAME"
    },
    "message": {
      "text": "THE-ORIGINAL-INTENT-STATIC-REPLY",
      "request": {
        "request_id": "THE-REQUEST-ID",
        "language": "THE-END-USER-ISO-LANG"
      }
    },
    "bot": {
      "name": "THE-BOT-NAME",
      "_id": "THE-BOT-UNIQUE-ID",
      "project_id": "THE-PROJECT-THIS-BOT-BELONGS-TO"
    }
  }
}

The token

const token = req.body.token;

While replying to the end-users may look as a synchronous action, it is not.

To reply you use the HTTP “res” object, but using the conversation token you can send as many messages as you want back to the conversation, using Pingstreams messaging APIs.

Simply set this token in the Authorization field of the send-message API.

The webhook payload

When an intent configured for fulfillment is matched, Pingstreams sends an HTTPS POST webhook request to your webhook service. The body of this request is a JSON object with information about the matched intent. The payload property contains most of the information needed.

let payload = req.body.payload;

Intent data

Within the payload you can find many information about the current detected intent, i.e. its display name:

let intent = payload.intent;
let intent_name = intent.intent_display_name;

Intent static reply

The original static text that you set to reply to the user is also embedded in the payload:

const static_text = payload.message.text;

Chatbot metadata

Chatbot metadata are sent to your webhook, so you can have enough data to take the right actions based on the selected chatbot:

let bot = payload.bot;
let bot_name = bot.name;

Chatbot id

Just two words about the chatbot ID. In Pingstreams the chatbot ID is a UUID. But inside a support conversation (that is ‘group’ conversation, where many participants can be involved) the chatbot participant ID always has a “bot_” prefix. This prefix helps Pingstreams to immediately recognize a chatbot among the other participants, taking the right actions.

If you want to play with chatbots in the conversation (using orchestration APIs) always remember to prefix the chatbot ID with “bot_” before adding it to a conversation or to recognize it in the same conversation, like in the following example:

let bot = payload.bot;
let bot_id = bot._id;
let bot_id_as_conversation_participant = "bot_" + bot_id;

User language

This property is the language the user is using (i.e. the browser language):

let user_lang = payload.message.request.language;

Project id

const projectId = payload.bot.id_project;

The Request metadata

const request = payload.message.request;
const requestId = payload.message.request.request_id;