SmartIVR - ChatBot API connector

This document describres the expected API interface to connect our SmartIVR to any external ChatBot service.

Our SmartIVR will perform the following POST request each time it has the user input in text form and expects the specified JSON format containing one of the possible response types.

The SmartIVR will add with each request an Authorization header containing a security token so it can be identified by the API.

Request

In each request the SmartIVR will send an ID to identify the conversation, with a format of PHONE-CALLTIMESTAMP, and a text containing the user's input. All request will include two headers with the information of the detected user phone (X-Phone) and the number that is called (X-Destination) in case they apply to the bussiness logic performed by the bot.

Headers

Header	Value
Authorization	Bearer TOKEN
Content-Type	application/json
X-Phone	The user's phone as viewed by the SmartIVR
X-Destination	The number that the user dialed to reach this voice service

Body

Field	Value
id	Identification of the conversation
text	Transcription of the user speech

Example

{
    "id": "666555444-1784037502",
    "text": "I need help with my new account"
}

Response

There are four different kind of supported actions that the SmartIVR can perform based on the ChatBot's reasoning:

ask: Play a text to the user and starts listening for the next user input.
info: Play a text to the user and inmediatly do a new request through the API with an empty text.
transfer: Transfer the call to the destiny specified on the dest field. It may add metadata if needed to send to the remote called party.
hangup: To finish and hangup the call.

Field	Type	Required	Value
type	string	yes	Type of the action to perform, must be one of "ask\|info\|transfer\|hangup"
lang	string	only if field `text` exists	Language code of the text to play. It must follow the BCP 47 format (e.g. en-US, es-ES)
text	string	only in ask or info responses	Text to play to the user
dest	string	only in transfer responses	DDI or extension to transfer the call to
metadata	MetadataObjects[]	only in transfer responses	List of metadata to add to the transfer
metadata[].name	string	only in transfer responses	Name of the metadata value
metadata[].value	string	only in transfer responses	Value of the metadata name

Examples

Ask example

{   
    "type": "ask",
    "text": "How can I help you?",
    "lang": "en-US"
}

Info example

{   
    "type": "info",
    "text": "For your security I inform you that this call may be recorded.",
    "lang": "en-US"
}

Transfer example

{   
    "type": "transfer",
    "dest": "0012025550147",
    "metadata": [
        { "name": "X-TicketID", "value": "12345A" },
        { "name": "X-CustomerPhone", "value": "666555444" }
    ]
}

Hangup example

{   
    "type": "hangup"
}