Built-in functions

The system provides a set of built-in functions, mainly designed to control the dialogue process. For example, to say a phrase, repeat, connect, wait for the interlocutor, and so on.

An inline function can be called from an executable section by its name using the inline data access prefix #:

node myNode { do { #sayText("Hello, world!"); // Calling the "say" function. } transitions { // Custom transitions... } }

Blocking calls

A function call is called blocking if it stops the execution of the further part of the section until the required event is received. When the required event is received, the function returns the result and the section execution continues.

Session control

connect (blocking call)

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.

#connect(endpoint);

Parameters

NameTypeDescription
endpointstringendpoint to connect to

Returns

object

Object depends on connection attempt outcome.

On success: returns an object with the following fields:

NameTypeDescription
msgIdstring literalcontains value "OpenedSessionChannelMessage"
endpointstringendpoint with which a connection is established

On failure: returns an object with the following fields:

NameTypeDescription
msgIdstring literalcontains value "FailedOpenSessionChannelMessage"
reasonstringthe reason why the connection could not be established
detailsstringadditional information

connectSafe (blocking call)

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.

#connectSafe(endpoint);

Parameters

NameTypeDescription
endpointstringendpoint to connect to

Returns

object

Object with the following fields:

NameTypeDescription
messageIConnectionResultmessage received in response to a connection request

IConnectionResult is an object with the following fields: | Name | Type | Description | |----------|----------------|-------------------------------------------------| | msgId | string literal | contains value "OpenedSessionChannelMessage" | | endpoint | string | endpoint with which a connection is established |

forward

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

#forward(endpoint);

Parameters

NameTypeDescription
endpointstringendpoint to connect to

Returns

boolean

Always true.

disconnect (blocking call)

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

#disconnect();

Returns

object

Object with the following fields:

NameTypeDescription
hangupMsgIdstringthe identifier of the message indicating that the connection was closed

NLG Control

say (blocking call)

Sends a command to say a phrase. Blocks control until the phrase had been said (or interrupted).

#say(phraseId, repeatMode, interruptible);

Parameters

NameTypeDescription
phraseIdstringphrasemap key of the phrase to be spoken
repeatMode?IRepeatModecontrol repeating logic, (see IRepeatMode) default value: override
interruptible?booleanwhether the phrase could be interrupted, default value: false
options{emotion?: string; speed?: number;}Override speed and emotion of saying text

IRepeatMode is an enum of string literals, each one denotes phrase buffer update logic:

  • override: override phrase buffer

  • complement: append to the phrase buffer

  • ignore: do not change the phrase buffer

Returns

boolean

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

sayText (blocking call)

Sends a command to say the text. Blocks control until the phrase had been said (or interrupted). Differs from say in that the text parameter is interpreted literally rather than being resolved via phrasemap.

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

More details This function does not require phrasemap at the cost of no static analysis is performed of whether the phrase is available (in case of prerecorded speech) and no pre-synthesis is performed (in case of synthesized speech) which may cause delays at runtime as well as no caching will be used which cause re-synthesizing on each run.

Thus, this function may be used for demonstration purposes allowing the script to be as simple as possible, but it is strongly recommended to not use it in production cases.

#sayText(text, repeatMode, interruptible, options);

Parameters

NameTypeDescription
textstringtext to say
repeatMode?IRepeatModecontrol repeating logic, (see IRepeatMode) default value: override
interruptible?booleanwhether the phrase could be interrupted, default value: false
options{emotion?: string; speed?: number;}Control speed and emotion of saying text

IRepeatMode is an enum of string literals, each one denotes phrase buffer update logic:

  • override: override phrase buffer

  • complement: append to the phrase buffer

  • ignore: do not change the phrase buffer

Returns

boolean

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

Examples

//just say some text #sayText("Hello, how are you?"); //say this text, without support of repeat #sayText("Hello, how are you?", "ignore"); //say this text, without support of repeat #sayText("Hello, how are you?"); #sayText("Would you like some coffee?", "complement"); //add to repeat buffer. Call of the #repeat will say "Hello, how are you? Would you like some coffee?" //this phrase can be interrupted by user, if he says something #sayText("Hello, how are you?", interruptible: true); //say this phrase fast #sayText("Hello, how are you?", options: { speed: 1.5 }); //say this phrase with emotion as from "I love you" //NOTE: you need to enable emotional dasha tts with `conv.audio.tts = "dasha-emotional"; #sayText("Hello, how are you?", options: { emotion: "from text: I love you" }); //say this phrase with emotion as from "I love you" and do it slow #sayText("Hello, how are you?", options: { emotion: "from text: I love you", speed: 0.7 }); //Build phrase from variable #sayText("Hello" + $name + ", how are you?");

repeat (blocking call)

Sends a command to say a phrase from the phrase buffer (see repeatMode argument of say or sayText). Blocks control until the phrase had been said (or interrupted).

#repeat(accuracy, interruptible);

Parameters

NameTypeDescription
accuracy?IRepeatAccuracyphrasemap sub-key to use, default value: "repeat"
interruptible?booleanwhether the phrase could be interrupted, default value: false

IRepeatAccuracy is an enum of string literals, each one denotes phrasemap sub-key:

  • first
  • repeat
  • short

Returns

boolean

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

NLU Control

messageHasIntent

Checks if the phrase being processed contains the specified intent.

#messageHasIntent(intent, state);

Parameters

NameTypeDescription
intentstringthe name of the intent being checked
statestringpolarity state, default value: positive

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

Returns

boolean

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

Example

digression hello { conditions { on #messageHasIntent("hello"); } do { } }
node can_i_help { do { #sayText("How can I help?"); wait *; } transitions { transfer_money: goto transfer_money on #messageHasIntent("transfer_money"); } }
node transfer_money_confirm { do { #sayText("Do you confirm money transfer?") wait *; } transitions { positive: goto process_transfer on #messageHasIntent("agreement", "positive"); negative: goto transfer_money on #messageHasIntent("agreement", "negative"); }

messageHasAnyIntent

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

#messageHasAnyIntent(intents);

Parameters

NameTypeDescription
intentsstring[]array of names of the intents being checked

Returns

boolean

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

Example

node transfer_money_confirm { do { #sayText("Do you confirm money transfer?") wait *; } transitions { agree: goto process_transfer on #messageHasAnyIntent(["confirm", "agree"]); disagree: goto cancel_transfer on #messageHasAnyIntent(["cancel", "disagree"]); } }

messageHasSentiment

Checks if the phrase being processed contains a specified sentiment.

Parameters

NameTypeDescription
sentimentstringname of the sentiment being checked

Possible sentiment values:

  • positive
  • negative

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

#messageHasSentiment(sentiment);

Returns

boolean

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

Example

node transfer_money_confirm { do { #sayText("Do you confirm money transfer?") wait *; } transitions { agree: goto process_transfer on #messageHasSentiment("positive"); disagree: goto cancel_transfer on #messageHasSentiment("negative"); } }

messageHasData

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

#messageHasData(dataType, filter);

Parameters

NameTypeDescription
dataTypestringa name of a skill that generates entities being checked
filterIFiltera filter that defines the requirements for a phrase

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.

Example

node transfer_money { do { #sayText("From which accounts you would like to transfer from?") wait *; } transitions { provide_data: goto validate_account on #messageHasData("account"); } onexit { provide_data: do { set $account = #messageGetData("account", { value: true })[0]?.value??""; } } }

Returns

boolean

true if the phrase fulfills the condition, false otherwise.

messageGetData

Extracts entities fulfilling a given condition.

#messageGetData(dataType, filter);

Parameters

NameTypeDescription
dataTypestringa name of a skill that generates entities being checked
filterIFiltera filter that defines the requirements for a phrase

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.

Returns

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.

Example

node transfer_money { do { #sayText("From which accounts you would like to transfer from?") wait *; } transitions { provide_data: goto validate_account on #messageHasData("account"); } onexit { provide_data: do { set $account = #messageGetData("account", { value: true })[0]?.value??""; } } }
node say_food { do { for (var item in #messageGetData("food")) { #sayText(item?.value ?? ""); } } }
node say_food { do { var account = #messageGetData("account", { value: true, tag: true })[0]; if (account.tag == "source") { set $source_account = account?.value??""; } } }
external function resolve_account(info: string): string; node myNode { do { set $account = #messageGetData("account", { value: true })[0]?.value??""; set $account = external foo($account); } transitions {} }

getSentenceType

Get sentence type for current message text.

Read more about the sentence types here.

#getSentenceType();

Returns

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)

Example

if (#getSentenceType() == "request") { #sayText("Sorry, I can't do it now", repeatMode: "ignore"); } else if (#getSentenceType() == "question") { #sayText("Sorry, I don't understand the question", repeatMode: "ignore"); } else { #sayText("I don't understand. Repeat please.", repeatMode: "ignore"); }

getMessageText

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

Returns

String with text said by the user

Example

digression hello { conditions { on #messageHasIntent("hello"); } do { var text = #getMessageText(); #log(text); return; } } node myNode { do { wait *; } transitions { next: goto next on true; } onexit { next: do { var text = #getMessageText(); #log(text); } } } node next { do { exit; } }

Dialogue control

getCurrentTime

#getCurrentTime();

Returns

number

Time in milliseconds since the script launch

getIdleTime

#getIdleTime();

Returns

number

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

startTimer

Starts a timer in the context of the current block.

#startTimer(duration);

Parameters

NameTypeDescription
durationnumbertimer duration in milliseconds

Returns

string

The handler of the started timer.

isTimerExpired

Checks if the timer has expired.

#isTimerExpired(instanceId);

Parameters

NameTypeDescription
instanceIdstringhandler of the checked timer

Returns

boolean

true if the timer has expired, otherwise false.

getLastVisitTime

#getLastVisitTime(name);

Parameters

NameTypeDescription
namestringname of the target node

Returns

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.

getVisitCount

#getVisitCount(name);

Parameters

NameTypeDescription
namestringname of the target node

Returns

number

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

waitingMode

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

#waitingMode(duration);

Parameters

NameTypeDescription
durationnumberduration to wait in milliseconds

Returns

boolean

Always true.

waitForSpeech (blocking call)

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

#waitForSpeech(duration);

Parameters

NameTypeDescription
durationnumberduration to wait in milliseconds

Returns

boolean

true, if a voice was found, otherwise false.

ensureRSM

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.

#ensureRSM();

Returns

boolean

Always true.

Utilities

random

#random();

Returns

number

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

sendDTMF

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

Parameters

NameTypeDescription
codestringThe dtmf message for sending

getDTMF

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

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

Example

digression dtmf { conditions { on #getDTMF() is not null tags: onprotocol; } do { var data = #getDTMF(); #log(data); return; } }
Found a mistake? Email us, and we'll send you a free t-shirt!

Enroll in beta

Request invite to our private Beta program for developers to join the waitlist. No spam, we promise.