NAV
cURL

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
N

Default 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 string
Parameter to specify the text to use for the English version of the message.
script_ita string
Parameter to specify the text to use for the Italian version of the message.
script_fre string
Parameter to specify the text to use for the French version of the message.
script_ger string
Parameter to specify the text to use for the German version of the message.
script_spa string
Parameter to specify the text to use for the Spanish version of the message.
script_por string
Parameter to specify the text to use for the Portuguese version of the message.
script_rus string
Parameter to specify the text to use for the Russian version of the message.
script_jap string
Parameter to specify the text to use for the Japanese version of the message.
script_chi string
Parameter to specify the text to use for the Chinese version of the message.
script_ara string
Parameter 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
female

Default 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).
false

Default 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 entered

Parameter 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
4

Default value if the parameter is not set: indifferent
italian use only if the script_ita parameter has been entered

Parameter 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
4

Default value if the parameter is not set: indifferent
french use only if the script_fre parameter has been entered

Parameter 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
4

Default value if the parameter is not set: indifferent
german use only if the script_ger parameter has been entered

Parameter 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
4

Default value if the parameter is not set: indifferent
spanish use only if the script_spa parameter has been entered

Parameter 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
4

Default value if the parameter is not set: indifferent
portuguese use only if the script_por parameter has been entered

Parameter 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
4

Default value if the parameter is not set: indifferent
russian use only if the script_rus parameter has been entered

Parameter 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
4

Default value if the parameter is not set: indifferent
japanese use only if the script_jap parameter has been entered

Parameter 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
4

Default value if the parameter is not set: indifferent
chinese use only if the script_chi parameter has been entered

Parameter 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
4

Default value if the parameter is not set: indifferent
arabic use only if the script_ara parameter has been entered

Parameter 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
4

Default 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 integer
Parameter 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

Second message details

Third message details

Order details

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 to italian

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 to Y:

[
  {
    "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