Overview

What is dial in number?

The Dial in number (hereinafter referred to as DIN) is a function to control incoming calls using XOXZO's Telephony API. The user subscribes a telephone number, and if there is an incoming call to that number, you can transfer the call or playback a message using the XOXZO DIN API.

Roughly the flow are as follows.

1. Search for an available DIN.
2. Choose the phone number you like and subscribe to it.
3. Create an action server.
4. Set the action server URL.

Behavior of the action server when receiving an incoming call

When an incoming call arrives at the subscribed phone number, XOXZO cloud system issues an HTTP request to the action URL of the web server (hereinafter referred to as action server) specified by the API. Users using DIN must install an action server to respond to HTTP requests from the XOXZO cloud.

The action instructs the XOXZO cloud system how to handle the incoming phone, and there are three types of action you can specify:

    

playback     

Play specified MP3 file     

transfer     

Transfer to the specified phone number     

say     

Read out a specified text

So let me explain how to build the DIN system in order.

Search for a free phone number

The phone numbers available for DIN are pooled in XOXZO cloud system and users can select their favorite phone number. To obtain a list of available phone numbers, use the following API.

DIN Search API

The returned list include din_uid, a unique identifier of DIN. This din_uid is used as an important parameter in the following API, so let's keep that in mind.

Subscribe the incoming phone number

When you decide the phone number you want to use, you can subscribe that DIN with the following API.

DIN subscribing API

Please specify the din_uid in the URL.

If the subscription is successful, use the following API

DIN list subscription API

to check if your subscription is all right.

Create an action server

When a DIN receives a call, XOXZO cloud will send a HTTP GET request to a callback URL you specify with two parameters. By using these parameters, you can know which DIN was called and what number called the DIN. You can then dynamically control your action according to these parameters.

    

caller     

Phone caller ID     

recipient     

Phone number of incoming DIN

The action server should return action in one line plain text. For details of the action, please see here

You can find a sample action server created with Django web framework here.

Setting action URL

Once the installation of the action server is completed, it is necessary to tell the action server URL to XOXZO cloud so that it knows where to send the callback GET request above.

We use the following API to do this:

Action URL Setting API

Cancel phone number

Once you're finished with a particular DIN, you can cancel the subscribtion with the following API.

DIN cancellation API

Libraries for each language

Fou your convenience, Python, Ruby, PHP libraries are available for using the XOXZO API. These are open source of MIT license. You can use these freely.

• Python
• Ruby
• PHP

Troubleshoot

When things don't work as expected, check the following points:

• Is the action URL set?
• Is the action URL correctly pointing to the action server?
• Is the action server accessible from XOXZO cloud?
• Is the mp3 sound file accessible from XOXZO cloud?
• Are there no mistakes in the response action text? Is the spelling of the command, the number of arguments, and the contents of the argument correct?
• Are there enough credit?