Introduction
The TelephoneVox API is a set of HTTP endpoints that adhere to RESTful design principles and CRUD actions. It uses standard HTTP response codes, authentication, and verbs. The API has consistent and well-formed JSON requests and responses with cursor-based pagination to simplify list handling.
Error messages are descriptive and easy to understand.
All major functions of the TelephoneVox customer portal are accessible via the API, enabling you to script complex unattended scenarios with any tool fluent in HTTP.
To better understand the logic of our API, you can help yourself by observing how we organized our order form by clicking here. It should be noted that not all parameters are mandatory, therefore it is possible to integrate a small number of parameters according to one's needs or the time available.
ATTENTION: Respect uppercase and lowercase letters.
Version 7 - June 7, 2022
Requests
Communicate with the API by making an HTTP request at the correct URI, the chosen method determines the action taken.
Method | Usage |
---|---|
POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. |
Parameters
You can pass information to the API in these types of parameters.
Request Body
POST method may include an object in the request body with a content type of application/json.
Endpoint
All requests must be sent to a single Endpoint via POST request. The data must be passed via JSON.
POST https://www.telephonevox.com/api/api.telephonevox.php
Authentication
This part must be integrated with the parameters indicated in the sections below
{
"data_configuration":
{
"user_id" : "your username",
"password" : "your password"
}
}
To authenticate a request, send your user_id
and password
in an array called data_configuration
in every request.
user_id: your username
password: your password
Parameters | Required | Description |
---|---|---|
user_id | Yes | Specify your username, usually your email address. |
password | Yes | Specify your password created when registering on the TelephoneVox.com website. |
Place Order
This API call is used to enter an order, the 3 JSON Objects arrays described below must be passed into it.
Array | Required | Description |
---|---|---|
data_configuration | Yes | It contains generic configuration parameters.Go to the section |
data_order | Yes | It contains the parameters relating to the configuration of the order.Go to the section |
messages | Yes | It contains the parameters relating to the audio messages to be sorted.Go to the section |
Configuration parameters for orders (data_configuration)
This part must be integrated with the Authenticate parameters indicated here
{
"data_configuration":
{
"web_language" : "italian",
"action" : "insert"
}
}
To place an order, you need to integrate the data_configuration
array by entering configuration parameters.
web_language: italian
or web_language: english
or web_language: greek
action: insert
Parameters | Required | Description |
---|---|---|
web_language | Yes | Parameter indicating the language chosen by the user on the site. We need to know this value as we offer some additional choices for English language sites that we cannot offer for Italian sites instead.Value:→ italian → english → greek |
action | Yes | Fixed parameter that indicates the API action to be performed. Indicate the "insert" value to pass the orders, filling in the "Configuration parameters" and the "Messages parameters".Value:→ insert |
Order parameters (data_order)
Example configuration:
{
"data_order":
{
"test" : "N",
"voucher" : "PROMOCODE",
"file_type" : "a"
}
}
The data_order
array must contain the parameters relating to the configuration of the order.
Parameters | Required | Description |
---|---|---|
test | Yes | Parameter to specify if tests are being carried out (Y) and therefore in this case the orders will not be processed, or if the sending is official and therefore in this case the orders will be processed (N).Value:→ Y → NDefault value if the parameter is not set: Y |
voucher | No | Parameter to specify any discount code assigned to you. For this information you can contact the sales manager. (string) |
file_type | Yes | Parameter to specify the type of file to be produced for the requested messages.Value:→ a (Mp3 - .mp3 - 44,1khz - 128kbps)→ b (Alaw - .wav - 8khz - 8 bit)→ c (Ulaw - .wav - 8khz - 8 bit)→ d (Pcm - .wav - 8khz - 16 bit)→ e (Pcm - .wav - 16khz - 16 bit)→ f (Pcm - .wav - 44,1khz - 16 bit)→ other (In case the customer wishes a different formula that we have not foreseen, it will be necessary to use the variable "other" followed by a free string indicating the format, for example: other+.vox_32khz_8bit )Default value if the parameter is not set: a |
Messages parameters (messages)
The messages
array must contain the parameters relating to the technical and artistic specifications of the messages to be ordered. Here's what the array must contain.
1. Set a text script
You have to choose the languages and send the script of the text (at least one of the following parameters must be used):
Parameters | Description |
---|---|
script_eng | stringParameter to specify the text to use for the English version of the message. |
script_ita | stringParameter to specify the text to use for the Italian version of the message. |
script_fre | stringParameter to specify the text to use for the French version of the message. |
script_ger | stringParameter to specify the text to use for the German version of the message. |
script_spa | stringParameter to specify the text to use for the Spanish version of the message. |
script_por | stringParameter to specify the text to use for the Portuguese version of the message. |
script_rus | stringParameter to specify the text to use for the Russian version of the message. |
script_jap | stringParameter to specify the text to use for the Japanese version of the message. |
script_chi | stringParameter to specify the text to use for the Chinese version of the message. |
script_ara | stringParameter to specify the text to use for the Arabic version of the message. |
2. Set the sex of the voice over talent
Parameters | Required | Description |
---|---|---|
sex | Yes | Parameter for choosing the sex of the voice over talent.The sex chosen at this point determines whether the voices in the next points will be male or female.Value:→ male → femaleDefault value if the parameter is not set: female |
3. Choose the type of voice
Parameters | Required | Description |
---|---|---|
is_robot | Yes | Parameter to choose if the voice over talent should be of a human or a robot (TTS). → falseDefault value if the parameter is not set: false |
4. Set a voice
The corresponding voice
parameter must be entered for each script
parameter used:
Parameters | Description |
---|---|
english | use only if the script_eng parameter has been enteredParameter to specify the identification number of the English voice over talent to use (only one). If any voice is suitable for the customer, then use the value "indifferent".Value:→ indifferent → 1 → 2 → 3 → 4Default value if the parameter is not set: indifferent |
italian | use only if the script_ita parameter has been enteredParameter to specify the identification number of the Italian voice over talent to use (only one). If any voice is suitable for the customer, then use the value "indifferent".Value:→ indifferent → 1 → 2 → 3 → 4Default value if the parameter is not set: indifferent |
french | use only if the script_fre parameter has been enteredParameter to specify the identification number of the French voice over talent to use (only one). If any voice is suitable for the customer, then use the value "indifferent".Value:→ indifferent → 1 → 2 → 3 → 4Default value if the parameter is not set: indifferent |
german | use only if the script_ger parameter has been enteredParameter to specify the identification number of the German voice over talent to use (only one). If any voice is suitable for the customer, then use the value "indifferent".Value:→ indifferent → 1 → 2 → 3 → 4Default value if the parameter is not set: indifferent |
spanish | use only if the script_spa parameter has been enteredParameter to specify the identification number of the Spanish voice over talent to use (only one). If any voice is suitable for the customer, then use the value "indifferent".Value:→ indifferent → 1 → 2 → 3 → 4Default value if the parameter is not set: indifferent |
portuguese | use only if the script_por parameter has been enteredParameter to specify the identification number of the Portuguese voice over talent to use (only one). If any voice is suitable for the customer, then use the value "indifferent".Value:→ indifferent → 1 → 2 → 3 → 4Default value if the parameter is not set: indifferent |
russian | use only if the script_rus parameter has been enteredParameter to specify the identification number of the Russian voice over talent to use (only one). If any voice is suitable for the customer, then use the value "indifferent".Value:→ indifferent → 1 → 2 → 3 → 4Default value if the parameter is not set: indifferent |
japanese | use only if the script_jap parameter has been enteredParameter to specify the identification number of the Japanese voice over talent to use (only one). If any voice is suitable for the customer, then use the value "indifferent".Value:→ indifferent → 1 → 2 → 3 → 4Default value if the parameter is not set: indifferent |
chinese | use only if the script_chi parameter has been enteredParameter to specify the identification number of the Chinese voice over talent to use (only one). If any voice is suitable for the customer, then use the value "indifferent".Value:→ indifferent → 1 → 2 → 3 → 4Default value if the parameter is not set: indifferent |
arabic | use only if the script_ara parameter has been enteredParameter to specify the identification number of the Arabic voice over talent to use (only one). If any voice is suitable for the customer, then use the value "indifferent".Value:→ indifferent → 1 → 2 → 3 → 4Default value if the parameter is not set: indifferent |
5. Choose the amount of files to produce/receive
If more than one script
parameter has been set within the same message, you can use this parameter to tell us whether to produce: an audio file for each language or a single audio file containing all the required languages. If more than one script parameter has been set within the same message, you can use this parameter to tell us whether to produce: an audio file for each language or a single audio file containing all the required languages.
Parameters | Required | Description |
---|---|---|
files_quantity | No | Parameter to indicate whether to produce a single file for all languages or one that contains all selected languages.Value:→ single (A single audio file with all required languages will be produced) → multiple (An audio file will be produced for each required language)Default value if the parameter is not set: single |
6. Set a music
Parameter for choosing the background music for the audio message. The choice of a backing track is optional.
Parameters | Required | Description |
---|---|---|
music_specification | No | Parameter for choosing the background music for the message.Value:→ catalog+TrackNumber (Request a backing track from our catalog. Replace TrackNumber with the desired backing track number, found here. Example:catalog+7 ) → title+SongTitle (Request a backing track specifying the title and the author. Replace SongTitle with the name of the track. Example:title+like a prayer madonna ) → web+Link (Request a backing track specifying the link. Replace Link with the link to the specific file or audio/video. Example:web+https://www.domain.com/folder/song.mp3 or web+https://www.youtube.com/79fzeNUqQbQ ). |
music_length | Use only if the music_specification parameter has been entered |
integerParameter to specify how many seconds the backing track must continue beyond the last word pronounced by the voice over talent. For example, if the music is to continue for zero seconds beyond the voice over talent's speech, then value as follows: 0 .Default value if the parameter is not set: 5 |
Example code
curl --location --request POST 'https://www.telephonevox.com/api/api.telephonevox.php' \
--header 'Content-Type: application/json' \
--data '{
"data_configuration":
{
"user_id" : "your username",
"password" : "your password",
"web_language" : "italian",
"action" : "insert"
},
"data_order":
{
"test" : "N",
"voucher" : "XXX",
"file_type" : "a"
},
"messages":
[
{
"script_ita" : "Italian text first message",
"script_eng" : "English text first message",
"sex" : "male",
"is_robot": "false",
"italian_voice" : "indifferent",
"english_voice" : "1",
"files_quantity" : "single",
"music_specification" : "catalog+7",
"music_length" : "10"
},
{
"script_ita" : "Italian text second message",
"sex" : "male",
"is_robot": "false",
"italian_voice" : "3"
}
{
"script_ita" : "Italian text third message",
"sex" : "male",
"is_robot": "true",
"italian_voice" : "1"
}
]
}'
The above command returns JSON structured like this:
[
{
"Result" : "Order placed",
"Order-number" : "4686"
}
]
In this section you will find sample code for a complete API call.
First message details
- Version of the message in Italian with human male voice over talent and indifferent voice
- Version of the message in English with human male voice over talent and voice number 1
- Backing track number 7 from our catalog for both messages
- The base will have to continue for 10 seconds after the voice over talent has spoken
- Production of an audio file for each language
Second message details
- Message in Italian with human male voice over talent and voice number 3
Third message details
- Message in Italian with robot (TTS) male voice over talent and voice number 1
Order details
- Inserting the voucher with code "XXX"
- Required file format: Mp3 - .mp3 - 44,1khz - 128kbps
Get voices list
This API call is used to obtain the voices list, the JSON Object array described below must be passed into it.
Array | Required | Description |
---|---|---|
data_configuration | Yes | It contains generic configuration parameters.Go to the section |
Configuration parameters for voices list (data_configuration)
Example with
web_language
set toitalian
curl --location --request POST 'https://www.telephonevox.com/api/api.telephonevox.php' \
--header 'Content-Type: application/json' \
--data '{
"data_configuration":
{
"user_id" : "your username",
"password" : "your password"
"web_language" : "italian",
"action" : "voices"
}
}'
The above command returns JSON structured like this:
[
{
"Vox" : "1",
"Vox_type" : "Italian female voice",
"Is_Robot" : "false",
"File_mp3" : "http://www.telephonevox.com/voci/1femminilelinguaitaliana.mp3"
},
...
{
"Vox_type" : "English male voice",
"File_mp3" : "http://www.telephonevox.com/voci/INDIFFERENTEmaschilelinguainglese.mp3"
},
...
{
"Vox_type" : "Arabic male voice",
"File_mp3" : "http://www.telephonevox.com/voci/INDIFFERENTEmaschilelinguaarabo.mp3"
}
]
This part must be integrated with the Authenticate parameters indicated here
To obtain the voices list, you need to integrate the data_configuration
array by entering configuration parameters.
web_language: italian
or web_language: english
or web_language: greek
action: voices
Parameters | Required | Description |
---|---|---|
web_language | Yes | Parameter indicating the language chosen by the user on the site. We need to know this value as we offer some additional choices for English language sites that we cannot offer for Italian sites instead.Value:→ italian → english → greek |
action | Yes | Fixed parameter that indicates the API action to be performed. Indicate "voice" value to obtain the voices list.Value:→ voices |
Get backing track list
This API call is used to obtain the backing track list, the JSON Object array described below must be passed into it.
Array | Required | Description |
---|---|---|
data_configuration | Yes | It contains generic configuration parameters.Go to the section |
Configuration parameters for backing track list (data_configuration)
curl --location --request POST 'https://www.telephonevox.com/api/api.telephonevox.php' \
--header 'Content-Type: application/json' \
--data '{
"data_configuration":
{
"user_id" : "your username",
"password" : "your password"
"web_language" : "italian",
"action" : "soundtrack"
}
}'
The above command returns JSON structured like this:
[
{
"Music_background" : "1",
"Title" : "Eine kleine nachtmusik",
"Author" : "Mozart",
"Musical_genre" : "Classical",
"File_mp3" : "http://www.telephonevox.com/basi/1.mp3"
},
...
{
"Music_background" : "23",
"Title" : "Tender Hand 2",
"Author" : "Karel Vagner",
"Musical_genre" : "Modern",
"File_mp3" : "http://www.telephonevox.com/basi/23.mp3"
},
...
{
"Music_background" : "48",
"Title" : "Auld lang syne",
"Musical_genre" : "Christmas",
"File_mp3" : "http://www.telephonevox.com/basi/48.mp3"
}
]
This part must be integrated with the Authenticate parameters indicated here
To obtain the backing track list, you need to integrate the data_configuration
array by entering configuration parameters.
web_language: italian
or web_language: english
action: soundtrack
Parameters | Required | Description |
---|---|---|
web_language | Yes | Parameter indicating the language chosen by the user on the site. We need to know this value as we offer some additional choices for English language sites that we cannot offer for Italian sites instead.Value:→ italian → english |
action | Yes | Fixed parameter that indicates the API action to be performed. Indicate the "soundtrack" value to obtain the backing track list.Value:→ soundtrack |
Errors
Example of an error in the general configuration parameters:
[
{
"Error" : "Please note, you have not entered the “action” parameter"
}
]
Example of error in message parameters:
[
{
"Result" : "Order not placed",
"Order-number" : "n.d.",
"Error" : "Please note, you have not entered the text of the message 1"
}
]
Example of an error in the validation of the order by our system:
[
{
"Result" : "Order not placed",
"Order-number" : "n.d.",
"Error" : "Validation error"
}
]
Example of error when the
test
variable is set toY
:
[
{
"Result" : "Order placed, not validated",
"Order-number" : "n.d.",
"Error" : "Test order"
}
]
In the event of an error, the system that interpreting the API calls will return the cause of the problem. Here are some examples of errors.
Contacts
In case of doubts or questions you can send an email to webmaster@telephonevox.com