AI in Webex
AI in Webex
BYoVA WebSocket: Troubleshooting and Validation
Use these checks to validate a partner BYoVA WebSocket connector and isolate connection, media, turn-taking, DTMF, and cleanup failures.
anchorOverview
anchorFor field names, required values, and the complete conversation lifecycle, see the BYoVA over WebSocket guide and its published AsyncAPI schemas.
anchorConnection and authentication
anchor| Symptom | Checks |
|---|---|
| WebSocket handshake is rejected | Confirm the endpoint is reachable over wss://, the certificate is valid for its hostname, and the bearer token is present and accepted. |
| The first message is rejected | Confirm SESSION_START is the first application input and that the request uses the expected JSON envelope. |
| Messages are associated with the wrong call | Keep one connection per conversation_id and return the same conversation ID in partner responses and errors. |
| Heartbeat fails | Respond promptly to PING with PONG using the same sequence number. |
anchorAudio and response sequencing
anchor| Symptom | Checks |
|---|---|
| Audio is rejected or sounds wrong | Confirm raw G.711 mu-law/PCMU, 8 kHz, mono audio. Keep the payload Base64-encoded inside JSON and do not add a WAV or RIFF header. |
| Response starts late or sounds choppy | Send each audio fragment as soon as it is generated; do not pace transmission to playback duration. Check the 320-byte minimum and 32 KB maximum. |
| Streamed audio is malformed | Confirm chunk audio contains raw, headerless media bytes and the response follows the published AsyncAPI schema. |
| A reply never completes or repeats | Send PARTIAL only when the request sets allow_partial_responses to true; use CHUNK for streamed audio independently. Then send exactly one FINAL and no more output for that reply. |
anchorVoice and barge-in
anchor- Send
START_OF_INPUTwhen the partner detects caller speech andEND_OF_INPUTwhen its endpointing logic considers the speech complete. - Without barge-in, expect the next caller-audio stream after
FINAL; speech spoken while the prompt plays is not delivered to the partner. - For caller interruption, enable
prompts[].is_barge_in_enabledand report detected speech withSTART_OF_INPUT. - Do not wait for a literal
BARGE_INevent; the WebSocket contract uses the prompt setting and input-boundary events.
anchorDTMF
anchor- Process
dtmf_inputas one ordered collection, not one request per key press. - Confirm
input_modeaccepts DTMF andinput_handling_config.dtmf_configsets the intended length, terminator, and inter-digit timeout. - Check that collection ends on the configured terminator, maximum length, or inter-digit timeout.
- Use
START_OF_DTMFas the Webex-to-partner DTMF event; do not treat it as a partner output event.
anchorErrors and session cleanup
anchorHandle schema-defined errors such as unauthorized, bad_request, unsupported_media, upstream_error, rate_limit, and timeout. Avoid tight retry loops for rate limits and do not replay an already-started conversation unless the platform contract explicitly supports it.
On SESSION_END, transfer, protocol error, or transport failure, release conversation state and close the session. Keep bearer tokens, raw audio, transcripts, and other sensitive content out of error details and routine diagnostic logs.
anchorEnd-to-end checklist
anchor- The authenticated secure WebSocket handshake succeeds.
-
SESSION_STARTinitializes one conversation on one connection. - Caller audio is decoded with the encoding and sample rate supplied by Webex.
- Speech boundaries are reported to Webex.
- Audio fragments follow the current media profile and are sent without artificial pacing.
- For the next caller input,
input_modeis correct andinput_handling_configsupplies any needed DTMF collection settings or speech timers. - Exactly one
FINALcloses each logical reply. - Barge-in and non-barge-in timing match the configured prompt behavior.
- DTMF digits are collected and processed in order.
-
PINGreceives a matchingPONG. - Exit events release state and close the session.