Alternative return value for await_delivery

If :await_delivery is set to true, the function will return a map with the following keys:

• :success - a boolean indicating whether the SMS was delivered successfully
• :error_message - a string describing the delivery error when not successful
• :failure_reason - one of:
  • :recipient_unreachable
  • :recipient_incorrect
  • :delivery_failure
  • :blacklisted
  • :not_registered_for_this_country
  • nil (if the SMS was delivered successfully)

sms_notify(phone, message)

Deprecated, please use sms() instead

spawn_function(function, args)

Run a function asynchronously

Runs the given function asynchronously. When the function finishes, its return value is sent to the calling process as an event.

The name of the event is returned as the return value of spawn_function().

dialog main do
  # spawn the function in the background
  _eventname = spawn_function(:worker, ["some_arg"])

  say "We are processing your request, one moment"
  _result = await(event(_eventname))
  say("HTTP worker result = #{_result.payload}")
end

function worker(_arg) do
  log "Going to post in the background.."
  _result = http_post @url
  log "done"
  return _result.body
end

As the name of the event is dynamic, the event should be awaited on in the main conversation using await or with the wait control.

@constants are available in the spawned function, as well as the global variables. However, the global variables CANNOT be changed: they are set to a snapshot of the globals at time the function was spawned. Any changes to the globals not carried over to the main conversation, these are lost when the spawned function is done.

The lifecycle of a spawned function is limited to the lifecycle of the conversation: as soon as the conversation finishes (via close or similar), all still running spawned functions will exit.

Side effects like tag and logging is supported in spawned functions. However, the remember and forget statements are forbidden, as these could cause race conditions.

spawn_group(group \\ nil, context \\ %{})

Spawn a group process.

strip_emoji(string)

Remove any emoji from a given string.

strip_html(string)

Remove HTML tags from a given string.

strip_markdown(string)

Remove Markdown formatting from a given string.

strip_speechmarkdown(string)

Remove any Speech Markdown formatting from a given string.

tag?(tag)

Retrieve the value of a prefixed tag, or true / false for a normal tag, for the tags that are set on the current conversation.

tag "workflow::assigned"
say tag?("workflow")

Will say assigned.

tag "hello"
if tag?("hello"), do: say "Hello is set"

testing?()

Helper function for checking whether the bot is running as part of a test case

Returns true if that is the case, or false otherwise.

Using this function can help you switching parts of your bot (mocking data, HTTP calls etc.) when the bot tests are being run.

text_to_speech(smd, opts \\ [])

Perform text-to-speech on the given speech markdown string.

Returns the URL to the stored MP3 audio recording. Results are cached so that performing the same text-to-speech twice will return the same URL.

text to speech can fail because the requested locale does not have a corresponding voice configuration, or the Google TTS backend returns an error. In both cases, nil is returned to the caller.

Options:

• :locale — The locale to speak in. Must have a voice configured in the corresponding connected channel. (if the conversation is not on a voice channel, it is assumed the REST API channel is enabled which also has a voices configuration).

transcribe(input, request_params \\ [])

Transcribe the given audio attachment or URL into a %Bubble.Message{} struct.

Options:

• locale - use recognition in given locale (defaults to locale of conversation)
• provider - A transcription provider, e.g. google, microsoft_openai, etc.
• model - the name of the provider-specific model to use.

See the transcribe REST API docs for more information on all available transcribe parameters, or Audio transcription support for more information on provider-specific parameters.

unassign_conversation()

Unassigns the operator from the current conversation.

If there was not operator assigned, then this function returns false.

unidecode(text)

Transliterate a string with accented characters to a plain ASCII version without any accents or special symbols.

whatsapp(phone, template_id, opts \\ [])

Send the given Whatsapp template message to the given phone number.

The current bot must have a valid 360dialog Whatsapp connection setup up in order for this function to work. Furthermore, the given

The given whatsapp template identifier (template_id) must exist in the conversation's locale (or with the overridden locale: option).

A new whatsapp conversation will be started that has a conversation.originator map. This map includes conversation.originator.addr which can be used to send events back to this conversation.

Options:

• :parameters - a map of numbered body parameters, e.g. %{"1" => "Pete", "2" => "example"}; can only used for basic text-only templates. Will be ignored if :components option is given.

• :components - A full list of template component parameters (https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#template-object)

• :locale - a locale string to override the locale that is selected for sending the template message.

• :on_existing - The desired behaviour if there's already an existing Whatsapp conversation. Defaults to :cancel.

  • :cancel: Don't send a template, return false. Does nothing.
  • :close: Close the existing conversation, then start a new one.

• :conversation_data - A map of data to merge into the global variables of the new conversation.

within_office_hours(office_hours, opts \\ [])

Calculate whether the given date is within the given week day office hours.

The office_hours variable must be a 7-item array in which each item represents an opening/closing hour. The first (0th) element in the array is sunday, the last is saturday.

Options:

• timezone - The timezone to consider (defaults to user.timezone or bot.timezone)
• date - The reference date to consider (defaults to date_now())

write_script(title, contents, opts \\ [])

Write a script file by name.

This function is primarily meant for writing migrations that work on content scripts. It only works given the following conditions:

• The script (by title) must already exist, or the type: option must be given
• The function is called within the DialoX studio, in preview mode (debugging)
• The user that calls the script must be allowed to change the script

The function only works for existing scripts. The content type of the script is unchanged, and the content must be formatted in the right format; e.g. the caller must know that the file is JSON, bubblescript, YAML, etc. The draft version of the script is written; e.g. a manual publish is still required to put the change 'live'.

Options:

• :type - a valid script MIME type (text/bubblescript, text/yaml+data, application/json+data, etc)

yaml_build(data)

Convert a given value to a string encoded as YAML.

yaml_parse(string)

Convert the given JSON-encoded string to a data structure. Returns nil when decoding fails.