Bidirectional realtime WebSocket transport that streams base64 PCM microphone audio from the browser to Layercode and streams synthesized speech, transcripts, and structured data back, authorized with a short-lived client_session_key.
asyncapi: '2.6.0'
id: 'urn:com:layercode:agents:web:websocket'
info:
title: Layercode Realtime Voice WebSocket API
version: '1.0.0'
description: |
AsyncAPI 2.6 description of Layercode's **realtime voice transport**, a
genuine bidirectional WebSocket documented at
https://docs.layercode.com/api-reference/frontend-ws-api.
Unlike one-way HTTP SSE, this is a true full-duplex WebSocket. The browser
opens the connection at
`wss://api.layercode.com/v1/agents/web/websocket?client_session_key=...`
using a short-lived `client_session_key` obtained from the REST endpoint
`POST /v1/agents/web/authorize_session` (modeled in
`openapi/layercode-openapi.yml`).
Over the socket the client streams base64-encoded 16-bit PCM microphone
audio (8000 Hz, mono) to Layercode, and Layercode streams back synthesized
speech (base64 16-bit PCM, 16000 Hz, mono), interim and final transcripts,
streamed assistant text, and structured data, organized into user and
assistant turns identified by `turn_id`.
The companion webhook surface - where Layercode POSTs transcript events to
your backend and your backend streams response.tts / response.data /
response.end events back as Server-Sent Events - is documented at
https://docs.layercode.com/api-reference/webhook-sse-api and summarized in
`info.x-webhook-notes` below; it is a separate HTTP+SSE channel and is not
modeled as WebSocket here.
contact:
name: API Evangelist
email: kin@apievangelist.com
url: https://apievangelist.com
license:
name: API documentation - Layercode Terms
url: https://layercode.com/terms
x-transport-notes:
transport: WebSocket
protocol: wss
direction: bidirectional (full-duplex)
url: 'wss://api.layercode.com/v1/agents/web/websocket'
authorizedBy: 'client_session_key query parameter from POST /v1/agents/web/authorize_session'
clientAudio: base64 16-bit PCM, 8000 Hz, mono
serverAudio: base64 16-bit PCM, 16000 Hz, mono
source: https://docs.layercode.com/api-reference/frontend-ws-api
x-webhook-notes:
transport: HTTP Server-Sent Events (SSE)
direction: 'Layercode POSTs JSON events to your backend webhook; backend streams SSE back'
requestEvents: [session.start, message, data, session.update, session.end]
responseEvents: [response.tts, response.data, response.end, response.hangup]
signatureHeader: layercode-signature
source: https://docs.layercode.com/api-reference/webhook-sse-api
defaultContentType: application/json
servers:
layercode:
url: api.layercode.com/v1/agents/web/websocket
protocol: wss
description: |
Layercode realtime voice WebSocket. The browser connects with a
short-lived client_session_key query parameter. The connection is
full-duplex: the client publishes microphone audio and control messages,
and the server publishes audio, transcripts, text, and data events.
channels:
/v1/agents/web/websocket:
description: |
Realtime voice channel. Opened by the browser with
`?client_session_key=...`. Both directions exchange JSON text frames; all
audio payloads are carried as base64 strings inside JSON messages.
bindings:
ws:
query:
type: object
properties:
client_session_key:
type: string
description: Short-lived session key from authorize_session.
required:
- client_session_key
publish:
operationId: clientToServer
summary: Messages the client sends to Layercode.
message:
oneOf:
- $ref: '#/components/messages/ClientReady'
- $ref: '#/components/messages/ClientAudio'
- $ref: '#/components/messages/TriggerTurnStart'
- $ref: '#/components/messages/TriggerTurnEnd'
- $ref: '#/components/messages/TriggerAudioReplayFinished'
- $ref: '#/components/messages/ClientResponseText'
- $ref: '#/components/messages/ClientResponseData'
subscribe:
operationId: serverToClient
summary: Messages Layercode sends to the client.
message:
oneOf:
- $ref: '#/components/messages/TurnStart'
- $ref: '#/components/messages/ResponseAudio'
- $ref: '#/components/messages/ResponseTextDelta'
- $ref: '#/components/messages/ResponseText'
- $ref: '#/components/messages/UserTranscriptInterimDelta'
- $ref: '#/components/messages/UserTranscriptDelta'
- $ref: '#/components/messages/UserTranscript'
- $ref: '#/components/messages/ResponseData'
components:
messages:
ClientReady:
name: client.ready
title: Client ready
summary: Signals the client is connected and ready to stream.
payload:
type: object
properties:
type:
type: string
const: client.ready
ClientAudio:
name: client.audio
title: Client audio chunk
summary: A chunk of microphone audio from the browser.
payload:
type: object
properties:
type:
type: string
const: client.audio
content:
type: string
description: Base64-encoded 16-bit PCM audio, 8000 Hz, mono.
TriggerTurnStart:
name: trigger.turn.start
title: Turn start trigger (push-to-talk)
payload:
type: object
properties:
type:
type: string
const: trigger.turn.start
role:
type: string
const: user
TriggerTurnEnd:
name: trigger.turn.end
title: Turn end trigger (push-to-talk)
payload:
type: object
properties:
type:
type: string
const: trigger.turn.end
role:
type: string
const: user
TriggerAudioReplayFinished:
name: trigger.response.audio.replay_finished
title: Audio replay finished
summary: Client finished playing back a response audio turn.
payload:
type: object
properties:
type:
type: string
const: trigger.response.audio.replay_finished
reason:
type: string
turn_id:
type: string
format: uuid
ClientResponseText:
name: client.response.text
title: Client text message
summary: A typed text message from the user.
payload:
type: object
properties:
type:
type: string
const: client.response.text
content:
type: string
ClientResponseData:
name: client.response.data
title: Client structured data
summary: Arbitrary structured JSON emitted by the client UI.
payload:
type: object
properties:
type:
type: string
const: client.response.data
data:
type: object
additionalProperties: true
TurnStart:
name: turn.start
title: Turn start
payload:
type: object
properties:
type:
type: string
const: turn.start
role:
type: string
enum:
- user
- assistant
turn_id:
type: string
format: uuid
ResponseAudio:
name: response.audio
title: Response audio chunk
summary: Synthesized speech audio from Layercode.
payload:
type: object
properties:
type:
type: string
const: response.audio
content:
type: string
description: Base64-encoded 16-bit PCM audio, 16000 Hz, mono.
delta_id:
type: string
format: uuid
turn_id:
type: string
format: uuid
ResponseTextDelta:
name: response.text.delta
title: Response text delta
payload:
type: object
properties:
type:
type: string
const: response.text.delta
content:
type: string
turn_id:
type: string
format: uuid
ResponseText:
name: response.text
title: Response text (complete)
payload:
type: object
properties:
type:
type: string
const: response.text
content:
type: string
turn_id:
type: string
format: uuid
UserTranscriptInterimDelta:
name: user.transcript.interim_delta
title: Interim transcript delta
payload:
type: object
properties:
type:
type: string
const: user.transcript.interim_delta
content:
type: string
turn_id:
type: string
format: uuid
UserTranscriptDelta:
name: user.transcript.delta
title: Final transcript delta
payload:
type: object
properties:
type:
type: string
const: user.transcript.delta
content:
type: string
turn_id:
type: string
format: uuid
UserTranscript:
name: user.transcript
title: Complete turn transcript
payload:
type: object
properties:
type:
type: string
const: user.transcript
content:
type: string
turn_id:
type: string
format: uuid
ResponseData:
name: response.data
title: Response structured data
summary: Structured JSON pushed to the client without audio.
payload:
type: object
properties:
type:
type: string
const: response.data
content:
type: object
additionalProperties: true
turn_id:
type: string
format: uuid