SupportLoginunifonic.com

Different Voice Parameters that are Available

Suggest Edits

In this section, you will be acquainted with the various parameters that can be used for your voice calls. Combining one or more of them allows you to achieve different use cases - Text-to-Speech, One-Time Password, Audio Notifications, IVR, Number Masking etc.

ParameterTypeDescription/Example
say
- either “say” or “play” is compulsory at a time		stringThe text content that will be translated into a voice audio file by the Unifonic Text-To-Speech Service and played to the recipient on the call.

{
"say":"Hello World",
"language":"english"
"voice":"male",
"ttsEngine":"standard|neural" //optional, default is standard.
}

For more information on text-to-speech engines and its support languages, read this guide.
play
- either “say” or “play” is compulsory at a time
language		stringThe audioId that references the approved audio file in the audio library. The audio library is found within the Unifonic Console Campaign Module.
voice
- compulsory if used with “say” or “onEmptyResponse” parameter		string

enum:
- male
- female		The voice of the audio that will be generated by Unifonic TTS engine.

Unifonic TTS engine currently support male/female voices for all languages.
Language
- compulsory if used with “say” or “onEmptyResponse” parameter		string

Supported languages:
- arabic
- english		The language that will be used by Unifonic TTS engine to convert the text into audio.

Provided language should be similar to the language of the provided text.
Loop
[Optional]		stringThe number of times a message is played if a response is not inputted.
ResponseUrl
[Optional]
- compulsory if expecting recipient's speech/DTMF response		stringThe API where the DTMF/Speech response from the recipient will be posted to. This should be a publicly accessible https endpoint as the recipient may respond verbally or via DTMF, either the digits field or speechResult field sent to the responseUrl may return as ‘null”.

Sample request payload to be posted at this API:
{
“confidence”:0.6, //refers to accuracy of this speech recognition activity
“speechResult”:”one”,
“digits”: “1”,
“recipient”: “+966XXXXXXXXX”,
“callerId”: “+966XXXXXXXXX”
}

ON RESPONSE HANDLING:

Scenario 1: Ending the call after receiving input
For example, after a recipient inputs a DTMF response, you want to say thank you. Simply provide this 200 OK response as part of your API:

{
“say”: “thank you”,
“voice”: “male”,
“language”: “english”
}

Scenario 2: Ask another question
For example, after a recipient inputs a DTMF response, you want to ask a further question. Simply provide this 200 OK response as part of your API:

{
“say”: “are you satisfied with our service? press 1 to say yes. press 2 to say no.”,
“voice”: “male”,
“language”: “english”
“loop”: “3”
“responseUrl: “https://testcustomer.com/question2response
}

// the response of this 2nd question will be posted to the corresponding responseUrl instead

/// if no response or invalid response is provided after posting the DTMF response, our server will automatically say this in the call: “Sorry. An Error Occurred” before hanging up.
onEmptyResponse
[Optional]		stringThe text content that will be translated into a voice audio file by the Unifonic Text-to-Speech Service, and played to the recipient in the event that no DTMF responses were detected.

If onEmptyResponse is missing and no DTMF response were detected, Unifonic will hang up the call after 4 seconds of the last played message.

If onEmptyResponse is initialised in your request, do make sure to define "language" and "voice" params as this will be a text-to-speech operation.
digitsLimit
[Optional]		stringLimits the amount of digits that will be captured by the system. For example, if the digitLimits is set to 1, only the first digit that is inputted by the recipient will be captured.

e.g.:
{
“play”: “XXXXXXXXX”,
“responseUrl” :https://testcustomer.com/question,
“digitsLimit”: “1”
}
transfer
[Optional]		stringThe E164 callerId digits that you will like to transfer the call to.
For example, if the recipient were to select to speak to a customer service agent, the call can be transferred to the number of the customer service agent/call centre.

The transfer parameter can be paired with a say or play parameter, which will allow you to inform the recipient that the call will be transferred. Otherwise, to inform the recipient that the call may be recorded for quality assessment purposes.

The transferred call may or may not be recorded, based on your settings, and the recording will be found in the voice call logs on the Unifonic Console.

e.g.:

{
“language”: “english”,
“voice”: “male”,
“say”: “Your call will now be transferred to our customer service agent.”,
"recording":true,
“transfer”: “+966XXXXXXXXX”,
}
queueName
[Optional]		stringThis parameter can be initialised when adding an active call to the queue. If an existing queue with the queueName is found, calls will be added to that queue. If no existing queue is found with the initialised queueName, a new queue will be created and the call will be added to that queue.

e.g.:
{
“language”: “english”,
“voice”: “female”,
“say”: “Our agents are currently busy. Please wait and we will attend to you shortly.
“queueName”:”service_support”
}
speechCollectionLanguage [optional]stringThis parameter can be initialised when the response collection activity should be conducted via speech recognition. This parameter defines the speech collection language, which enables the system to accurately recognise the language that was spoken by the end user.

After the speech collection activity has concluded and the system was able to recognise what was verbally collected. The system will send the response to the responseUrl in the following format:

Sample request payload to be posted at the responseUrl:
{
“confidence”:0.6, //refers to accuracy of this speech recognition activity
“speechResult”:”one”,
“digits”: null,
“recipient”: “+966XXXXXXXXX”,
“callerId”: “+966XXXXXXXXX”
}
expiry [optional]stringPre-determine the expiry time of each request. Requests that are not processed by the voice gateway by this expiry time will be moved to "failed" automatically.

e.g.:
{
“language”: “english”,
“voice”: “female”,
“say”: “Our agents are currently busy. Please wait and we will attend to you shortly.",
“expiry”:”“2024-01-30T13:49:51.141Z””
}
referenceId [optional]stringSpecify a referenceId for this particular call request so that you can correlate this call request to a transaction on your system.

e.g.
{
“language”: “english”,
“voice”: “female”,
“say”: “Hello user, your order will be delivered to you today at your specified delivery address.",
"referenceId":"transaction-123"
}
pausestringYou can add a pause value in your IVR object to introduce a short pausal for your text to speech operation under the "say" verb. The pause verb only make sense if you are using the multiple say feature.

e.g.
{
"say": "Press, one, or, say, one, for, I strongly agree",
"voice": "male",
"language": "english",
"pause": "1"
}
messagearrayYou can determine a message array in your IVR object in order to create a multiple say or play within a IVR object.

e.g.
{
"recipient":["+971506939568"],
"callerId" : "KSA",
"secondaryCallerID":"KSA",
"type":"ivr",
"ivr":{
"message": [
{
"say": "Press, one, or, say, one, for, I strongly agree",
"voice": "male",
"language": "english",
"pause": "1"
},
{
"say": "Press, two, or, say, two, for, no opinion",
"voice": "male",
"language": "english",
"pause": "1"
},
{
"say": "Press, three, or, say, three, for, I disagree",
"voice": "male",
"language": "english",
"pause": "3"
}
],
"messageLoop": "2",
"responseUrl":"https://myresponseurl.com/1"
}
}
messageLoopstringYou can loop a message object by specifying a messageLoop value.

e.g.
{
"recipient":["+971506939568"],
"callerId" : "KSA",
"secondaryCallerID":"KSA",
"type":"ivr",
"ivr":{
"message": [
{
"say": "Press, one, or, say, one, for, I strongly agree",
"voice": "male",
"language": "english",
"pause": "1"
},
{
"say": "Press, two, or, say, two, for, no opinion",
"voice": "male",
"language": "english",
"pause": "1"
},
{
"say": "Press, three, or, say, three, for, I disagree",
"voice": "male",
"language": "english",
"pause": "3"
}
],
"messageLoop": "2",
"responseUrl":"https://myresponseurl.com/1"
}
}
conference [optional]booleanDefine a list of recipients to receive a call and to be added into the same conference room. In return, you will receive a conferenceId which can be used to add more participants.

e.g.:
{
“language”: “english”,
“voice”: “female”,
“say”: “Good morning. You will now be redirected into the conference room.",
“conference”: true
}

sample api response:
{
"status": "Request has been sent.",
"callId": "6260cc16-6732-455b-a61a-75db85603a38",
"conferenceId": "f096caba-a812-4a2c-afb4-8894758e19ef"
}
conferenceId [optional]stringThe conferenceId can be used to add more participants into a conference.

e.g.:
{
“language”: “english”,
“voice”: “female”,
“say”: “Good morning. You will now be redirected into the conference room.",
“conferenceId”:"f096caba-a812-4a2c-afb4-8894758e19ef"
}

Updated 2 months ago