(Last updated 2019-10-08 11:47:55 CEST)

This documents how an external interface with which telegra KIT can communicate should be implemented.

1. Introduction

It is possible to implement a passive interface for telegra KIT. Telegra KIT will contact this passive interface when either specific intents are recognized, or at the end of every call. The interface to implement are several endpoints reachable via https. In the configuration of a bot it is possible to provide an IP or URL and a port. If no port is specified communication will default to port 443. The bot will then assume that the appropriate endpoints exist and will send requests when appropriate.

All request are of type application/json. When referings to the fields of a request, we refer to the fields of the json object we send.

The expected response to all requests is 200. If the status code in the response to any request has a different value we assume an error occurred.

2. Authentication

The implementer of the interface needs to generate a token and set this as the token for a bot on the telegra KIT Web configuration. This token will be sent in every request as a bearer token, i.e., it will be sent along in the Authorization field of the header as "Bearer <token>" in every request.

3. Conversation Object

A conversation object is a list of dictionaries. Every entry in the list contains some part of the dialog between the bot and the caller, possibly a recognized intent, and what the bot decided to do if the caller did not hang up. More specifically, every entry in the list has the following fields.

  • dialog: This is a list with an entry for every thing that either the bot or the caller said before the bot performed the next action (forward the call, hang up or change the mode) or the caller hung up. Every entry is of the form:

    {
      "speaker": <string>,
      "text": <string>
    }

    The value of speaker will be either BOT or USER and the value of text will be either what we understood the caller to have said or what the bot said.

  • intent: The name of the intent that was recognized as a string, null if no intent was recognized.

  • continuation: This is an object. If the call was interrupted by the caller this will be null. If not, it always contains the field value, telling you which action the bot performed. The following values are possible:

    • CHANGE_MODE: The bot decided to change the mode. In this case the object has two more field:

      • mode: The mode to which the bot changed.

      • next_question: What the bot is going to say after changing mode.

    • SIMPLE_ANSWER: The bot decided to give an answer and end the conversation. The object has one more field:

      • answer: What the bot will say before ending the conversation.

    • FORWARD: The bot decided to forward the call. The object has two more fields:

      • answer: What the bot will say before forwarding the call.

      • line: The line to which the call should be forwarded.

    • REDIRECT_TO_DEFAULT: The bot decided it cannot continue the conversation and to forward the call the the standard line. The object contains two more fields.

      • apology: What the bot will say before forwarding to the default line.

      • line: The default line.

4. Endpoints

4.1. Call Notification

POST /call

If enabled in the configuration, this will be called at the end of every call.

Fields
Field Name Type Content

timestamp

float

Unix timestamp of the moment the call started.

username

string

The username to which this bot belongs.

bot_name

string

The name of the called bot.

bot_id

string

The id of the called bot in our system.

call_id

string

The id of the call in our system.

phone_number

string

The number from which the bot was called.

caller_hung_up

boolean

A boolean indicating if the caller hung up before the last action of the bot could be performed.

forward_to_default_line

boolean

Indicates if the call was forwarded to the default line.

call

object

A conversation object with the dialog between bot and caller for this call.

4.2. Intent Notification

POST /intent

This will be called when an intent, for which the option to notify the external interface has been enabled, is recognized.

Fields
Field Name Type Content

timestamp

float

Unix timestamp of the moment the call started.

username

string

The username to which this bot belongs.

bot_name

string

The name of the called bot.

bot_id

string

The id of the called bot in our system.

classification_id

string

The id of this classification in the system.

intent

string

The name of the intent.

mode

string

The name of the mode.

call_id

string

The id of the call in our system.

phone_number

string

The number from which the bot was called.

call

object

A conversation object with the dialog between bot and caller up to the point where this intent was recognized.

5. Error Handling

It is possible to specify an Email address to which emails are sent when errors in the communication with an interface occur. Whenever the communication fails, either because the interface is down, or the return value was not 200, the system will log this error and send it in an email. These emails are throttled in case an error repeats too often. At most one email every 5 minutes is sent. After an error occurs it will take at most 10 minutes for an email to be sent (please be aware that receiving the email might take some additional time). The email contains the last 50 errors that were registered since the last email was sent.