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.

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

Place Order

This API call is used to enter an order, the 3 JSON Objects arrays described below must be passed into it.

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

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.

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):

2. Set the sex of the voice over talent

3. Choose the type of voice

4. Set a voice

The corresponding voice parameter must be entered for each script parameter used:

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.

6. Set a music

Parameter for choosing the background music for the audio message. The choice of a backing track is optional.

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.

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

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.

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

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