Voice API

The Voice API allows you to interact with a phone via beautiful HTTP endpoints.

Warning

• There is a minimum amount of credits which you need to have in order to make a Voice API call, regardless of the cost of the call itself. Please refer to the Help Center for more information.

Tip

You can see how this API works on the web at hello.xoxzo.com

Simple Playback API

To make a call and playback an audio file when your recipient answers the phone, make a POST request to the endpoint:

https://api.xoxzo.com/voice/simple/playbacks/

with the following parameters:

Name	Description	Required	Data Type	Example
caller	Caller number	Yes	Numeric	+8190123456789
recipient	Call recipient	Yes	E.164	+8190123456789
recording_url	URL where your mp3 audio file is located	Yes	URL	http://www.mysite.com/123.mp3
callbackurl	Callback URL	No	URL	http://example.com
tags	Tags	No	UTF-8	tag1,tag2

Note

Notes on the recipient parameter:

• Xoxzo uses the E.164 number format when specifying phone numbers.

• E.164 dictates that phone numbers must start with the + prefix and country code then followed directly by the mobile number leaving the local 0 prefix.

• Example of a valid recipient is: +818011234567 with 81 as the Japan country code and 8011234567 as the mobile number.

Note

Notes on the caller parameter:

• Xoxzo uses the E.164 number format when specifying phone numbers.

• E.164 dictates that phone numbers must start with the + prefix and country code then followed directly by the mobile number leaving the local 0 prefix.

Warning

• The caller is sent as through a best effort method and is not guaranteed to be shown on the recipient’s mobile as it is and maybe replaced with an arbitary caller. This is dependent on the policies of the carriers, intermerdiary networks and governments, and they may not honour your request.

Note

Notes on the recording_url parameter:

• The mp3 file specified by the URL MUST be publicly accessible.

• The URL can ONLY contain ascii letters or digits, underscores, slash or hyphens.

• https is not supported at this moment.

Note

Samples of valid URL for recording_url are as below:

• http://example.com/sample-sound.mp3

Note

Notes on the callbackurl parameter:

• When this optional parameter is provided, XOXZO cloud will call this URL when the call ended.

• XOXZO cloud will call the URL with http POST method. Parameters of the callback is similar to “Checking Call Status API”. Please see Checking Call Status.

• Callback URL must return http status 200. Until then, we will retry up to a maximum of ten times.

Note

Notes on the tags parameter:

• When this optional parameter is provided, you can put tags for each API calls and you can retrieve the tags using the check call status API later.

• You can put multiple tags separated by the comma. The leading and trailing spaces are removed from the tags.

JP specific optional parameters

The additional parameters below are for JP specific usage and recipients:

Name	Description	Required	Data Type	Example
jp_din_caller	Local caller ID	No	The string true	true

Please refer to our JP Local Caller ID service for more information.

Note

Notes on the jp_din_caller parameter:

• You are required to subscribe to a Dial In Number in order to use the local caller ID functionality. Please refer to Subscribing to a Dial In Number via API for more information.

Examples

Below is an example request using cURL:

curl -u <SID>:<AUTH_TOKEN> \
  --data-urlencode 'caller=<caller>' \
  --data-urlencode 'recipient=<recipient>' \
  --data-urlencode 'recording_url=<recording_url>' \
  https://api.xoxzo.com/voice/simple/playbacks/

Response

The response would be a JSON structure, returned with HTTP 201 CREATED status code:

HTTP/1.0 201 CREATED
Content-Type: application/json

[
    {
        "callid": "<callid>"
    }
]

If there’s invalid parameters given, HTTP 400 BAD REQUEST status code will be returned. For example, if the caller parameter is missing, the HTTP response should be like this:

HTTP/1.0 400 BAD REQUEST
Content-Type: application/json

{
    "caller": [
        "This field is required."
    ]
}

Response Data

Name	Description
callid	The unique call id for this call

Tip

It’s faster to actually try some test code againts the API to see immediate results. Signing up takes only a few minutes and it’s free

Using Text To Speech with Simple Playback API

OPTIONAL: For an additional cost, you can use text to speech option instead of pre-recorded mp3 file when making calls using the Simple Playback API. To use this option please refer to Text To Speech

Checking Call Status

To check call status, make a GET request to the endpoint followed by <callid>. An example of using curl is below:

curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/voice/calls/<callid>/

Every time you make a call, you will get a response containing <callid>. Use this <callid> to check call status.

The response would be a JSON structure, returned with HTTP 200 OK status code:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "callid": "<callid>",
    "recipient": "<recipient>",
    "url": "https://api.xoxzo.com/voice/calls/<callid>/",
    "tags": [
        "tag2",
        "tag3"
    ],
    "end_time": "2019-03-05 01:38:50",
    "direction": "outbound",
    "cost": 1,
    "status": "NO ANSWER",
    "duration": 0,
    "call_type": "simple/playbacks",
    "start_time": "2019-03-05 01:38:10",
    "caller": "<caller>"
}

Response data

Name	Description
callid	The unique call id for this call
cost	The cost in credits for this call
duration	The duration of the call
start_time	The time when the call was made (in UTC)
end_time	The time when the call ended (in UTC)
caller	The caller number
recipient	The recipient number
status	The status of this call
url	The URL of this call status
tags	The tags assigned to this call. If no tags are assigned, empty list [] will be set.
direction	The direction of this call
call_type	The call type of this call

Common call statuses

This is a list of statuses that you can find in the status data:

Call status	Description
ANSWERED	The call was answered by the recipient, or was passed to a mailbox
FAILED	The call failed to connect to the recipient
IN PROGRESS	The call is still in progress
NO ANSWER	The call was not answered by the recipient

Simple Conference API

The Conference API when executed, will make a call to each of your participants and connect them automatically to a conference call when they answer the call. You can then simultaneously have a conversation with multiple people at once on the phone.

To start a conference call, you can use the following API. make a POST request to the endpoint:

https://api.xoxzo.com/voice/simple/conferences/

with the following parameters:

Name	Description	Required	Data Type	Example
caller	Caller number	Yes	Numeric	+8190123456789
participants	Conference participants	Yes	E.164	+8190123456789,+8190123456780
lang	Language of guidance	No	ISO 639-1	en

Note

Notes on the participants parameter:

• Xoxzo uses the E.164 number format when specifying phone numbers.

• You need a minimum of 2 participants and up to a maximum of 3 participants, separated with a comma (,)

• E.164 dictates that phone numbers must start with the + prefix and country code then followed directly by the mobile number leaving the local 0 prefix.

• Example of a valid participants is: +818011234567 with 81 as the Japan country code and 8011234567 as the mobile number.

Note

Notes on the lang parameter:

• You can specify the guidance language of the beginning of the conference call with this this parameter.

• Two letter language code of the guidance in ISO 639-1.

• This parameter is optional. The default value is ja.

• Currently, en and ja are accepted.

Note

Notes on the caller parameter:

• Please see caller parameter

Response

The response would be a JSON structure, returned with HTTP 201 CREATED status code:

HTTP/1.0 201 CREATED
Content-Type: application/json

{
   "conferenceid": "<conferenceid>",
   "participants": [
       {
           "callid": "<callid1>",
           "participant": "<participant1>"
       },
       {
           "callid": "<callid2>",
           "participant": "<participant2>"
       }
   ]
}

Response Data

Name	Description
conferenceid	The unique conference id for this conference
participants	A list about each participant’s call
callid	The unique call id for the participant
participant	The participant number that was called

Checking Conference Status

To check conference status, make a GET request to the endpoint followed by <conferenceid>. An example of using curl is below:

curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/voice/simple/conferences/<conferenceid>/

Every time you make a canference, you will get a response containing <conferenceid>. Use this <conferenceid> to check call status.

The response would be a JSON structure, returned with HTTP 200 OK status code:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "cost": 65,
    "participants": [
        {
            "status": "ANSWERED",
            "recipient": "<recipent1>",
            "cost": 50,
            "caller": "<caller>",
            "callid": "<callid1>",
            "start_time": "2017-10-31 01:17:50",
            "url": "https://api.xoxzo.com/voice/calls/<callid1>/",
            "end_time": "2017-10-31 01:18:00",
            "duration": 1
        },
        {
            "status": "ANSWERED",
            "recipient": "<recipent2>",
            "cost": 15,
            "caller": "<caller>",
            "callid": "<callid2>",
            "start_time": "2017-10-31 01:17:50",
            "url": "https://api.xoxzo.com/voice/calls/<callid2>/",
            "end_time": "2017-10-31 01:18:09",
            "duration": 2
        }
    ],
    "conferenceid": "<conferenceid>",
    "start_time": "2017-10-31 01:17:50",
    "end_time": "2017-10-31 01:18:09",
    "duration": 2
}

Please see Response data for details.