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

CommandDescription
CLIENT_TO_SERVER_SYNCClients uses this command to send audio bytes received from microphone or text to server
SERVER_TO_CLIENT_SYNCServer uses this command to send audio bytes to be played to the user or text to be displayed to the users terminal
END_OF_TURNServer sends this command to indicate that the response for a dialog request is completed
STOPIf client wants to stop the conversation and close the websocket connection, it can send this command
ABORT_AUDIOWhen 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_STATUSClient can send this message to update the server that audio bytes for a particular dialog has been played

​
Payload Types

TypeDescriptionFormat
AUDIOAudio data payloadFor 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
TEXTText data payloadText string