Built-in functions of DashaScript dialogue design

DashaScript has a number of built-in functions to give you intricate control over the interactions Dasha AI has with your users. The functions are designed in a way to let you create human-like conversational experiences for your users.

The built-in functions are inline and can be called from the executable section (sections do or transitions within a node or a digression). Built-in functions are identified by the # prefix.

Blocking call (synchronous) functions block execution of further operations until the function is resolved. When it is resolved, the function returns the result and code execution continues.

Answer to the user using GPT with current history and ability to call DSL functions

Returns an object with fields:

• interrupted - true, if GPT was interrupted by user
• functionCalled - true, if function was called during or instead of an answer
• completed - true, if GPT has completed answering (and connection to the user was not closed)
• saidPhrase - GPT’s phrase
• calledFunctionNames - name of the function that was called (if none was called returns an empty array)
• thinking - text that shows GPT’s thinking process prior to response generation (only when Thinking is enabled)

Ask GPT to help and form answer to a user around it.

• functionCalled - true, if function was called during or instead of GPT’s response
• completed - must always return true
• responseText - returns GPT’s response for the question
• calledFunctionNames - name of the function that was called (if none was called returns an empty array)
• thinking - text that shows GPT’s thinking process prior to response generation

Fillers are small texts that are being said by robot to create a display of presence and activity in dialogue. Fillers are very helpful when GPT takes longer time to generate a response.

Fillers are turned on by adding preferred phrases in fillerTexts . It should look like this.

Thinking is a feature, aimed at perfecting GPT’s following to the requirements of the prompt, and potentially checking on which stage of the dialogue did GPT fail through debug log.

You can see thinking process with the Inspector tool on our platform. It will look something like this.

The format function allows you to format a source string by incorporating provided arguments, local variables, and context variables. This function operates similarly to the answerWithGPT and askGPT methods, where the arguments (args) are embedded within the prompt.

The formatted string with the provided arguments, local variables, and context variables inserted in place of their respective placeholders.

This example demonstrates the formatting process, resulting in the string: 42: Override/Local Override 2/In context 3.

The sequence of replacement is as follows:

Arguments: First, the function checks for the variable in the provided arguments (args). Scope Variables: If the variable is not found in the arguments, it checks for the variable in the local scope. Context Variables: If the variable is still not found, it checks for the variable in the context. Warning: If the variable is not found in any of the above steps, a warning is displayed and the placeholder {{your_variable_name}} remains unchanged.

This ensures that the most relevant and specific variable is used for formatting the string.

Attempts to establish a connection (starts a call) and returns the result of the attempt. Blocks execution until the result of the connection attempt is received.

object

Object depends on connection attempt outcome.

On success: returns an object with the following fields:

On failure: returns an object with the following fields:

Establishes a connection (starts a call) and returns the result of the attempt. If the connection failed, it stops script execution with the error "Connection failed". Blocks execution until the result of the connection attempt is received.

object

Object with the following fields:

IConnectionResult is an object with the following fields:

Emits SIP Refer with Refer-To username equals to the endpoint for SIP-based channels. Nothing for a text-based channel (chat).

boolean

Always true.

Closes the connection (ends the call). Blocks execution until the result of the attempt to close the connection is received.

object

Object with the following fields:

Disable speach-to-text (STT) and natural-language-understanding (NLU) in current block or main context (the main graph is implicitly a block too.).

Note that recognition disabling interrupts the calculation of duration of the current session.

boolean

Always true.

Enables speach-to-text (STT) and natural-language-understanding (NLU) in current block or main context (the main graph is implicitly a block too.).

Note that enabling of recognition turns on the calculation of duration of the current session.

boolean

Always true.

The noiseControl function enables or disables background noise in the current channel. It can be called only after establishing a connection using either the connect or connectSafe methods.

boolean

Always true

The recordControl function manages the recording of audio in the current channel. It can be invoked only after establishing a connection using either the connect or connectSafe methods.

boolean

Always true

Sends a command to say a phrase from connected phrasemap.

Blocks control until the phrase had been said (or interrupted).

boolean

true if the phrase was said completely, false if it was interrupted.

Channeled version of the builtin function #say.

Similarly to the #say it sends a command to pronounce a phrase from a phrasemap.

Unlike the #say function, #sayChanneled allows you to pronounce phrase in the specific channels provided by channelIds parameter. If channelIds is not provided or provided as an empty array, then the phrase will be pronounced in all channels. It does not affect phrase buffer, so it does not have repeatMode parameter.

Blocks control until the phrase is spoken.

boolean

Always true as it can not be interrupted.

Sends a command to say the text. Differs from say in that the text parameter is interpreted literally rather than being resolved via phrasemap.

Blocks control until the phrase had been said (or interrupted).

Warning: it is not recommended to use this function in production.

boolean

true if the phrase was completely said, false if it was interrupted.

Channeled version of the builtin function #sayText.

Similarly to the #sayText it sends a command to pronounce a phrase from a phrasemap.

Unlike the #sayText function, #sayTextChanneled allows you to pronounce phrase in the specific channels provided by channelIds parameter. If channelIds is not provided or provided as an empty array, then the phrase will be pronounced in all channels. It does not affect phrase buffer, so it does not have repeatMode parameter. Also, it cannot be interrupted.

Blocks control until the phrase is spoken.

boolean

Always true as it can not be interrupted.

Sends a command to repeat phrases from the phrase buffer (see repeatMode argument of say or sayText).

Due to the variability of phrases (which set in phrasemap) calling the #repeat() may enliven a dialogue and help the dialogue sound more human-like.

Blocks control until the phrase had been said (or interrupted).

IRepeatAccuracy is a enum of string literals that denote which phrasemap sub-key will be used to pronounce:

• first
• repeat
• short

boolean

true if the phrase was completely said, false if it was interrupted.

The phrase buffer is a system buffer used to accumulate phrases that you may pronounce again to repeat them to a user.

Use builtin function #repeat() to repeat phrases accumulated in buffer.

Due to the variability of phrases (which set in phrasemap) calling the #repeat() may enliven a dialogue and help the dialogue sound more human-like.

The content of phrase buffer is controlled by repeatMode argument used to invoke phrases pronunciation (see IRepeatMode).

IRepeatMode is a enum of string literals, which control phrase buffer update logic:

• override: override phrase buffer. If the phrase is pronounced with repeatMode:"override", the buffer will be cleaned and the phrase will be appended to empty buffer.
• complement: append to the phrase buffer. The phrase buffer will not be cleaned and the current phrase will be appended to the buffer.
• ignore: do not change the phrase buffer. The phrase buffer will not be cleaned and the current phrase will not be appended to the buffer.

Suppose, you have the following phrasemap content:

... and the following DSL code:

, then the last #repeat will actually trigger the following text to be pronounced by Dasha:

So, the current buffer content was pronounced and (where possible) the "repeat" versions of phrases were used.

Sends a command to prepare a phrase.

If phrase specified in phrasemap is static (i.e. it does not have any arguments) it is prepared automatically prepared before dialog begins.

Otherwise, if phrase is dynamic and requires some arguments, it can not be prepared in advance and since that it is prepared when calling #say function.

The preparation process requires some time, so if unprepared phrase is being prepared in runtime, it may cause lags in dialogue.

To avoid this you may use the #preparePhrase function before the actual dialogue is started to force prepare some dynamic phrase with particular arguments.

The parameters phraseId and options are the same as for #say function.

boolean

Always true.

NOTE: Different NLG control functions consume different options. See the description of the desired function.

NOTE: If interruptDelay set to some specific value, it will be consider as additional trigger. Otherwise, the default behaviour (interrupting by 2-second-long utterance) will be ignored.

Checks if the phrase being processed contains the specified intent.

State defines intent polarity. It works only for intent that allows it. Read here how to create custom polar intents.

Possible state values:

• positive
• negative

boolean

true if the phrase contains the specified intent, otherwise it returns false.

Checks if the phrase being processed contains any of the specified intents.

boolean

true if the phrase contains any specified intents, otherwise it returns false.

Checks if the phrase being processed contains a specified sentiment.

Possible sentiment values:

• positive
• negative

Connect sentiment skill in .dashaapp to extract sentiment from messages.

boolean

true if the phrase contains the specified sentiment, otherwise it returns false.

Checks if the phrase being processed fulfills a given filter condition.

IFilter is a map from string to boolean or string. The key of the map corresponds to the entity name, boolean value denotes if the entity must be present (true) or absent (false) in the message, string value sets a requirement for a concrete value of the entity.

boolean

true if the phrase fulfills the condition, false otherwise.

Extracts entities fulfilling a given condition.

IFilter is a map from string to boolean or string. The key of the map corresponds to the entity name, boolean value denotes if the entity must be present (true) or absent (false) in the message, string value sets a requirement for a concrete value of the entity.

object[]

An array of entities extracted from the phrase being processed. Each element of the array returned is an object which keys are strings correspond to entity names and values are string corresponds to entity values.

Get sentence type for current message text.

Read more about the sentence types here.

string?

Possible values:

• statement - Declarative sentences: Used to make statements or relay information
• request - Imperative sentences: Used to make a command or give a direct instruction
• question - Interrogative sentences: Used to ask a question
• null - type of sentence is not classified (create custom intents or/and entities, then it will be classified)

Returns last processed message text (what user said). Available only in digression and in onexit section of the transition with condition tag ontext.

Note:

• tag ontext is default tag in conditions and can be ommited

String with text said by the user

number

Time in milliseconds since the script launch

number

Time in milliseconds since the last phrase/word said by the system or the interlocutor, or since the end of the wait.

Starts a timer in the context of the current block.

string

The handler of the started timer.

Checks if the timer has expired.

boolean

true if the timer has expired, otherwise false.

number

A time of the last visit to the specified node in the current context since the script started. Returns 0 if the node has not been visited.

number

The number of visits to the specified node in the current context.

Pauses IdleTime calculation (returned by the getIdleTime call) until the specified timeout expires, or until the interlocutor's voice is detected.

boolean

Always true.

Note: For more details, see Complex logic at the start of conversation.

Blocks execution until the voice of the interlocutor is detected, or until the specified timeout expires. If timeout did expire, than ensures text event on the current (or closest next, if there is no current) segment: if text is missing in the original segment, an empty text will be added to the segment. The simulated recognition result does not contain intents

boolean

true, if a voice was found, otherwise false.

Note: this function is intended to enable complex logic at the start of a conversation and should be used in pair with waitForSpeech. For more details, see Complex logic at the start of conversation.

Ensures text event on the current (or closest next, if there is no current) segment: if text is missing in the original segment, an empty text will be added to the segment.

boolean

Always true.

VAD refers to voice activity detection. Just as it sounds - this is the time that Dasha monitors the channel for additional user speech before responding to the user.

The function #setVadPauseLength can be helpful when a user is asked some question that may require long user answer with long pauses in speech. For example, when one is asked the question "Tell me your address, please?" the user may need some time to phrase their reply. In such a case the VAD pauses should be longer than in the case of regular conversation, for example a simple "yes-no" reply.

It sets the multiplier of the pause detection parameter (see vadPauseDelay parameter) which is used to detect the end of user speech. The default value is 1.0.

You may want to use this if you feel Dasha is too quick to respond to the user.

boolean

Always true.

Gets description of specified async block.

If id is not provided (or null) then the function returns description of the current block.

{ isSessionOpened: boolean; exist: boolean; id: string; }

• isSessionOpened - true if this async block's session is ongoing
• exist - true if this async block exists
• id - id of this async block

Checks if current message is async block message of specified type.

If argument type is not provided, checks if current message is async block message of any type.

boolean

true if current message is async block message of specified type

Gets content of async block message.

None

AsyncBlockMessage (see Async Block Messages)

Sends message from current async block to async block with targetRouteId.

boolean

Bridges the current async block channel and target async block channels.

If biDirectional == true the current user will hear target users (and vice versa), but target users will not hear each other (unless there are bridges between them already). Otherwise, the current user will hear the bridged users.

boolean

Unbridges current async block channel and target async block channels.

boolean

Performs an HTTP request, blocking the script execution until a response is returned, or a specified timeout is reached.

All requests are sent by the backend part of your application, not from Dasha itself. See the SDK docs to learn how to customize the requests being sent, or disable this feature altogether.

An object with the following fields:

number

A pseudo-random number between 0 and 1 (including 0 but not including 1) using a uniform distribution of the random variable.

Sends DTMF message, if a current channel is a SIP.

Returns DTMF message(buttons press on phone), if the last received message is DTMF. Actual only for SIP channels. Actual only when you are handling messages with tag onprotocol

Returns string - if we have received DTMF now, null otherwise

Converts a string to an integer.

If a string represents float number it will be floored to an integer.

If a string can not be converted into a number, the function will return NaN.

number

An integer number if string could be converted into a number, NaN otherwise.

Converts a string to a floating-point number.

If a string can not be converted into a number, the function will return NaN.

number

A floating-point number if string could be converted into a number, NaN otherwise.

Converts any value to a string.

string

Stringified object

Outputs message to the application output. The message may be any object that could be created in DSL.

Returns a dialogue transcription as an array of objects.

Where name is a humanName option of connectOptions or null if not set.

Returns a dialogue transcription as a string

• If humanName in #connect/#connectSafe not set

• If humanName in #connect/#connectSafe is set to agent

• Warm transfer with humanName set for the agent connection and #disableRecognition() was not called, and option channelIds is set to []