¶ Telephony
PhoneMyBot's main operation is to let chatbots manage incoming phone calls. This is automatic once the chatbot is connected with PhoneMyBot, and this likely covers most of the interactions.
But the chatbot may need to take telephony-related actions of its own for certain use cases, and PhoneMyBot allows it to do that.
In this page we explain how a chatbot can transfer calls (for instance to human agents), and dial calls out to telephone numbers.
¶ Call transfer
PhoneMyBot supports transferring calls to human agents or to other phone numbers (for instance a voicemail system, if outside business hours). In order to start the transfer, the chatbot needs to send a command to PhoneMyBot. The command could be included or implied in the text sent during the conversation (in-band) - if the necessary configuration has been done, or as a special API message (out-of-band).
For you API fanatics, let's start with the PhoenMyBot call transfer API.
¶ Out-of-band
To transfer a call to a telephone number, a chatbot can send a message to PhoneMyBot using the PhoneMyBot direct API (please be familiar with the API before attempting to transfer a call in this way). The message should include the prompt to give to the user before transferring the call and the telephone number to transfer to. Here is an example:
{
“body”: “[prompt to speak to the user]”,
“new”: false,
“from”: null
“to”: null
“last”: false,
“opaque”: null,
“conversation”: [the conversation id],
"hints": {
"telephony": {
"action": "transfer",
"info": {
"calling": "[calling number]",
"called": "[called number]"
}
}
}
}
After receiving the message, PhoneMyBot speaks the prompt to the user and then tries to transfer the call to the number in the “called” field. The transfer is unsupervised, meaning that PhoneMyBot loses control of the call once the transfer request is done.
If the transfer succeeds, PhoneMyBot ends the conversation normally with a flag of “last”= true. If it does not, PhoneMyBot also sends the following hints:
If the number was busy,
"hints": {
"telephony": {
"event": "busy"
}
}
If the number did not answer:
"hints": {
"telephony": {
"event": "noanswer"
}
}
These messages are only informational for the chatbot as the call has already ended from the chatbot point of view.
¶ With markup language
The PhoneMyBot Call Action markup language allows chatbots that do not use the direct API to embed commands in the text of the message they are sending to the user. One of them requests PhoneMyBot to transfer the call to a telephone number specified in the command.
Since there is a wiki page dedicated to the markup language, please see there for details.
If the transfer succeeds, PhoneMyBot ends the conversation normally. If it does not, PhoneMyBot will use one of the error codes of the native chatbot API to signal the error (if using an adaptor).,
Another way to receive a failure message from PhoneMyBot if the call transfer fails is to configure the bot to receive an in-band string (a sentence), and specify the sentences to send in various cases.
In your chatbot configuration, enable the flag "Send back call failure reasons to chatbot in-band", then specify the 3 sentences you want your chatbot to look for in this case. The GUI is like this:
Again, these messages are only to inform the chatbot of the failure of the call transfer. At this point, the chatbot has been disconnected from the user.
¶ From chatbot configuration
When you configure your chatbot, you can define what we call Bot actions. These are actions that PhoneMyBot takes, triggered by a text from the chatbot intended to be spoken to the user, but that triggers the action by matching a regular expression. One of the actions is call transfer. This is often a very convenient way to set up a call transfer, since it does not need any coding. It is explained in detailed here.
¶ If the chatbot API allows transfer
Some chatbot platforms have a specific message to transfer the conversation somewhere else. In particular this is the case for IBM Watson. If this is the case, the PhoneMyBot chatbot configuration includes the ability to specify a default telephone number to transfer the call to. The PhoneMyBot adaptor for the particular platform will then be on the lookout for the command to transfer the call, and will send the call to the default number if it sees it.
¶ Handover the call to another chatbot
Similar to call transfers where a call is directed to a human agent or another phone number, PhoneMyBot also supports call handovers to another chatbot. In this case, the call remains entirely within the PhoneMyBot network.
The handover process does not occur directly between chatbots but involves transferring the call from one VoiceBot channel to another that is connected to the desired destination chatbot. PhoneMyBot manages the handover seamlessly, making it transparent to the destination chatbot.
The message for the handover, using the PhoneMyBot direct API will be as follows:
{
“body”: “[prompt to speak to the user]”,
“new”: false,
“from”: null
“to”: null
“last”: false,
“opaque”: null,
“conversation”: [the conversation id],
"hints": {
"voicemessage": false,
"telephony": {
"action": "handover",
"info": {
"referTo": "[phone number of the destination channel]"
}
}
}
}
It's important to note that each VoiceBot channel is always associated with a phone number. This number can be a PSTN number or an internal number if the channel does not need a direct PSTN connection. This is the phone number to be used in the handover message.
¶ Place calls
PhoneMyBot supports placing calls towards a phone number. Typically, chatbots don't start conversations. Especially web-based chatbots must wait for the user to show up and start the conversation with a question. But sometimes it may be useful to contact the user proactively, for example to confirm an appointment or alert the user about an order status. Clearly, in this case being able to initiate a phone call may be beneficial.
PhoneMyBot provides a way to start an outgoing call through its native API. Since there is no provision for outgoing calls in any chatbot platforms API, developers who want to use this feature need to add the API call to their chatbot application.
The call can be placed by the chatbot, or by an external dialing applicatiom, sending a message to PhoneMyBot using the PhoneMyBot standard API (please be familiar with it before attempting to place a call).
It should be noted that the the message url differs a little bit by the url used in the normal messaging dialog, since when the call is placed, the "conversation" ID is not known yet. So the message uri should be as follows (with "init" to the end):
- POST /cloudengine/rest/voicebot/send/init
The body of the message should be like this:
{
“body”: “”,
“new”: true,
“from”: "[calling number]"
“to”: "[called number]"
“last”: false,
“opaque”: ["optional data"],
“conversation”: null,
"hints": {
"telephony": {
"action": "placecall",
"timeoutms":20000,
}
}
}
}
Note that the flag “new” should be set to true to signal that this is a new conversation. The "opaque" can also be used, if needed, as an additional reference to match the messages received by the bot with the call placed by a possibly external dialer. The value of "timeoutms" can be adjusted if needed.
PhoneMyBot will dial the number and sent the bot a message with the call status once it has been established or has failed, as follow:
- If the call is answered and a conversation is established, PhoneMyBot sends to the bot an event message with the following "hints" attribute:
snippet:
"hints": {
"event": "call.connected"
}
This is a clue for the chatbot that the conversation is started and the "conversation" ID provided with this message can be used as a reference for the ongoing conversation.
- If the called number is busy, a message with the flag “last” set to true and the following snippet:
"hints": {
"event": "call.busy"
}
- If the call failed because of no answer, a message with the flag “last” set to true and the following snippet:
"hints": {
"event": "call.noanswer"
}