Documentation for developers

Welcome to PhoneMyBot

If you have developed your own chatbot, PhoneMyBot gives you and your customers the ability to call in using their telephone and engage in a conversation with your chatbot using their voice.

PhoneMyBot transcribes what they say and sends it as text to your chatbot, then takes the text in your chatbot’s response and reads it back to your customers.

PhoneMyBot doesn't decide what to say to your customer, or when to end a call. Your chatbot does. You control PhoneMyBot from your platform through its API.

Getting Started

To integrate your bot with PhoneMyBot you need first to get familiar with the management of PhoneMyBot service and make sure that PhoneMyBot is configured according to your needs.

  • When you register to PhoneMyBot you will use a normal browser to access the dashboard and:
Service subscription

You can subscribe to a new PhoneMyBot service instance from your dashboard on the PhoneMyBot portal, simply by clicking on 'New Subscription'.

new subscription

When you subscribe, the portal will ask you to choose a language. This will be the language PhoneMyBot will use to transcribe the voice of your customer and read your text.

Don't worry if you select the wrong language. You can change the language at anytime from the configuration page.

PhoneMyBot offers you the possibility to create multiple service instances, since you may need to serve customer speaking in different languages and create different call services for different topics.

You are welcome to add all the service instances that you need.

Service configuration

Once the service is created you can change the relevant parameters. In particular you can configure:

  • the language to be used in the conversation
  • the phone numbers you want to add to the service (selecting the country code)
  • the URL where your bot will receive the messages (see service API details).
Service monitoring

You can monitor your PhoneMyBot services through the portal. You can monitor:

  • service changes (e.g. service creation, reconfiguration, etc.)
  • the actual use of the phone lines and relevant resources in any time period.
  • the cost of the service.

API Endpoints

PhoneMyBot talks with chatbot platforms via its messaging interface, a REST API optimized to deliver to the customer, via phone line, the text messages produced by the chatbot and send back, in text format, what the customers say on the phone.

All the messages are of course linked to a session, and the session corresponds to a specific phone call.

PhoneMyBot supports multiple simultaneous calls on separate sessions.

You configure the API parameters using the service configuration facilities of the PhoneMyBot portal.

You select the "edit" bot configuration option in the subscription page:

edit bot configuration

The bot cofiguration window opens. You will see the parameters "bot URL" and "security token" set as required to test the service with the test chat.

When you are ready to test with your own bot, change these parameters to your own "bot URL" and "security token".

bot configuration window

You can reset the service to its initial configuration, and go back to using the PhoneMyBot test chat, clicking on "reset demo mode" in the subscription page.

Messaging interface

The messaging interface of PhoneMyBot is symmetrical, as the same method is used by PhoneMyBot to send messages to the bot and viceversa.

Read the Management Link

POST/cloudengine/rest/voicebot/send/{conversation}

Send 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

Name type description
from string caller number or ID.
to string called number or ID.
body string the body of the message
conversation string conversation (i.e. session) unique identifier (should match the ‘conversation’ field used for the endpoint).
opaque string user-provided identifier. This is provided to PhoneMyBot with the first message and and is provided in the following messages related with the same conversation.
new string identifies the first message in a conversation.
last string identifies the last message in a conversation.
Response:
                          		
                                  {
                                       "success":true,
                                          "reason":"delivered"
                                  }
                              
                        	
                                  
                                      {
                                           "success":false,
                                              "reason":"authorization fail"
                                      }
or 
                                  
                                      {
                                           "success":false,
                                              "reason":"missing authorization header"
                                      }
or 
                                  
                                      {
                                           "success":false,
                                              "reason":"wrong auhorization header format"
                                      }
                                  
                              
                                  
                                      {
                                           "success":false,
                                              "reason":"conversation not found"
                                      }
or 
                                  
                                      {
                                           "success":false,
                                              "reason":"rejected"
                                      }
                                  
                              
                                    
                                        {
                                             "success":false,
                                                "reason":"start not allowed"
                                        }

Notes:

  • The value of the field ‘new’ in the body is ‘true’ only for the first message in a conversation. Since the conversation typically is initiated by the customer calling the phone line, PhoneMyBot is the entity setting this value to ‘true’. The value of the ‘new’ field should be ‘false’ in all the following messages.
  • The value of ‘conversation’ is provided by PhoneMyBot with the first message.
  • The use of the field ‘opaque’ in the body, is optional. and allows the user (handling the chatbot) to send information with the message that will be sent back ‘as is’ by PhoneMyBot with the next message for the same conversation. PhoneMyBot is not processing the value of ‘opaque’. The use of ‘opaque’ is provided as an additional way for the user to keep control of the session.
  • Both PhoneMyBot and the chatbot can set the value of ‘last’ to ‘true’ to terminate the conversation.
  • Any message sent to PhoneMyBot that refers to a conversation that has been closed or never existed is discarded with the response ‘conversation not found’.

Security

For the POST request being accepted by the receiving party (PhoneMyBot or chatbot), it should be sent using basic authentication.

Basic authentication requires the 'Authorization' element being set in the HTTP header with the value 'Authentication token' set as expected from the other party.

The 'Authentication token' required by PhoneMyBot to accept the messages is provided by the PhoneMyBot portal after the service is configured

The 'Authentication token' expected by your chatbot is one of the configuration parameters to be set in the PhoneMyBot portal to configure your service.

Note that a new 'Authentication token' is issued each time the service is reconfigured.

Testing

PhoneMyBot comes with a simple testing environment that you can use to test its capabilities with no chatbot integration.

A chat window is provided in the PhoneMyBot portal for you to impersonate the chatbot.

You can impersonate also the customer, calling the phone number assigned to the service.

PhoneMyBot provides the transcription of what you say at the phone in the chat window and synthetizes in voice on the phone line what you write in the chat window.

This way, you can have a conversation between the chat window and the phone line, emulating the conversation between the customer and the chatbot.

To start the test just select your subscription page in PhoneMyBot portal and click on the 'TEST' button. You will be provided with a 4-digits PIN. Dial the phone number associated with the same service subscription subscription and enter the PIN when prompted. That’s it: you’re using PhoneMyBot.