Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Live voice agents use a separate WebSocket endpoint from voice-agent realtime sessions. Foundry sends session.start; clients wait for session.started. Do not negotiate the realtime WebSocket subprotocol on this endpoint. session.update changes backend settings, not the Foundry delegation target. response.item.create and response.create require Responses delegation.
These tables describe the event properties and link to their models.
Client events
- session.start
- session.update
- session.input_audio.append
- session.input_audio.mute
- session.input_audio.unmute
- session.output_audio.fixture.play
- session.instructions.append
- session.thinking.append
- session.commentary.append
- decision.create
- decision.item.create
- decision.item.delete
- response.item.create
- response.create
- session.close
session.start
Schema: OpenAI.LiveSessionStartEvent.
Foundry sends this event to start the Live session.
All of: OpenAI.LiveClientEvent.
| Property | Type | Required | Description |
|---|---|---|---|
event_id |
Any of: string; null |
No | |
type |
"session.start" |
Yes | The Live client event type. Always session.start. |
session |
OpenAI.LiveSessionCreateParams | Yes | Initial session configuration supplied by Foundry. |
Required preview opt-ins: VoiceAgents=V1Preview.
session.update
Schema: OpenAI.LiveClientEventLiveSessionUpdateParam.
Update the delegation settings or transcript triggers of an active Live session. The server acknowledges accepted changes with session.updated.
All of: OpenAI.LiveClientEvent.
| Property | Type | Required | Description |
|---|---|---|---|
event_id |
Any of: string; null |
No | |
type |
"session.update" |
Yes | The Live client event type. Always session.update. default: "session.update". |
session |
OpenAI.LiveSessionUpdateParams | Yes | Sparse delegation and trigger updates. Omitted settings retain their values. The delegation type cannot change. Model, frontend instructions, audio, and startup input are immutable. |
Required preview opt-ins: VoiceAgents=V1Preview.
Example event:
{
"type": "session.update",
"event_id": "evt_update_001",
"session": {
"delegation": {
"type": "responses",
"responses": {
"instructions": "Check restaurant availability. Ask before confirming a booking.",
"max_output_tokens": 1024
}
}
}
}
session.input_audio.append
Schema: OpenAI.LiveClientEventLiveInputAudioAppendEvent.
Send audio to a Live session over its primary WebSocket. WebRTC and SIP sessions send audio over their media transport.
All of: OpenAI.LiveClientEvent.
| Property | Type | Required | Description |
|---|---|---|---|
event_id |
Any of: string; null |
No | |
type |
"session.input_audio.append" |
Yes | The Live client event type. Always session.input_audio.append. default: "session.input_audio.append". |
audio |
string |
Yes | Base64-encoded raw audio in the startup-selected format, without a WAV or other container header. Primary WebSocket only; media transports use their audio track. Audio appends have no acknowledgment. Reflected sideband server events reuse this event type and audio key, with no timestamps or event_id; their audio is always mono PCM16LE at 24 kHz. minLength: 1. |
Required preview opt-ins: VoiceAgents=V1Preview.
Example event:
{
"type": "session.input_audio.append",
"audio": "AACAAIAAAIAAAP9/AIAAgA=="
}
session.input_audio.mute
Schema: OpenAI.LiveClientEventLiveInputAudioMuteParam.
Mute audio input to the Live model without closing the session. The server acknowledges with session.input_audio.muted.
All of: OpenAI.LiveClientEvent.
| Property | Type | Required | Description |
|---|---|---|---|
event_id |
Any of: string; null |
No | |
type |
"session.input_audio.mute" |
Yes | The Live client event type. Always session.input_audio.mute. default: "session.input_audio.mute". |
Required preview opt-ins: VoiceAgents=V1Preview.
Example event:
{
"type": "session.input_audio.mute",
"event_id": "evt_mute_001"
}
session.input_audio.unmute
Schema: OpenAI.LiveClientEventLiveInputAudioUnmuteParam.
Resume audio input to a Live model after muting it. The server acknowledges with session.input_audio.unmuted. An active audio fixture still pauses inference until playback finishes.
All of: OpenAI.LiveClientEvent.
| Property | Type | Required | Description |
|---|---|---|---|
event_id |
Any of: string; null |
No | |
type |
"session.input_audio.unmute" |
Yes | The Live client event type. Always session.input_audio.unmute. default: "session.input_audio.unmute". |
Required preview opt-ins: VoiceAgents=V1Preview.
Example event:
{
"type": "session.input_audio.unmute",
"event_id": "evt_unmute_001"
}
session.output_audio.fixture.play
Schema: OpenAI.LiveClientEventLiveOutputAudioFixturePlayParam.
Play one complete audio fixture through the session output. Send this event over the primary WebSocket or a server sideband. Audio must be raw mono PCM16 little-endian at 24 kHz, regardless of the session audio format, and at most 30 seconds. The entire payload is validated before model speech is interrupted and input is muted. Only one fixture can be active. fixture.playing acknowledges acceptance and fixture.played reports server mixer drain. These notifications are not exact transport-media boundaries. Input arriving during playback is dropped and not replayed.
All of: OpenAI.LiveClientEvent.
| Property | Type | Required | Description |
|---|---|---|---|
event_id |
Any of: string; null |
No | |
type |
"session.output_audio.fixture.play" |
Yes | default: "session.output_audio.fixture.play". |
audio |
string |
Yes | Base64-encoded raw mono PCM16 audio, little-endian, at 24 kHz. Do not include a WAV or other container header. minLength: 1. maxLength: 1920000. |
Required preview opt-ins: VoiceAgents=V1Preview.
Example event:
{
"type": "session.output_audio.fixture.play",
"event_id": "evt_play_001",
"audio": "AAAAAA=="
}
session.instructions.append
Schema: OpenAI.LiveClientEventLiveInstructionsAppendParam.
Append developer instructions to the Live conversation while it is running, optionally associating them with an existing client delegation. Rejected while an audio fixture is active. These instructions remain in conversation history through compaction and are included in future backend delegations. For external audio, describe content already delivered so the assistant does not repeat it.
All of: OpenAI.LiveClientEvent.
| Property | Type | Required | Description |
|---|---|---|---|
event_id |
Any of: string; null |
No | |
type |
"session.instructions.append" |
Yes | The Live client event type. Always session.instructions.append. default: "session.instructions.append". |
delegation_id |
Any of: string; null |
Yes | |
content |
string |
Yes | Instruction text to append, limited to 500 tokens. This is a plain string, not an array of content parts. |
Required preview opt-ins: VoiceAgents=V1Preview.
Example event:
{
"type": "session.instructions.append",
"event_id": "evt_instructions_001",
"delegation_id": null,
"content": "The caller prefers outdoor seating."
}
session.thinking.append
Schema: OpenAI.LiveClientEventLiveThinkingAppendParam.
Provide silent reasoning or progress context to the Live model, optionally for an existing client delegation. Rejected while an audio fixture is active.
All of: OpenAI.LiveClientEvent.
| Property | Type | Required | Description |
|---|---|---|---|
event_id |
Any of: string; null |
No | |
type |
"session.thinking.append" |
Yes | The Live client event type. Always session.thinking.append. default: "session.thinking.append". |
delegation_id |
Any of: string; null |
Yes | |
content |
string |
Yes | Silent reasoning or progress context, limited to 500 tokens. It does not directly request speech, but can influence later speech and is not a secrecy boundary. |
Required preview opt-ins: VoiceAgents=V1Preview.
Example event:
{
"type": "session.thinking.append",
"event_id": "evt_thinking_001",
"delegation_id": "del_abc123",
"content": "Checking availability for two guests at 7 PM."
}
session.commentary.append
Schema: OpenAI.LiveClientEventLiveCommentaryAppendParam.
Provide context the Live model can communicate to the user, optionally for an existing client delegation. Rejected while an audio fixture is active.
All of: OpenAI.LiveClientEvent.
| Property | Type | Required | Description |
|---|---|---|---|
event_id |
Any of: string; null |
No | |
type |
"session.commentary.append" |
Yes | The Live client event type. Always session.commentary.append. default: "session.commentary.append". |
delegation_id |
Any of: string; null |
Yes | |
content |
string |
Yes | Speakable context for the Live model, limited to 500 tokens. Use this for a result the model should communicate; use session.thinking.append for silent context. |
Required preview opt-ins: VoiceAgents=V1Preview.
Example event:
{
"type": "session.commentary.append",
"event_id": "evt_commentary_001",
"delegation_id": "del_abc123",
"content": "There is an outdoor table for two at 7 PM. Ask whether to reserve it."
}
decision.create
Schema: OpenAI.LiveClientEventLiveDecisionCreateParam.
Evaluate the configured questions using the current conversation and Decision inputs. Reusing an event_id is rejected for the lifetime of the session.
All of: OpenAI.LiveClientEvent.
| Property | Type | Required | Description |
|---|---|---|---|
event_id |
string |
Yes | minLength: 1. maxLength: 256. |
type |
"decision.create" |
Yes | default: "decision.create". |
Required preview opt-ins: VoiceAgents=V1Preview.
Example event:
{
"type": "decision.create",
"event_id": "decision_1"
}
decision.item.create
Schema: OpenAI.LiveClientEventLiveDecisionItemCreateParam.
Append an input item for future decisions without starting an evaluation or changing Live voice context.
All of: OpenAI.LiveClientEvent.
| Property | Type | Required | Description |
|---|---|---|---|
event_id |
Any of: string; null |
No | |
type |
"decision.item.create" |
Yes | default: "decision.item.create". |
item |
OpenAI.LiveDecisionInputItemParam | Yes |
Required preview opt-ins: VoiceAgents=V1Preview.
Example event:
{
"type": "decision.item.create",
"event_id": "browser_1",
"item": {
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "Wikipedia is open."
}
]
}
}
decision.item.delete
Schema: OpenAI.LiveClientEventLiveDecisionItemDeleteParam.
Delete an input item from future decisions without starting an evaluation or changing Live voice context.
All of: OpenAI.LiveClientEvent.
| Property | Type | Required | Description |
|---|---|---|---|
event_id |
Any of: string; null |
No | |
type |
"decision.item.delete" |
Yes | default: "decision.item.delete". |
item_id |
string |
Yes | minLength: 1. |
Required preview opt-ins: VoiceAgents=V1Preview.
Example event:
{
"type": "decision.item.delete",
"event_id": "remove_browser_1",
"item_id": "msg_browser_1"
}
response.item.create
Schema: OpenAI.LiveClientEventLiveResponseItemCreateParam.
Add an input item to the Live session’s Responses backend. Requires Responses delegation; use response.create to request a response.
All of: OpenAI.LiveClientEvent.
| Property | Type | Required | Description |
|---|---|---|---|
event_id |
Any of: string; null |
No | |
type |
"response.item.create" |
Yes | The Live client event type. Always response.item.create. default: "response.item.create". |
item |
OpenAI.InputItem | Yes | An input item to append to the Responses backend conversation, such as a user message or a function tool result. |
Required preview opt-ins: VoiceAgents=V1Preview.
Example event:
{
"type": "response.item.create",
"event_id": "evt_item_001",
"item": {
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "Please check for a table for two at 7 PM."
}
]
}
}
response.create
Schema: OpenAI.LiveClientEventLiveResponseCreateParam.
Request a response from the Live session’s Responses backend, or continue a delegated response waiting for tool results. Requires Responses delegation.
All of: OpenAI.LiveClientEvent.
| Property | Type | Required | Description |
|---|---|---|---|
event_id |
Any of: string; null |
No | |
type |
"response.create" |
Yes | The Live client event type. Always response.create. default: "response.create". |
Required preview opt-ins: VoiceAgents=V1Preview.
Example event:
{
"type": "response.create",
"event_id": "evt_response_001"
}
session.close
Schema: OpenAI.LiveClientEventLiveSessionCloseParam.
Request that the Live session close. The terminal session.closed event contains the close reason and final usage.
All of: OpenAI.LiveClientEvent.
| Property | Type | Required | Description |
|---|---|---|---|
event_id |
Any of: string; null |
No | |
type |
"session.close" |
Yes | The Live client event type. Always session.close. default: "session.close". |
Required preview opt-ins: VoiceAgents=V1Preview.
Example event:
{
"type": "session.close",
"event_id": "evt_close_001"
}