WebSocket 연결 설정

클라이언트와 WebRTC Gateway는 /sohri WebSocket 하나로 제어 이벤트와 오디오를 교환합니다. 이 문서는 서버 내부 환경변수가 아니라 연결 시 합의하는 외부 계약을 설명합니다.

연결

wss://<socket-backend>/sohri?minSpeech=0.3&endSilence=1.2&epdTimeout=7.0&ttsSampleRate=48000&ttsStream=v1

인증 정보는 다음 우선순위로 읽습니다.

1. Authorization: Bearer <credential>
2. WebSocket subprotocol의 sohri.apikey 또는 sohri.token
3. query parameter

credential은 워크스페이스 API key(sr_live_, sr_test_) 또는 App Backend가 발급한 Ed25519 client-secret JWT입니다.

핸드셰이크 query

이름	별칭	의미
minSpeech	minspeech, min_speech	EPD가 발화 후보를 인정할 최소 음성 길이
endSilence	endsilence, end_silence	발화 종료로 판단할 무음 길이
epdTimeout	timeout, epd_timeout	EPD activity 최대 대기 시간
continuousAudio	continuous_audio	TIMEOUT 뒤 다음 PCM에서 EPD 연결을 이어갈지 여부
ttsSampleRate	tts_sample_rate	16000, 24000, 48000 중 요청 sample rate
ttsStream	tts_stream	v1이면 TTS 스트리밍 협상 요청

최종 EPD 설정은 minSpeech <= epdTimeout이어야 합니다. 협상된 TTS 값은 connection_established 응답에서 확인합니다.

연결 직후 응답

서버는 세션 생성과 인증이 끝나면 connection_established를 보냅니다.

{
  "type": "connection_established",
  "sessionId": "websocket-session-id",
  "dialogId": "dialog-uuid",
  "ttsStream": "v1"
}

ttsStream은 실제 협상에 성공한 경우에만 포함됩니다.

대화 경로 선택

첫 Binary PCM 전에 conversation_session_update를 보내면 대화 경로를 명시할 수 있습니다.

{
  "type": "conversation_session_update",
  "conversationEngine": "sohri"
}

• sohri: EPD → Graph Builder(DM) → TTS 기본 경로
• openai_realtime: Realtime provider 경로

서버는 준비가 끝난 뒤 conversation_session_updated를 반환합니다. 설정 없이 PCM이 먼저 오면 sohri가 확정되며, 세션 도중 경로를 변경할 수 없습니다.

런타임 설정 메시지

epd_config_update는 다음 EPD 연결에 적용할 발화 설정을 변경합니다. 핸드셰이크 query와 달리 범위 밖 값은 보정하지 않고 오류로 응답합니다.

세션·시나리오·TTS 설정 메시지와 전체 event 목록은 WebSocket 이벤트를 참고하세요.