Remote Conversation Eventing

Summary

Remote conversation eventing provides the ability to forward events from conversations with end-users to a service of your choice and design. These events can then be used with your own infrastructure to achieve any external integrations desired. To get started, contact your ServisBOT representative.

Remote Conversation Eventing is a Beta feature.

Remote Conversation Eventing may be added to your ServisBOT package at an additional cost.

“”

Technical Details

Remote Conversation Eventing egresses conversational data from the ServisBOT platform to a URL provided by the Customer. The URL must:

  1. Support a HTTPS Post Request with a JSON Body
  2. Return a 200 status code on successful receipt

It is possible that a record may arrive more than once, duplicates can be identified via the id field. Events may arrive out of order, however the timestamp will always represent the correct order.

Authorization

ServisBOT can add an API Key or a JWT to the header of the request sent to the remote endpoint. Please liaise with your ServisBOT contact to configure this. As an added layer of security, all requests egress from a known set of IP Addresses that can be added to the receivers firewall rules.

Type of events

Currently three content types egressed from our conversation eventing:

  1. Message - content is text
  2. Markup - content is rich media in ServisBOT Timeline Markup Language
  3. Markup Interaction - an interaction on a Markup item in our Messenger. The Markup message is identified via the source fields in the contents object.

An example of all of the above is shown in the Examples section of this document.

Event body

Full example event body

{
    "message": {
        "version": "v2",
        "type": "TimelineMessage",
        "contentType": "message",
        "contents": {
            "message": "thanks"
        },
        "correlationId": "GAUQ7wYJp",
        "conversationId": "391ab66c-d3c9-415d-87ce-9b9d92a9e754",
        "id": "0m1EHNXkDW",
        "to": "server",
        "timestamp": 1683561232082,
        "organization": "acme",
        "identity": "eu-west-1:35e22cb7-9683-40c7-aec4-8c5432d6b43f",
        "inputSource": {
            "type": "utterance"
        },
        "endpoint": {
            "address": "acme-bot"
        }
    }
}

Keys

conversationId:

  • description: Conversation identifier. ShortId or UUID
  • type: string
  • example: dxig0lgk2y

identity:

  • type: string
  • description: User identifier
  • example: eu-west-1:73659d16-e526-4a3f-9044-3ca5b4d35f68

id:

  • type: string
  • description: The message identifier. ShortId or a UUID
  • example: _ctBcIqYu-

timestamp:

  • type: number
  • description: The time the message was created
  • example: 1582022674824

organization:

  • type: string
  • description: The organization this message belongs to
  • example: acme

type:

  • type: string
  • description: The ServisBot defined category of the content
  • example: TimelineMessage

contentType:

  • type: string
  • description: The ServisBot defined type of the content
  • example: markup

to:

  • type: string
  • description: The direction of the message. “server” or “client”
  • example: server

version:

  • type: string
  • description: The ServisBot internal message schema version
  • example: v2

correlationId:

  • type: string
  • description: The ServisBot correlationId, a shortId
  • example: kwB6sC8Mr

customerReference:

  • type: string
  • description: A unique identifier for a customer
  • example: unique-customer-reference

contents:

  • type: object
  • description: The contents of the message, can be message or markup with context
  • properties:
    • message:
      • type: string
      • description: The text of the user or bot message
      • example: Hello, how are you?
    • markup:
      • type: string
      • description: The text of the user or bot message represented as ServisBot Markup
      • example: Hello!
    • source:
      • description: the related message for the interaction
      • type: object
      • example: a markupInteraction would have a source of the TimelineMessage where the interaction happened

Examples

Simple Message

{
    "message": {
        "version": "v2",
        "type": "TimelineMessage",
        "contentType": "message",
        "contents": {
            "message": "thanks"
        },
        "correlationId": "GAUQ7wYJp",
        "conversationId": "391ab66c-d3c9-415d-87ce-9b9d92a9e754",
        "id": "0m1EHNXkDW",
        "to": "server",
        "timestamp": 1683561232082,
        "organization": "acme",
        "identity": "eu-west-1:35e22cb7-9683-40c7-aec4-8c5432d6b43f",
        "inputSource": {
            "type": "utterance"
        },
        "endpoint": {
            "address": "acme-bot"
        }
    }
}

cURL

curl --location --request POST 'www.acme.com/integrations/servisbot/events' \
--header 'Authorization: ApiKey myApiKey' \
--header 'X-Correlation-Id: XWcgeIsWR' \
--header 'Content-Type: application/json' \
--data-raw '{
    "message": {
        "version": "v2",
        "type": "TimelineMessage",
        "contentType": "message",
        "contents": {
            "message": "thanks"
        },
        "correlationId": "GAUQ7wYJp",
        "conversationId": "391ab66c-d3c9-415d-87ce-9b9d92a9e754",
        "id": "0m1EHNXkDW",
        "to": "server",
        "timestamp": 1683561232082,
        "organization": "acme",
        "identity": "eu-west-1:35e22cb7-9683-40c7-aec4-8c5432d6b43f",
        "inputSource": {
            "type": "utterance"
        },
        "endpoint": {
            "address": "acme-bot"
        }
    }
}'

Markup Event

{
    "message": {
        "version": "v2",
        "type": "TimelineMessage",
        "contentType": "markup",
        "contents": {
            "markup": "<TimelineMessage>\n      <ButtonPromptContainer interactionType=\"event\" preventRetries=\"true\" >\n        <ButtonPrompt label=\"Option One\" id=\"0\" />\n        <ButtonPrompt label=\"Option Two\" id=\"1\" />\n        <ButtonPrompt label=\"Option Three\" id=\"2\" />\n      </ButtonPromptContainer>\n    </TimelineMessage>",
            "markupObject": {
                "TimelineMessage": {
                    "#name": "TimelineMessage",
                    "children": [
                        {
                            "attributes": {
                                "interactionType": "event",
                                "preventRetries": "true"
                            },
                            "#name": "ButtonPromptContainer",
                            "children": [
                                {
                                    "attributes": {
                                        "label": "Option One",
                                        "id": "0"
                                    },
                                    "#name": "ButtonPrompt"
                                },
                                {
                                    "attributes": {
                                        "label": "Option Two",
                                        "id": "1"
                                    },
                                    "#name": "ButtonPrompt"
                                },
                                {
                                    "attributes": {
                                        "label": "Option Three",
                                        "id": "2"
                                    },
                                    "#name": "ButtonPrompt"
                                }
                            ]
                        }
                    ]
                }
            }
        },
        "correlationId": "XWcgeIsWR",
        "conversationId": "391ab66c-d3c9-415d-87ce-9b9d92a9e754",
        "id": "HUnkGJp8io",
        "to": "client",
        "timestamp": 1683561222398,
        "organization": "acme",
        "endpoint": {
            "address": "acme-bot"
        }
    }
}

cURL

curl --location --request POST 'www.acme.com/integrations/servisbot/events' \
--header 'Authorization: ApiKey myApiKey' \
--header 'X-Correlation-Id: XWcgeIsWR' \
--header 'Content-Type: application/json' \
--data-raw '{
    "message": {
        "version": "v2",
        "type": "TimelineMessage",
        "contentType": "markup",
        "contents": {
            "markup": "<TimelineMessage>\n      <ButtonPromptContainer interactionType=\"event\" preventRetries=\"true\" >\n        <ButtonPrompt label=\"Option One\" id=\"0\" />\n        <ButtonPrompt label=\"Option Two\" id=\"1\" />\n        <ButtonPrompt label=\"Option Three\" id=\"2\" />\n      </ButtonPromptContainer>\n    </TimelineMessage>",
            "markupObject": {
                "TimelineMessage": {
                    "#name": "TimelineMessage",
                    "children": [
                        {
                            "attributes": {
                                "interactionType": "event",
                                "preventRetries": "true"
                            },
                            "#name": "ButtonPromptContainer",
                            "children": [
                                {
                                    "attributes": {
                                        "label": "Option One",
                                        "id": "0"
                                    },
                                    "#name": "ButtonPrompt"
                                },
                                {
                                    "attributes": {
                                        "label": "Option Two",
                                        "id": "1"
                                    },
                                    "#name": "ButtonPrompt"
                                },
                                {
                                    "attributes": {
                                        "label": "Option Three",
                                        "id": "2"
                                    },
                                    "#name": "ButtonPrompt"
                                }
                            ]
                        }
                    ]
                }
            }
        },
        "correlationId": "XWcgeIsWR",
        "conversationId": "391ab66c-d3c9-415d-87ce-9b9d92a9e754",
        "id": "HUnkGJp8io",
        "to": "client",
        "timestamp": 1683561222398,
        "organization": "acme",
        "endpoint": {
            "address": "acme-bot"
        }
    }
}'

Markup Interaction Event

{
    "message": {
        "version": "v2",
        "type": "TimelineMessage",
        "contentType": "markupInteraction",
        "contents": {
            "source": {
                "eventType": "TimelineMessage",
                "timestamp": 1683561222398,
                "id": "HUnkGJp8io",
                "conversationId": "391ab66c-d3c9-415d-87ce-9b9d92a9e754"
            },
            "interaction": {
                "action": "buttonInteraction",
                "value": {
                    "id": "2",
                    "label": "Option Three"
                },
                "timestamp": 1683561225799
            }
        },
        "correlationId": "zTDaXjPAv",
        "conversationId": "391ab66c-d3c9-415d-87ce-9b9d92a9e754",
        "id": "HUnkGJp8io",
        "to": "server",
        "timestamp": 1683561225461,
        "organization": "acme",
        "endpoint": {
            "address": "acme-bot"
        },
        "inputSource": {
            "type": "interaction"
        }
    }
}

cURL

curl --location --request POST 'www.acme.com/integrations/servisbot/events' \
--header 'Authorization: ApiKey myApiKey' \
--header 'X-Correlation-Id: XWcgeIsWR' \
--header 'Content-Type: application/json' \
--data-raw '{
    "message": {
        "version": "v2",
        "type": "TimelineMessage",
        "contentType": "markupInteraction",
        "contents": {
            "source": {
                "eventType": "TimelineMessage",
                "timestamp": 1683561222398,
                "id": "HUnkGJp8io",
                "conversationId": "391ab66c-d3c9-415d-87ce-9b9d92a9e754"
            },
            "interaction": {
                "action": "buttonInteraction",
                "value": {
                    "id": "2",
                    "label": "Option Three"
                },
                "timestamp": 1683561225799
            }
        },
        "correlationId": "zTDaXjPAv",
        "conversationId": "391ab66c-d3c9-415d-87ce-9b9d92a9e754",
        "id": "HUnkGJp8io",
        "to": "server",
        "timestamp": 1683561225461,
        "organization": "acme",
        "endpoint": {
            "address": "acme-bot"
        },
        "inputSource": {
            "type": "interaction"
        }
    }
}'