AI and WebSocket Legs

Overview

WebSocket legs are first-class PBX legs in this package.

A WebSocket leg:

• has a legId
• belongs to a dialId when created by Dial -> Make Call
• can be bridged
• can play and record media
• can participate in waits
• can host a voice agent

Creating WebSocket Legs

Use SIP PBX -> Dial -> Make Call with Mode = WebSocket.

Transport Profiles

Transport Profile	Required fields	Purpose
OpenAI Realtime	OpenAI API	OpenAI realtime voice sessions.
Gemini Live	Gemini API	Gemini live voice sessions.
Generic	WebSocket URL	User-defined JSON event protocol.

OpenAI Realtime Parameters

Parameter	Required	Description
OpenAI API	Yes	OpenAI credential used for realtime session setup.
OpenAI Realtime Model	No	Realtime-capable model used for the session.
OpenAI Realtime Voice	No	Voice identifier used by the session.
OpenAI Input Transcription Model	No	Input transcription model.
OpenAI Instructions	No	Session instructions prompt.
OpenAI Prompt ID	No	Prompt registry ID.
OpenAI Prompt Version	No	Prompt version string.
OpenAI Prompt Variables JSON	No	JSON object with prompt variables.
WebSocket Start Mode	No	Immediate or Deferred.

Gemini Live Parameters

Parameter	Required	Description
Gemini API	Yes	Gemini credential used for live session setup.
Gemini Live Model	No	Live-capable Gemini model.
Gemini Live Voice	No	Voice identifier used by the session.
Gemini Live API Version	No	API version string.
Gemini Live Instructions	No	Session instructions prompt.
WebSocket Start Mode	No	Immediate or Deferred.

Generic WebSocket Parameters

Parameter	Required	Description
WebSocket URL	Yes	Target WebSocket URL.
Generic WebSocket Headers JSON	No	JSON object with outgoing headers.
Generic WebSocket Initial Messages JSON	No	JSON array of messages sent immediately after connect.
Generic Outgoing Audio Event Type	No	Event type used for PBX-to-WebSocket audio.
Generic Outgoing Audio Field	No	Field name used for PBX-to-WebSocket audio payload.
Generic Outgoing Audio Sample Rate	No	Sample rate for PBX-to-WebSocket audio.
Generic Incoming Audio Event Types	No	Comma-separated event types treated as WebSocket-to-PBX audio.
Generic Incoming Audio Field	No	Field name used for WebSocket-to-PBX audio payload.
Generic Incoming Audio Sample Rate	No	Sample rate for WebSocket-to-PBX audio.

WebSocket Start Mode

Value	Meaning
Immediate	Open the provider session as soon as the leg is ready.
Deferred	Keep the session unstarted until Attach Voice Agent finishes memory and tool setup.

AI Resource Actions

Operation: Attach Voice Agent

Parameter	Required	Description
Options -> AI Leg ID	No	Explicit AI leg override. If omitted, resolves from aiLegId, then legId, then sipPbx.aiLegId, then sipPbx.legId.

Special Inputs

Input	Meaning
main	Required normal workflow input.
ai_memory	Optional single memory input.
ai_tool	Optional tool definition inputs, multiple allowed.

Output

Branch	Typical fields
Result	legId, eventType, optional reason

Operation: Invoke AI Tool

This is a tool-definition node, not a normal executable action.

Parameter	Required	Description
AI Tool Ref	Yes	Stable public tool ref used by the trigger and voice-agent binding.
Function Description	Yes	Natural-language description shown to the model.
Flow Parameters	No	Static or expression-driven values passed to the trigger as flowParams.
Function Parameters	No	Schema entries passed to the model and later emitted as toolParams.

Function Parameter Fields

Field	Required	Description
Name	Yes	Parameter name.
Type	Yes	String, Number, Integer, or Boolean.
Description	Yes	Natural-language parameter description.
Required	No	Marks the parameter as required in the schema.

Output

Output	Meaning
Tool	Special ai_tool output consumed by Attach Voice Agent. This node does not emit a normal executable main result.

AI Tool Call Round Trip

Step	Meaning
Dial -> Make Call (Mode = WebSocket)	Creates the AI leg.
Call -> Bridge	Optionally connects it to a caller leg.
AI -> Attach Voice Agent	Binds memory and tools.
AI Tool Call Trigger -> Request	Emits aiToolRequestId, aiLegId, peerLegId, flowParams, toolParams.
Respond -> Respond To AI Tool	Returns Response Text back to the model.