API Docs

Streamlining Communication with Voitex API Integration

Voitex's host of APIs facilitates smooth data exchange, improving communication processes, operational efficiency, and user experience.

IN THIS ARTICLE:


API Branch


Client-Side APIs

API Branch


Overview

Use this feature to get and return certain information during a phone call by enter your API endpoint in the IVR Branch with the function ‘Trigger.' See below for the request you will receive, and the response we expect.


Request Parameters

The request body contains the following parameters:

Parameter Description
call_id A unique ID for this specific call. Any API requests made during this call will have the same unique ID.
cid The number the caller is calling from.
cnam The caller's caller ID name.
contact_info If this caller’s phone number is registered in your contacts, any details associated with the specified contact will be included here.
date_time Current date and time.
did The hotline number the caller called.
branch_data

an array detailing each branch the caller navigated through during the phone call, along with the inputs pressed at each step.

  • This data can be reset in the middle of a call by sending the caller to a branch with the function ‘Content’ and setting the dropdown to ‘Clear Data’.)
payment_info An array of payment information, including the amount and last four digits of the credit card, if the caller made a payment during the phone call.
variables An array of variables set during the phone call, including those set in 'Trigger' or 'Contact Data' branches.

Response Parameters

The following parameters may or may not be included in the response.

Parameter Description
goto

Specifies the branch to navigate to next. If left unspecified, the system will default to the 'No Route Found' setting of the current 'Trigger' branch.

  • This parameter is only relevant if 'play' and 'inputs' parameters are not provided.
play An array of audio files and/or text-to-speech (TTS) recordings to be played before advancing to the specified 'goto' option.
inputs

An array of inputs that callers can select from while the ‘play’ parameter recordings are playing, along with respective branch numbers to go to if the caller selects a specific option.

  • An input of ‘%’ will send the caller to the corresponding goto branch regardless of the input they enter.
variables

An array of variables along with their corresponding values that can be utilized later in the call.

  • For instance, an album number might be utilized in an 'Album Collection' branch to specify the album to play.

Request Code Sample

{
   "call_id":"AST10-1689867312.264",
   "cid":"8459511000",
   "cnam":"VOITEX",
   "contact_info":"null",
   "date_time":"2023-07-20 11:35:35",
   "did":"8459511110",
   "branch_data":[
      {"branch":"0","input":"1"},
      {"branch":"1000","input":"17"}
   ],
   "payment_info":[{
      "last_four":"4444",
      "expiration":"0126",
      "cvv":987,
      "zip":"10950",
      "phone":"8451239876",
      "amount":"57",
      "transaction_id":"875891"
   }],
   "variables":[{
      "caller_pin ":"123",
      "var_2":"var_val"
   }]
}

Response Code Sample

{ 
   "goto":"150", 
   "play":[ 
      { 
         "type":"file", 
         "album":"10", 
         "sort":"25" 
      }, 
      { 
         "type":"tts", 
         "text":"This is a reply TTS recording from the API.", 
      } 
   ], 
   "inputs":{ 
      "1":"3", 
      "4":"2", 
      "6":"105", 
   }, 
   "variables":{ 
      "album_num":"13", 
      "var_2":"var_val" 
   } 
}

Client-Side APIs

With our versatile API functionalities, seamlessly interact with our system and optimize your workflow. From uploading recordings and generating TTS files to triggering notification calls and sending SMS messages, our APIs empower you to automate processes, enhance communication, and streamline operations effortlessly.


Authentication

To use this API, you need an auth_key, which we provide once the account is opened. You

need to include the auth_key in the headers of every request, as shown below:

headers: {
       "auth_key": "your_auth_key"
}

Explore our range of API options below:


Upload Recording API


Overview

This API enables you to upload recordings to specific albums, organizing them into different categories.


Authentication

See detail above.


Endpoint

POST https://api.voitex.com/recordings/upload/index.php


Request Parameters

The request body could include the following parameters:

Parameter Description Required
album_number

The album number to which the recording should be added to.

  • To view the list of albums and their numbers, visit the user portal.
Yes
sort_number

The unique number ID assigned to this recording.

  • This ID enables callers to select a specific recording within a particular category when accessing recordings over the phone. By entering the associated number ID, callers can listen to their desired recording.
 Yes
upload_file The actual file (in wav or mp3 formats) that contains the recording. Yes
display_name The name used to label the recording on the portal for easy identification and management of the recording. No

Response Parameters

The Voitex API will return a JSON object with the following fields:

Parameter Description
status

The status of the request, as follows:

  • "success" if the request was successful.
  • "error" if there was an error.
data The backend recording ID that we assigned to the recording.
errors

An array of error messages, if applicable.

  • This parameter will be empty if the request was successful, or contain one or more error messages if there was an error.

Request Code Sample

POST https://api.voitex.com/recordings/upload/index.php

headers: {
      "auth_key": "1234567890abcdef"
}
form-data: {
     "album_number": 1,
     "upload_file": "example.wav",
     "sort_number": 5,
     "display_name": "Example Recording" 
}

Response Code Sample

{
      "data": "918357",
      "status": "success",
      "errors": [] 

}

Create TTS


Overview

This API allows you to create TTS (Text-To-Speech) recordings and save them in a Library album.


Authentication

See detail above.


Endpoint

POST https://api.voitex.com/v1/recordings/upload/


Request Parameters

The request body could include the following parameters:

Parameter Description Required
album_number

The album number to which the recording should be added to.

  • To view the list of albums and their numbers, visit the user portal.
Yes
text The text that needs to be converted to audio. Yes
sort_number

The unique number ID (sort number) assigned to this recording.

  • If not specified, the next sort number available will be assigned automatically.
 No
type Currently 'tts' typs is the only available type. No

Response Parameters

The Voitex API will return a JSON object with the following fields:

Parameter Description
status

The status of the request, as follows:

  • "success" if the request was successful.
  • "error" if there was an error.
data The backend recording ID that we assigned to the recording.
errors

An array of error messages, if applicable.

  • This parameter will be empty if the request was successful, or contain one or more error messages if there was an error.

Request Code Sample

POST https://api.voitex.com/v1/recordings/upload/ 

headers: {
      "auth_key": "1234567890abcdef"
}
form-data: {
     "album_number ": "1",
     "sort_number": "15",
     "type": "tts",
     "text": "This is a test recording created by the TTS API.",
}

Response Code Sample

{
      "status": "success",
      "data": "915863",
      "errors": []  
}

Notification Call


Overview

This API allows you to initiate notification phone calls from your DID number to any designated phone number.


Authentication

See detail above.


Endpoint

POST https://api.voitex.com/v1/call/index.php


Request Parameters

The request body could include the following parameters:

Parameter Description Required
cid The hotline number to send the call from. Yes
to The phone number to send the call to. Yes
type

Set this field to ‘goto’ if you want to direct the call receiver to an IVR branch.

(Coming soon) Type ‘stream’ to stream a single file.

 Yes
route_number

The hotline DID to which to route the call receiver.

  • This field is required when ‘type’ is set to ‘goto.'


 No
branch_number

The branch to route the call receiver to.

  • This field is required when ‘type’ is set to ‘goto.’
 No
sfile_id

The ID of the file to play from your library.

  • This field is required when ‘type’ is set to ‘stream.' (Coming soon)
No

Response Parameters

The Voitex API will return a JSON object with the following fields:

Parameter Description
status

The status of the request, as follows:

  • 'success' if the request was successful.
  • 'error' if there was an error.
reference_id Unique identifier to easily reference this request at a later time.
errors

An array of error messages, if applicable.

  • This parameter will be empty if the request was successful, or contain one or more error messages if there was an error.

Request Code Sample


POST https://api.voitex.com/v1/call/index.php

headers: {
      "auth_key": "1234567890abcdef"
}
form-data: {
     "cid":"8459511000",
     "to": "8455009999",
     "type": "goto",
     "route_number": "8459511000",
     "branch_number ": "8459511000"
  }

Response Code Sample

{
      "status": "success",
      "reference_id": "Sz1gt0IqgVV7HHs",
      "errors": [] 
}

Send SMS


Overview

This API allows you to send text messages from your SMS-enabled DID.


Authentication

See detail above.


Endpoint

POST https://api.voitex.com/v1/sms/send/index.php


Request Parameters

The request body includes the following parameters:

Parameter Description Required
from The DID (phone number) on your account from which to send the SMS. Yes
to The number to send the SMS to. Yes
body The actual message to send. Yes

Response Parameters

The Voitex API will return a JSON object with the following fields:

Parameter Description
status

The status of the request, as follows:

  • 'success' if the request was successful.
  • 'error' if there was an error.
data

The data you sent in the API request, along with the DID type (TN – telephone

number or TF – toll-free) and a referenceID.
errors

An array of error messages, if applicable.

  • This parameter will be empty if the request was successful, or contain one or more error messages if there was an error.

Request Code Sample


POST https://api.voitex.com/v1/sms/send/index.php 

headers: {
      "auth_key": "1234567890abcdef"
}
form-data: {
     "from ": "8459511000 ",
     "to": "8451234567",
     "body": "This is a test message body"
}

Response Code Sample

{
      "status": "success",
      "data": "{
             "to": "8451234567",
             "from ": "8459511000 ",
             "body": "This is a test message body",
             "did_type ": "TN ",
             "from ": "u7T0um "
      }",
      "errors": []
}
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.