Telephony Utilities API

Telephony Utilities API is a collection of APIs which are useful when dealing with phones and the internet.

Carrier Lookup

To do a lookup call, make a POST request to the endpoint:

https://api.xoxzo.com/utilities/carrierlookup/

with the following parameters:

Name	Description	Required	Data Type	Example
recipient	The number to lookup	Yes	E.164	+8190123456789

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.

Examples

Below is an example request using cURL:

curl -u <SID>:<AUTH_TOKEN> --data-urlencode 'recipient=<recipient>' https://api.xoxzo.com/utilities/carrierlookup/

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

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

[
    {
        "id": "gyt5rrrrrrrrrrr65rfsr43rrrrujgf4"
        "mcc": "440",
        "mnc": "54",
        "mccmnc": "44054",
        "carrier": "KDDI",
        "country": "JP",
        "recipient": "+8190123456789"
        "cost": 5,
    }
]

If your lookup failed to identify the carrier for your target recipient, your response data will be something like this:

HTTP/1.1 201 Created
Content-Type: application/json

[
   {
      "carrier": null,
      "cost": 5,
      "country": null,
      "id": "SPsxrrrrmdCopjYgynTRXrrrrrrDkrrr",
      "mcc": null,
      "mccmnc": null,
      "mnc": null,
      "recipient": "+8133333333"
   }
]

Response data

Name	Description
id	A unique 32 char id to identify this lookup request
mcc	The country code of the carrier
mnc	The network code of the carrier
mccmnc	The mccmnc code (combination of mcc and mnc) that uniquely identifies this carrier
carrier	The carrier name
country	ISO Alpha-2 code of the home country of this carrier
recipient	The number being queried
cost	The credits deducted for this API call

Note

Notes on the mccmnc data:

• The combination of the MCC and MNC code MCCMNC uniquely identifies a certain network operator (carrier) anywhere in the world.

• Although the operator business name might change due to buyouts or management changes, the MCCMNC code very rarely does.

• There are cases where one business entity or operator brand might have multiple MCCMNC codes assigned to it.

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

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

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

Text To Speech

Text to speech is an optional functionality that can be used together with our voice call API. It is not an API on it’s own.

In order to use Text To Speech, you will need to refer to the documentation for the specific voice API you would like to use. The APIs will have special parameters which you can use to utilize Text To Speech.

Text to Speech with Simple Playback API

Warning

• Additional costs will apply. Please check the pricing page for details.

To make a call and playback an text message 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
tts_message	text to playback	Yes	UTF-8	Hello world!
tts_lang	language of the text	Yes	ISO 639-1	en

Note

Notes on the caller parameter:

• Please refer Simple Playback API

Note

Notes on the recipient parameter:

• Please refer Simple Playback API

Note

Notes on the tts_message parameter:

• UTF-8 text used for speech synthesis.

• Maximum length is 250 characters.

• You can not specify recording_url parameter with this parameter.

Note

Notes on the tts_lang parameter:

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

• This parameter must exist when tts_message is used.

Supported languages:

Language code	Language
ja	Japanese
en	English

Examples

Below is an example request using cURL:

curl -u <SID>:<AUTH_TOKEN>
     --data-urlencode 'caller=<caller>' \
     --data-urlencode 'recipient=<recipient>' \
     --data-urlencode 'tts_message=おはよう' \
     --data-urlencode　'tts_lang=ja' \
     https://api.xoxzo.com/voice/simple/playbacks/

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

Response data

As for the response , please refer Simple Playback API