Webhook Adapter

The Webhook engagement adaptor enables you to create a custom integration with ServisBOT using HTTP APIs.

Setting up a Webhook engagement adaptor.

To create a Webhook based adaptor, you will need to first create a secret. This secret will be used as your Bearer API key, and will be used to secure the API calls you make to ServisBOT along with the webhook events your API will receive in response. You’ll need to remember the value of this Secret - we’ll need it later, and you cannot retrieve secrets after they have been created. The secret should be of type Bearer token. Secret Config

Then, you’ll need to create an endpoint with Engagement Adapter of type Webhook. Your endpoint will have a unique address - keep this, we’ll need it later. You’ll also need to point to the secret you just created, and also provide a Url where webhook events get sent to on egress.

Example Endpoint Configuration

Here is an example endpoint:

{
  "Address": "myorganization-webhook",
  "OutboundBotReference": "MyBot",
  "InboundBotReference": "MyBot",
  "EngagementType": "Webhook",
  "Status": "online",
  "AllowedDomains": [
    "*.servisbot.com",
    "https://servisbot.com"
  ],
  "EngagementConfig": {
    "Secret": "srn:vault::myorganization:secret:webhookApiKey",
    "Url" : "https://myapi.com/webhook"
  },
  "Useragent": "useragent",
  "TargetBotReference": "MyBot",
  "Name": "MyWebhook"
}

You will need to make note of the Address portion of your endpoint - we’ll be using it later.

Ingress: Send messages to a Bot on behalf of a User

It is possible to send in plain text messages on behalf of a user, and also to update context. For this step, we’ll need:

  • Your ServisBOT Region Name.
  • Some unique identifier for your user - this could be an email address, a phone number, or a unique ID you generate.
  • Your API Key Secret (created earlier).
  • Your Endpoint Address (created earlier).

To send a plain text message:

(replace YOUR_ENDPOINT_ADDRESS, YOUR_REGION, YOUR_API_KEY and YOUR_UNIQUE_REFERENCE accordingly)

curl -X POST https://engagement.YOUR_REGION.servisbot.com/picard/v1/engage/YOUR_ENDPOINT_ADDRESS \ -H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"Type":"message", "Value":"Hi!", "CustomerReference":"YOUR_UNIQUE_REFERENCE"
}'

To update the context as a standalone action:

curl -X POST https://engagement.YOUR_REGION.servisbot.com/picard/v1/engage/YOUR_ENDPOINT_ADDRESS \ -H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"Type":"context", "Value":{ "Leve" : "Gold", "Name" : "Bob" }, "CustomerReference":"YOUR_UNIQUE_REFERENCE"
}'

To send a page event:

curl -X POST https://engagement.YOUR_REGION.servisbot.com/picard/v1/engage/YOUR_ENDPOINT_ADDRESS \ -H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"Type":"pageEvent", "Value":{ "alias":"pageEventAlias", body:{ /*Additional page event data here*/ }}, "CustomerReference":"YOUR_UNIQUE_REFERENCE"
}'

To update context while using the other message types of message & pageEvent:

curl -X POST https://engagement.YOUR_REGION.servisbot.com/picard/v1/engage/YOUR_ENDPOINT_ADDRESS \ -H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"Type":"message", "Value":"Hi!", "CustomerReference":"YOUR_UNIQUE_REFERENCE", Context: { "Leve" : "Gold", "Name" : "Bob" }
}'

Egress: Receive messages as a User from a Bot

Messages will egress over webhook. Your endpoint should check the Authorization header, ensuring its value is of the form Bearer $apikey, where $apikey matches the value provided when creating the secret above. All messages are sent over HTTP POST.

Content Types

There are three possible ContentTypes that can appear in your payload:

  1. “ContentType”: “HostNotification”: host notifications sent to your API will have this content type in the payload.
  2. “ContentType”: “TimelineMarkup”: timeline markup sent to your API will have this content type in the payload.
  3. “ContentType”: “Message”: messages sent to your API will have this content type in the payload.

Payloads

Messages sent to your API will have the following payload:

{
  "Messages": [
    "Hello World!"
  ],
  "CustomerReference": "hello@servisbot.com",
  "ContentType": "Message",
  "Timestamp": 1623666214
}

Timeline Markup sent to your API will have the following payload:

{
  "Markdown": [
    {
      "message": "Hello world!",
      "type": "message"
    },
    {
      "type": "detailView",
      "title": "Details",
      "description": "My new detail view",
      "url": "http://www.servisbot.com"
    }
  ],
  "CustomerReference": "hello@servisbot.com",
  "ContentType": "TimelineMarkup",
  "Timestamp": 1623666214
}

Host Notifications sent to your API will have the following payload:

{
  "HostNotification": "This is always a string - you may choose to send stringified JSON in this field",
  "CustomerReference": "hello@servisbot.com",
  "ContentType": "HostNotification",
  "Timestamp": 1623666214
}