Guava.Call (Guava v0.36.0)

A handle to a live call, passed to your Guava.Agent handlers.

Use it to steer the conversation: assign tasks, set the persona, send instructions, transfer, read collected fields, and more. Every mutating function enqueues a command on the call's WebSocket connection.

Summary

Types

t()

Functions

add_info(call, label, info)

Provide the agent contextual information about a topic.

call_info(call)

The call's Guava.CallInfo.

default_reach_person_outcomes()

The default set of reach_person outcomes.

get_field(call, key, default \\ nil)

Read a collected field value by key.

get_variable(call, key, default \\ nil)

Read a call-scoped variable.

hangup(call, final_instructions \\ "")

Instruct the agent to naturally end the conversation and hang up.

has_field?(call, key)

Whether a field has been collected.

id(call)

The call's session id.

reach_person(call, contact_full_name, opts \\ [])

Reach a specific contact on an outbound call and record their availability in the contact_availability field. React to the outcome in Guava.Agent.handle_task_complete/3 (task id "reach_person"), reading the contact_availability field with get_field/2.

read_script(call, script)

Have the agent read a script verbatim.

retry_task(call, reason)

Ask the agent to retry the current task.

send_command(call, command)

Send an arbitrary command struct on this call.

send_dtmf(call, digits)

Press a sequence of DTMF digits on the call (e.g. to navigate an IVR).

send_instruction(call, instruction)

Send a free-form instruction to steer the agent.

set_agent_dtmf(call, enabled)

Enable or disable the agent pressing DTMF digits. Not supported on WebRTC calls.

set_language_mode(call, primary \\ "english", secondary \\ [])

Set primary and secondary spoken languages.

set_persona(call, opts \\ [])

Set the agent's persona.

set_task(call, task_id, opts \\ [])

Assign a task: an objective and/or a checklist of items.

set_variable(call, key, value)

Store a JSON-serializable, call-scoped variable.

transfer(call, destination, instructions \\ nil)

Transfer the call to a destination (phone number or SIP address).

Types

t()

@type t() :: %Guava.Call{
  call_info: Guava.CallInfo.t(),
  emit: (map() -> :ok) | nil,
  id: String.t(),
  server: pid(),
  table: :ets.tid()
}

Functions

add_info(call, label, info)

@spec add_info(t(), String.t(), term()) :: :ok

Provide the agent contextual information about a topic.

call_info(call)

@spec call_info(t()) :: Guava.CallInfo.t()

The call's Guava.CallInfo.

default_reach_person_outcomes()

The default set of reach_person outcomes.

get_field(call, key, default \\ nil)

@spec get_field(t(), String.t(), term()) :: term()

Read a collected field value by key.

get_variable(call, key, default \\ nil)

@spec get_variable(t(), String.t(), term()) :: term()

Read a call-scoped variable.

hangup(call, final_instructions \\ "")

@spec hangup(t(), String.t()) :: :ok

Instruct the agent to naturally end the conversation and hang up.

has_field?(call, key)

@spec has_field?(t(), String.t()) :: boolean()

Whether a field has been collected.

id(call)

@spec id(t()) :: String.t()

The call's session id.

reach_person(call, contact_full_name, opts \\ [])

@spec reach_person(t(), String.t(), keyword()) :: :ok

Options

:greeting — verbatim opening line.
:voicemail_message — leave this message on voicemail, then hang up.
:voicemail_hangup — hang up immediately on voicemail (no message).
:outcomes — override the availability outcomes (list of maps with :key, optional :description, optional :next_action_preview).

read_script(call, script)

@spec read_script(t(), String.t()) :: :ok

Have the agent read a script verbatim.

retry_task(call, reason)

@spec retry_task(t(), String.t()) :: :ok

Ask the agent to retry the current task.

send_command(call, command)

@spec send_command(
  t(),
  struct()
) :: :ok

Send an arbitrary command struct on this call.

Called from one of your handlers, the command is transmitted immediately, so commands you issue reach the server in the order you issued them — before any reply the runtime sends for the event being handled.

send_dtmf(call, digits)

@spec send_dtmf(t(), String.t() | [String.t()]) :: :ok

Press a sequence of DTMF digits on the call (e.g. to navigate an IVR).

digits may be a string like "123" or a list of single-digit strings. Each digit must be a valid DTMF digit (see Guava.Types.dtmf_digits/0). Not supported on WebRTC calls.

send_instruction(call, instruction)

@spec send_instruction(t(), String.t()) :: :ok

Send a free-form instruction to steer the agent.

set_agent_dtmf(call, enabled)

@spec set_agent_dtmf(t(), boolean()) :: :ok

Enable or disable the agent pressing DTMF digits. Not supported on WebRTC calls.

set_language_mode(call, primary \\ "english", secondary \\ [])

@spec set_language_mode(t(), String.t(), [String.t()]) :: :ok

Set primary and secondary spoken languages.

set_persona(call, opts \\ [])

@spec set_persona(
  t(),
  keyword()
) :: :ok

Set the agent's persona.

Options

:organization_name, :agent_name, :agent_purpose, :voice.

set_task(call, task_id, opts \\ [])

@spec set_task(t(), String.t(), keyword()) :: :ok

Assign a task: an objective and/or a checklist of items.

Checklist items may be Guava.Field structs, Guava.Say, Guava.Todo, or plain strings (converted to todos).

set_variable(call, key, value)

@spec set_variable(t(), String.t(), term()) :: :ok

Store a JSON-serializable, call-scoped variable.

transfer(call, destination, instructions \\ nil)

@spec transfer(t(), String.t(), String.t() | nil) :: :ok

Transfer the call to a destination (phone number or SIP address).

instructions (optional) tells the agent what to say; when omitted the agent announces a transfer before connecting. This is always a soft transfer.