PhoneMyBot's messaging API allows the chatbot to control the conversation - receiving an alert if there is an incoming session with transcription of what the user says, replying with answers and managing session events.
The API is symmetrical and includes a single method used both by PhoneMyBot to send messages to the chatbot and by the chatbot to send messages to PhoneMyBot.
This sends a message. The same method is used for both outgoing and incoming messages and is called by the party (PhoneMyBot or chatbot) that is sending the message.
The URL where the method should be posted is defined in the service configuration.
Parameters to be included into the JSON body:
| Name | Type | Description |
|---|---|---|
| from | string | Calling number or ID. |
| to | string | Called number or ID. |
| body | string | The text of the message |
| conversation | string | Session unique identifier. It should match the “conversation” field used for the endpoint. |
| opaque | string | Chatbot-provider identifier. It just goes through PhoeneMyBot and comes back untouched, for private processing. |
| new | boolean | Identifies the first message in a conversation. |
| last | boolean | Identifies the last message in a conversation. It also signals that a call is finished. |
The following is an example of body structure.
{
"body": "hello, how can I help you?",
"from": null,
"to": null,
"new": false,
"last": false,
"opaque": null,
"conversation": "7e8ec4e7-b8ee-4e65-bae9-3b83351672ef"
}
The message HTTP header must include basic authentication as authorization: Basic {security-token}, where the 'security token' is provided by the other end in the set-up of the API configuration.
Possible responses:
{
"success":true,
"reason":"delivered"
}
{
"success":false,
"reason":"authorization fail"
}
{
"success":false,
"reason":"conversation not found"
}
Example:
{
"success":false,
"reason":"start not allowed"
}
The API as described so far is good for a basic conversation, but sometimes PhoneMyBot needs additional input to perform advanced functions. For example, transferring a call or maximizing the understanding performance for the next exchange. So you can add 'hints' to the message. A hints section is as follows:
{
"hints": {
"[main-keyword]": {
"[lower-level-keyword]": "[value]"
}
}
}
Hints can be used for different tasks, both from the chatbot to send a command, and from PhoneMyBot to send information. The hints types may change in time, but for now they are:
The Telephony hint type may be used by the chatbot to send a command related with the ongoing call. For example, the command to transfer a call is as follows:
{
"hints": {
"telephony": {
"action": "transfer",
"info": {
"referTo": "+122444433322",
}
}
}
}
(please see here for how to transfer a call)
If the call transfer fails, PhoneMyBot will reply with a hint of its own, of type Event:
{
"hints": {
"telephony": {
"event": "busy"
}
}
}
The 'context' type is used by the chatbot to provide information to PhoneMyBot about the conversation context, in order to optimize the utterances interpretation by the Speech-to-Text engine.
This may mean for the chatbot to send a list of options that it's expecting, the equivalent of showing a number of buttons to click on a web interface. For this use, the chatbot can choose the name it gives to the context, while the type is "inline". An example is the following, giving a choice from 3 colors:
"hints": {
"context":[
{
"name":"colors",
"type":"inline",
"items":[
{
"key":"green",
"values":[
"green"
]
},
{
"key":"white",
"values": [
"white"
]
},
{
"key":"blue",
"values": [
"blue"
]
}
]
}
]
}
This will cause PhoneMyBot to only consider one of the possible colors as a valid answer from the user. Once this happens, PhoneMyBot will send back to the chatbot the corresponding "key". If the user says something else, i.e. PhoneMyBot does not recognize one of the possible options, it will send back to the chatbot a "no match" error and the chatbot can change the question.
PhoneMyBot also has a number of predefined contexts, that help in the understanding of certain strings - like numbers, codes, etc. Each is specialized for a language and country.
An example is a telephone number in the US (a string of exactly 10 digits):
"hints" {
"context": {
"name": "phonenumber",
"type": "builtin"
}
}
In this case the unique name of the context tells PhoneMyBot what to expect, and it determines the speech-to-text engine to use for the best results in transcribing the utterance.
Please see the list of context names page for details on the built-in contexts.