Notifications

Voice

Explains Voice notifications for controlling a live voice call from a Stubber action. Useful for steering the assistant, muting the caller, and hanging up.

A voice notification sends a command to the stub's live voice call. The call is started with the Start Voice Chat task, and reports back to the stub with the _update_from_voice feedback action.

Voice notifications don't need send_to: the command always goes to the stub's own call.

The same commands are available as the Voice Command task, with the same params.

# Basic usage

Answer a request the assistant handed to the stub, eg on the action that receives the GPT Chat Task's answer:

# Common parameters

Everything inside platforms.voice is a parameter for this notification. Handlebars and ~~ work in every parameter.

# command

required

string

One of the commands below.

# voice_session_uuid

optional

string

The voice call to send the command to. It must belong to this stub.

Default: the stub's live voice call

When the stub has no live voice call, or the call is already ending, the command fails and nothing happens on the call. After another stub took the call over with Voice Session Transfer, commands from this stub fail too: only the stub that has the call steers it. Each notification adds an event to the stub saying whether it was sent, see Feedback.

# Commands

# instructions

Instructions that steer the assistant. These may interrupt what it is saying.

# command

required

string

instructions

# content

required

string

The instructions for the assistant. Long content is split into several parts automatically.

# delegation_id

optional

string

Ties the content to a request the assistant handed to the stub. Use the delegation_id from the _update_from_voice that asked for it, eg {{stub.data._incoming_voice_data.delegation_id}}.

Without it, or when the id is empty or unknown, the content is context for the whole call.

# thinking

Silent context the assistant can use later in the call. Nothing is said aloud.

# command

required

string

thinking

# content

required

string

The context to give the assistant. Long content is split into several parts automatically.

# delegation_id

optional

string

Ties the content to a request the assistant handed to the stub. Use the delegation_id from the _update_from_voice that asked for it, eg {{stub.data._incoming_voice_data.delegation_id}}.

Without it, or when the id is empty or unknown, the content is context for the whole call.

# commentary

Something for the assistant to say aloud, close to word for word. Commentary is the usual way to answer a request the assistant handed to the stub.

# command

required

string

commentary

# content

required

string

What the assistant should say. Long content is split into several parts automatically.

# delegation_id

optional

string

Ties the content to a request the assistant handed to the stub. Use the delegation_id from the _update_from_voice that asked for it, eg {{stub.data._incoming_voice_data.delegation_id}}.

Without it, or when the id is empty or unknown, the content is context for the whole call.

# mute

Mutes the caller, so the assistant stops hearing them. The call stays up and the assistant can still speak.

# command

required

string

mute

# unmute

Unmutes the caller.

# command

required

string

unmute

# hangup

Ends the call once the assistant has finished speaking, or after 15 seconds at most. If the caller hasn't joined yet, the call ends straight away.

The stub gets a final _update_from_voice with event: "session_ended" once the call has ended.

# command

required

string

hangup

# content

optional

string

Instructions for the assistant before the call ends, eg "Say goodbye briefly."

# Feedback

Every voice notification adds an event to the stub, under the stubpost of the action that sent it, so you can see what happened to it:

• Voice commentary sent to the call when the command was sent
• Voice mute failed: no_active_voice_session when it failed, with the reason

The details are in the event's data.voice_data:

        "voice_data": {
  "command": "commentary",
  "success": true,
  "voice_session_uuid": "ae2ca8c6-ddf3-4840-9255-d9520a9cac7e",
  "content": "There's a table for two at seven.",
  "delegation_id": "item_ETSXQ2Sev4SEHt5NNoRmx"
}

      

When it failed, success is false and error has the message and details, eg the stub the call moved to for voice_session_transferred.

"Sent" means the call accepted the command. The assistant still decides how and when to act on it: a commentary is said in the assistant's own words, and may come after what it's saying now.