{ "componentChunkName": "component---src-templates-doc-page-js", "path": "/docs/en/telephony/script_voice_bot/", "result": {"data":{"site":{"siteMetadata":{"title":"Gatsby-doc-engine"}},"markdownRemark":{"id":"a1e22fbc-0239-555f-8439-2c2193204872","excerpt":"Bot script for a voice broadcast Text-to-speech and speech-to-text functions are used in voice broadcasts.?> Text-to-speech — the text is converted to voice…","html":"

Bot script for a voice broadcast

\n
\n

Text-to-speech and speech-to-text functions are used in voice broadcasts.

\n

Text-to-speech — the text is converted to voice.

\n

Speech-to-text — the sound stream is converted into text.

\n

That aspect of bot script development has certain peculiarities. This article considers the following aspects:

\n\n
\n

Adapting the script for a telephone channel

\n
Recognition
\n

When adapting the bot script for a phone channel, you need to catch and handle the event speechNotRecognized. The event is triggered if a client request could not be recognized within 5 seconds, or if the recognition returned nothing.

\n

For example:

\n\n
    state: speechNotRecognized || noContext = true\n        event: speechNotRecognized\n        a: Please repeat, I can’t hear you.\n        go!: {{$session.lastState}}
\n\n
    state: CatchAll\n        event!: speechNotRecognized\n        q!: *\n        random:\n            a: Could you repeat please?\n            a: I didn’t catch that.\n            a: Please repeat.\n            a: I’m sorry, I couldn’t hear what you said.
\n\n

Please note that pre-paid minutes in your subscriber plan will be spent while the bot is talking to an automated voice message system.

\n

The bot asks the client to repeat the reply or hangs up if it could not recognize the phrase:

\n
    state: NoInput || noContext=true\n        event: speechNotRecognized\n        script:\n            $session.noInputCounter = $session.noInputCounter || 0;\n            $session.noInputCounter++;\n        \n        if: $session.noInputCounter >= 5\n            a: It seems that the line is bad. I will call back later.\n            script:\n                $dialer.hangUp('(The bot has hung up)');\n        else:\n            a: I cannot hear you, please repeat!
\n

Other event for the telephone channel

\n
\n
Call termination by the bot
\n

The bot cannot use the method $dialer.hangUp('(Bot has hung up)') to terminate a call by itself.

\n

The phrase Bot has hung up will be displayed in the non-voice channel that you are using for bot debugging.

\n

For example:

\n
    state: HangUp\n        a: Have a good day. Goodbye.\n        script:\n            $dialer.hangUp('(The bot has hung up)');
\n

The argument for $dialer.hangUp() is optional.

\n

Use event: botHangup to track an event when the conversation has been terminated at the request of the bot.

\n

For example:

\n
  state: BotHangUp\n    event: botHangup\n    script:\n        log(\"Got event botHangup\");
\n
\n
Call termination by the client
\n

Use event: hangup to track the event of call termination by the client.

\n

For example, to determine what state the client was in before the call was terminated:

\n
    state: ClientHungUp\n        event!: hangup\n        script:\n            getClientHangUpReaction($session.lastState);
\n

Here, if the bot terminates the call by itself, the hangup event is not triggered.

\n
\n
Transfer to the operator
\n

You can also transfer the call to an operator:

\n
script:\n    $response.replies = $response.replies || [];\n    $response.replies\n     .push({\n        type:\"switch\",\n        phoneNumber:88008000000,\n    });
\n

More about call transfers to operators

\n
\n
Tone dialing
\n

The bot may request and process the sending of dtmf messages (numbers/characters coded as tones).

\n

A dtmf message request:

\n
script:\n    $response.replies = $response.replies || [];\n    $response.replies.push({\n        type: 'dtmf',\n        max: 4,            //the maximum number of digits expected from the subscriber.\n        timeout: 15000     //the subscriber input timeout, in milliseconds (a number).\n     });
\n

Then a request is caught, for example, with the digits:

\n
state: Digits\n    q: $regexp<\\d+>\n    a: you have dialed {{$parseTree.text}}!
\n

The event noDtmfAnswerEvent is triggered if the subscriber has not input a dtmf message:

\n
    state: noDTMF || noContext = true\n        event: noDtmfAnswerEvent\n        a: You have not selected anything.\n        go!: {{$session.lastState}}
\n

More details about tone dialing

\n
\n
Sessions
\n

More about sessions in the JAICP platform

\n

In voice broadcasts a session starts when the subscriber picks up the receiver or makes a call themselves. Call termination is treated as the session termination.

\n

Here, if you use the same script for other channels, then the session for them will start at the time of the first call by the client when there is no other active session for this client.

\n

We do not recommend artificial session splitting for voice broadcasts using the newSession response.

\n
\n

Using audio files

\n

You can use a pre-recorded file for a reply from a bot. The platform allows you to use audio files in the PCM format with the file extension .wav. PCM settings:

\n\n

Add the tag audio to the bot’s reply and include an audio file with the extension .wav in the link.

\n

For example:

\n
    state: audio\n        audio: https://example.wav   // audio file link (any repository)
\n
\n

Working with a phone number list

\n

Managing telephone number lists

\n

When creating a phone number list for a voice broadcast, you can add additional fields to the list. For example, First name, Last name, City. The table will only be validated by the first column that contains the phone numbers and the remaining fields will be loaded as text.

\n

You can use the data from the additional fields in a broadcast script.

\n

The method $dialer.getPayload() returns a json object with populated phone number list fields.

\n

For example, we are uploading a phone number list:

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
phonenameaddress
79990000000ᅠᅠJohn ᅠᅠ ᅠᅠNew York
\n
\n

Calling the method $dialer.getPayload() will return a json object:

\n
{\n  \"phone\": \"79990000000\",\n  \"name\": \"John\",\n  \"address\": \"New York\"\n}
\n

Script use:

\n
    state: Hello\n        a: Hello!\n        if: $dialer.getPayload().name\n            a: Your name is {{$dialer.getPayload().name}}\n        else:\n            a: I don’t know your name.
\n

If the list has been uploaded with headers, then calling the method $dialer.getPayload() will return a json object:

\n
{0: \"79990000000\", 1: \"John\", 2: \"New York\"}
\n

In this case var name = $dialer.getPayload()[1].

\n

If the column is empty, then calling the $dialer.getPayload().address function will return an empty value.

\n
{\n  \"phone\": \"79990000000\",\n  \"name\": \"John\",\n  \"address\": \"\"\n}
\n
\n

The method $dialer.getCaller() returns a string with the user’s phone number in the format in which the telephone switchboard sends it.

\n

Script use:

\n
    state: Hello\n        a: Hello!\n        a: Your number is {{getCaller()}}.\n        if: $dialer.getPayload().name\n            a: Your name is {{$dialer.getPayload().name}}\n        else:\n            a: I don’t know your name.
\n
\n

Scheduling a call from a script

\n

You may need to schedule a new call during a conversation between a bot and a client. For example, a client may ask you to call later.

\n

Use the $dialer.redial() method to schedule a new call and override the calling policy for this number from your script.

\n

Parameters of this method match those of the CallJobParametersList method in Calls API.

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ParameterExampleDescription
startDateTime2020-03-23T00:00:00ZCall start date. Takes the Date object.

The call will be made
within the [startDateTime, finishDateTime] interval.
finishDateTime2020-03-23T00:00:00ZCall end date. Takes the Date object.

Calls will not be made after finishDateTime.
allowedTime\"mon\": [{\"localTimeFrom\": \"10:00\", \"localTimeTo\": \"11:30\"}]For each day of the week, one or several recommended calling intervals can be specified.

localTimeFrom is the earliest time for a call. The time value is not absolute: customer’s local time will be used for calling.

localTimeTo is the latest time for a call. The time value is not absolute: customer’s local time will be used for calling.
allowedDays[\"sun\"]Weekdays when calling is allowed.
maxAttempts1Callback attempts.
retryIntervalInMinutes120The pause (in minutes) between callback attempts.
gmtZone\"+03:00\"Timezone ID. Should be specified from \"-18:00\" to \"+18:00\" or as the name of zone according to IANA TZBD.
\n
\n

Please note that $dialer.redial() method is not used without specified parameters. To ensure the correct work of the method, it is necessary to set the parameter startDateTime or allowedTime. If the rest of the parameters are not specified, their values will be taken from the voice calling campaign settings.

\n

For example, you configure the following callback parameters:

\n
state:\n    q!: Сall back\n    script:\n        $dialer.redial({\n            allowedTime: {\n                \"mon\": [{\"localTimeFrom\": \"10:00\", \"localTimeTo\": \"11:30\"},\n                        {\"localTimeFrom\": \"13:00\", \"localTimeTo\": \"14:30\"}],\n                \"fri\": [{\"localTimeFrom\": \"12:30\", \"localTimeTo\": \"15:00\"}],\n                \"default\": [{\"localTimeFrom\": \"10:00\", \"localTimeTo\": \"18:00\"}]\n            },\n            retryIntervalInMinutes: 120,\n            maxAttempts: 3\n         })\n    a: ok
\n

For the recommended interval, both the localTimeFrom and localTimeTo bounds must be specified. If one of the boundaries is not specified, then an error is returned.

\n

In this example, the callback will be made on Monday from 10:00 to 11:30 and from 13:00 to 14:30, and on Friday from 12:30 to 15:00. Recommendations for others not explicitly specified days are specified in the allowedTime parameter with the default key.

\n
\n

If the allowedDays parameter is specified, the call can be made only on the day that is explicitly specified.

\n
state:\n    q!: Сall back\n    script:\n        $dialer.redial({\n            allowedDays: [\"sat\", \"sun\"],\n            allowedTime: {\n                \"fri\": [{\"localTimeFrom\": \"12:30\", \"localTimeTo\": \"15:00\"}],\n                \"default\": [{\"localTimeFrom\": \"10:00\", \"localTimeTo\": \"18:00\"}]\n            },\n             retryIntervalInMinutes: 120,\n            maxAttempts: 3\n         })\n    a: ok
\n

In this example, although the interval is explicitly specified for Friday in the allowedTime parameter, the call can only be made on Saturday or Sunday.

\n

Please note that the recommended intervals within one day must be specified without intersections.

\n

Examples of intersections:

\n
\"mon\": [{\"localTimeFrom\": \"10:00\", \"localTimeTo\": \"13:30\"}, \n        {\"localTimeFrom\": \"13:00\", \"localTimeTo\": \"14:30\"}],\n\"tue\": [{\"localTimeFrom\": \"10:00\", \"localTimeTo\": \"18:30\"}, \n         {\"localTimeFrom\": \"13:00\", \"localTimeTo\": \"14:30\"}],
\n
\n

If the localTimeFrom parameter is greater than localTimeTo in the specified interval, then the interval is considered to be correct. It starts on the specified day and ends the next day. The calls in the following example will be made from 8 p.m. Monday to 3 a.m. Tuesday:

\n
\"mon\": [{\"localTimeFrom\": \"20:00\", \"localTimeTo\": \"03:00\"}],
\n
\n

Configure callback parameters based on the client’s reply. Use the $parseTree._Date.timestamp filled slot to define the call start date:

\n
state: Call me back\n        intent!: /Call me back\n        a: Ok, I will call you back!\n        script:\n            $dialer.redial({startDateTime: new Date($parseTree._Date.timestamp)})\n            $dialer.hangUp();
\n
\n

Configure callback settings at the client’s request with additional parameters:

\n
state: \n    q!: call me back in a hour\n\tscript:\n\t   var redialTimeFrom = moment().add(60, \"m\").toDate();\n       var redialTimeTo = moment().add(75, \"m\").toDate();\n\t   $dialer.redial({\n          startDateTime: redialTimeFrom, finishDateTime: redialTimeTo,   // call back in the interval of [now + 1h, now + 1h 15m]\n          localTimeFrom: \"12:00 AM\", localTimeTo: \"12:00 AM\",                  // ignore call time limits based on the customer’s time\n          maxAttempts: 2,                                                // make 2 calling attempts\n          retryIntervalInMinutes: 5                                      // with a 5 minute pause between them\n       })\n\ta: Ok, I will call you back in an hour
\n
\n

You can only schedule one call in a conversation. For example, a client may ask the bot to call later. Calls to $dialer.redial() are ignored for subsequent client replies as callback parameters have already been set.

\n

Please note that $dialer.redial() parameters can be overridden if the bot did not reply. It can be done in postProcess or another state if a go! transition was made without a bot reply.

\n

You can schedule up to 5 callbacks per number for a single voice calling campaign from your script.

\n

Learn more about call priority and calling policy

\n

</br

\n

Tagging the broadcast outcomes

\n

By tagging broadcast outcomes in a script you can add user-defined metrics into the statistics.

\n

More about statistics

\n

The method $dialer.setCallResult allows tagging of the broadcasting outcomes for keeping extended statistics.

\n

For example, let us consider the following script:

\n
        state: Yes\n            q: Yes\n            a: Thank you for your cooperation! Goodbye!\n            script:\n                $dialer.setCallResult(\"YES\");\n                $dialer.hangUp();\n            \n        state: No\n            q: No\n            a: I’m sorry to hear that you’re not interested. Goodbye!\n            script:\n               $dialer.setCallResult(\"NO\");\n               $dialer.hangUp();\n            \n        state: Maybe\n            q: Maybe\n            a: We will call you back later. Talk to you soon!\n            script:\n                $dialer.setCallResult(\"MAYBE\");\n                $dialer.hangUp();
\n

Now the broadcast outcome will be displayed in the table with the metrics when the script reaches the specific state: YES, NO, MAYBE.

\n

If extended metrics are not needed for the script, use methods that tag the outcomes about accepting or declining a proposal while not requiring the name to be filled in.

\n

The methods $dialer.setCallResultAccepted and $dialer.setCallResultRejected make it possible to tag the outcome as ACCEPTED or REJECTED, respectively.

\n

Script:

\n
        state: Yes\n            q: Yes\n            a: Thank you for your cooperation! Goodbye!\n            script:\n                $dialer.setCallResultAccepted();\n                $dialer.hangUp();\n            \n        state: No\n            q: No\n            a: I’m sorry to hear that you’re not interested. Goodbye!\n            script:\n               $dialer.setCallResultRejected();\n               $dialer.hangUp();
\n

In the table with the metrics the outcomes of the broadcast will be displayed as ACCEPTED and REJECTED when specific states are reached.

\n
\n

Extending the broadcast report

\n

The method $dialer.reportData($header, $value, $order) makes it possible to add columns with arbitrary data to a broadcast .xls report.

\n

Method parameters:

\n\n

The script developer may add columns into the report that are needed for a specific broadcast, for example:

\n
    \n
  1. Retrieving data during a call:\n\n
    2. \n
  2. To log the phrase and the completion of a step:\n\n
    3. \n
\n

The $order parameter is optional and takes the default value of 0 if omitted. The columns in the report are arranged in descending order depending on the corresponding $order values, and if it is the same for multiple columns, these will be sorted alphabetically.

\n

Consider the following script:

\n
theme: /\n\n    state:\n        q!: *start\n        a: Hello! What is your name?\n\n        state: Name\n            q: *\n            a: Hello, {{$parseTree.text}}!\n            script:\n                $dialer.reportData(\"Name\", $parseTree.text);\n            a: What do you think about smoking?\n\n            state: Smoking\n                q: *\n                a: Okay, we’ll put it down as: \"{{$parseTree.text}}\".\n                script:\n                    $dialer.reportData(\"Attitude to smoking\", $parseTree.text, 1);
\n
\n

Here the Attitude to smoking column will be the first of the user-defined columns as its $order is 1. The Name column will be placed second, because its $order is omitted and therefore equals 0.

\n

In a more complex case, the columns will be sorted this way in accordance with their $order values:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SexFirst NameLast NamePatronymicAttitude to smoking
1000-1
\n

Please note that the number of columns in the broadcast report is limited. Ask your account administrator for details.

\n

Retrieving call recordings

\n

If the phone channel has its Record calls parameter set to active, you can retrieve links to ongoing calls directly from the script using the $dialer.getCallRecordingPath() method.

\n

The method returns the relative path to the current call recording, such as the following:

\n
242829491/2019-06-18/79313365671/16:56:31.55-1P
\n

The full path conforms to this template:

\n
https://{{host}}/restapi/download/{{projectId}}/recordings/call/{{callRecordingPath}}
\n

Here,

\n","frontmatter":{"title":"","description":null},"headings":[{"value":"Bot script for a voice broadcast"}]}},"pageContext":{"slug":"/docs/en/telephony/script_voice_bot/","previous":{"fields":{"slug":"/docs/en/telephony/sip_providers/"},"frontmatter":{"title":"","description":null}},"next":{"fields":{"slug":"/docs/en/telephony/recognition_synthesis_settings/"},"frontmatter":{"title":"","description":null}}}}, "staticQueryHashes": ["1209419333"]}