> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trata.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={null}
{
    "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                                                                                                                                                                                |