LIKU Socket

WebSocket API Integration Guide

Overview

This document provides detailed information about integrating with our real-time voice chat WebSocket API. The API enables real-time bidirectional communication for voice chat functionality with AI assistants.

Authentication

Authentication is handled via a token-based system. The token is obtained through the Liku authentication API.

Authentication Endpoint

POST https://torooc-liku-api.med2lab.com/api/liku/authentication/

Request Body:

{
  "email": "[email protected]",
  "password": "user_password"
}

Response:

The token_key should be stored and used for subsequent API calls.

Connection Details

WebSocket Endpoint

Sequence Diagram

The following sequence diagram illustrates the communication flow between the client and server:

Sequence Description

  1. Authentication

    • Client sends authentication request to the Liku API

    • Server validates credentials and returns a token_key

  2. Connection Initialization

    • Client requests connection data using the token

    • Server generates and returns encoded connection data

  3. WebSocket Connection

    • Client establishes WebSocket connection with the server

    • Client sends connection data to the server

    • Server confirms connection is established

  4. Conversation Flow

    • Client sends audio data to the server

    • Server processes and returns user transcript

    • Server sends assistant audio to client

    • Server sends assistant transcript to client

Connection Process

  1. Authentication First, authenticate to obtain a token:

  2. Initialize Connection Data Make a GET request to obtain the connection initialization data:

    Query Parameters:

    • token (required): Your API authentication token

    • topic_id (required): Topic ID for the conversation

    • face_id (optional): Face ID for the avatar

    • liku_id (optional): Liku ID for the assistant

    • language (optional): Language code (e.g., "ko" for Korean, "en" for English)

    Example:

  3. Establish WebSocket Connection Use the obtained connection data to establish the WebSocket connection:

  4. Send Connection Data Once connected, send the connection data as the first message:

Message Types

Client to Server

  1. Connection Data

    • Format: JSON string

    • Sent as the first message after connection is established

    • Contains authentication and configuration information

  2. Audio Data

    • Format: Binary audio data (16-bit PCM, 16kHz sample rate)

    • Send as binary WebSocket messages

Server to Client

  1. Text Messages (JSON format)

  2. Audio Data

    • Format: Binary audio data (16-bit PCM)

    • Received as binary WebSocket messages

Audio Processing

The API handles audio processing with the following parameters:

  • Sample Rate: 16kHz (input), 24kHz (output)

  • Silence Duration: 700ms (for turn detection)

  • Audio Format: 16-bit PCM

Saving Transcripts

To save conversation transcripts to the server:

Headers:

Request Body:

Complete Implementation Example

Error Handling

WebSocket close codes:

  • 1000: Normal closure

  • 4000: Invalid connection data

  • 1005: No status code present

Audio Requirements

  • Input Audio Format: 16-bit PCM

  • Sample Rate: 16kHz

  • Channels: Mono

  • Chunk Size: Recommended 4096 bytes

Best Practices

  1. Connection Management

    • Implement reconnection logic with exponential backoff

    • Handle connection timeouts

    • Clean up resources when connection closes

  2. Audio Processing

    • Implement proper audio preprocessing (noise reduction, gain control)

    • Handle silence detection

    • Buffer audio data appropriately

  3. Error Handling

    • Implement proper error handling for all WebSocket events

    • Log errors for debugging

    • Provide user feedback for connection issues

  4. Security

    • Always use secure WebSocket connections (WSS)

    • Never expose tokens in client-side code

    • Implement proper token refresh mechanisms

Support

For additional support or questions, please contact our support team at [email protected].

Last updated