Skip to main content

Connect to Live Call WebSocket Stream

GET 
/ws/v1/liveCalls

WebSocket Endpoint - This endpoint establishes a WebSocket connection for real-time communication during an active call.

Connection Establishment​

This is a WebSocket endpoint, not a standard HTTP GET request. To connect:

  1. Initiate an HTTP GET request to this endpoint with the required conversationToken query parameter
  2. Include the Upgrade: websocket and Connection: Upgrade headers
  3. Include the Authorization: Bearer <token> header for authentication
  4. The server will respond with HTTP 101 Switching Protocols to complete the WebSocket handshake

Message Format​

All messages are JSON objects. Each message must include a type field that acts as a discriminator to identify the message type.

Bidirectional Communication​

Once connected, the WebSocket supports bidirectional message flow:

Client-to-Server Messages​

The client can send the following message types:

  • client:joinCall - Request to transfer the call to user

    • Schema: WebSocketClientJoinCallMessage
    • Required fields: type, id

  • client:endCall - Request to end the call to user

    • Schema: WebSocketClientEndCallMessage
    • Required fields: type, id

See WebSocketClientMessage for the complete union type.

Server-to-Client Messages​

The server will send the following message types:

  • ack - Acknowledgment of a client message

    • Schema: WebSocketClientAck
    • Contains: type, ackId (references the client message id)

  • event:start - Call start event

    • Schema: WebSocketCallStartMessage
    • Contains: type, phone (E.164 format), timestamp (ISO 8601)

  • event:end - Screening phase end event

    • Schema: WebSocketScreeningEndMessage
    • Contains: type, msg (description message)

  • event:callEnd - Call end event

    • Schema: WebSocketCallEndMessage
    • Contains: type, timestamp (ISO 8601)

  • transcript - Real-time transcript update

    • Schema: WebSocketTranscriptMessage
    • Contains: type, msg (transcript text), role (assistant|other|user), offset (optional)

  • error - Error message

    • Schema: WebSocketErrorMessage
    • Contains: type, description (error description)

See WebSocketServerMessage for the complete union type.

Connection Lifecycle​

  1. Client establishes WebSocket connection with conversationToken
  2. Client may send client:joinCall to join the conversation
  3. Server sends events as they occur (call start, screening end, transcripts, call end)
  4. Server acknowledges client messages with ack messages
  5. Client may send client:endCall to request call termination
  6. Connection closes when call ends or on error

Error Handling​

If an error occurs, the server will send an error message with a description. The connection may remain open or close depending on the error severity.

Query Parameters​

    conversationToken stringrequired

    The conversation token obtained from the call log entry's liveConversationToken field. This token is required to authenticate and connect to the live call WebSocket stream.

Header Parameters​

    x-hiya-product-version string

    Product version. The standard "major.minor.patch" format is highly encouraged without any leading characters; "2.1.3" or "3.0.0" for example.

    x-hiya-account-user-id stringrequired

    The identifier of a logged-in user. Same identifier that is used for /users/{user_id}

Responses​

Switching Protocols - The server is switching to the WebSocket protocol. After this response, the connection is upgraded to a WebSocket connection and bidirectional message communication begins.

Headers

  • Upgrade

    string

  • Connection

    string