API Architecture

Trata’s API architecture is divided into two main categories:

Control Plane APIs

• Configuration-focused APIs
• Not invoked during active conversations
• Used for system setup and management

Data Plane APIs

• Runtime APIs used during conversation flows
• Handles real-time communication
• Manages connections and WebSocket interactions

Conversation Protocol

Trata uses WebSockets for real-time communication with user-facing endpoints (Telephony providers and Frontend UI widgets).

Message Stream Schema

After opening the websocket connection, the server expects and sends messages in the following schema:

{
    "type": "object",
    "title": "MessageStream",
    "required": [
        "command",
        "payloadType",
        "payload"
    ],
    "properties": {
        "command": {
            "type": "string",
            "description": "The type of message stream being sent or received, check the table below for more details of the command types",
            "enum": [
                "CLIENT_TO_SERVER_SYNC",
                "SERVER_TO_CLIENT_SYNC",
                "END_OF_TURN",
                "STOP",
                "ABORT_AUDIO",
                "UPDATE_MESSAGE_STATUS"
            ]
        },
        "payloadType": {
            "type": "string",
            "description": "The type of payload being sent or received. Either Audio in bytes or text string, below table contains more details on the audio encoding format requirements",
            "enum": [
                "AUDIO",
                "TEXT"
            ]
        },
        "payload": {
            "type": "object",
            "description": "content of the payload, either audio bytes or text string"
        },
        "user_dialog_id": {
            "type": "string",
            "nullable": true,
            "description": "unique identifier for each dialog in the conversation. This dialog id is generated by the server and client can send a status update to server on whether the dialog is completely played or not at the client side"
        }
    }
}

Command Types

Command	Description
CLIENT_TO_SERVER_SYNC	Clients uses this command to send audio bytes received from microphone or text to server
SERVER_TO_CLIENT_SYNC	Server uses this command to send audio bytes to be played to the user or text to be displayed to the users terminal
END_OF_TURN	Server sends this command to indicate that the response for a dialog request is completed
STOP	If client wants to stop the conversation and close the websocket connection, it can send this command
ABORT_AUDIO	When server detects that the user has interrupted the conversation, it will send this command to client so that client can stop playing any buffered audio and listen to the user input
UPDATE_MESSAGE_STATUS	Client can send this message to update the server that audio bytes for a particular dialog has been played

Payload Types

Type	Description	Format
AUDIO	Audio data payload	For BROWSER connections: PCM audio with FLOAT32 encoding, 44.1kHz sample rate, 32-bit depth, and 128-sample chunks. For TWILIO/PLIVO connections: Format is automatically handled by Trata
TEXT	Text data payload	Text string