Chat Overview

{"event": "chat_metadata", "data": {"id": "chat_abc123", "user_message_id": "msg_001"}}
{"event": "processing", "data": {"status": "thinking"}}
{"event": "processing", "data": {"status": "analyzing"}}
{"event": "visualization", "data": {"id": "ab12xy3456", "type": "chart", "chart_type": "bar", "title": "Orders by Region", "data": {"values": [{"label": "North", "value": 412}, {"label": "South", "value": 289}, {"label": "East", "value": 531}], "x_axis_label": "Region", "y_axis_label": "Orders"}}}
{"event": "text_delta", "data": {"content": "There were 1,232 orders "}}
{"event": "text_delta", "data": {"content": "placed last month, with the East "}}
{"event": "text_delta", "data": {"content": "region leading at 531."}}
{"event": "message", "data": {"content": "There were 1,232 orders placed last month, with the East region leading at 531.", "id": "msg_005"}}

interface ChatEvent {
  event: "chat_metadata" | "processing" | "visualization" | "text_delta" | "message" | "error";
  data: any;
}

class TrellisChat {
  private ws: WebSocket;
  private onEvent: (event: ChatEvent) => void;

  constructor(token: string, onEvent: (event: ChatEvent) => void) {
    this.onEvent = onEvent;
    this.ws = new WebSocket("wss://api.trellis.sh/v1/chats/ws");

    this.ws.onopen = () => {
      // Browser WebSocket cannot set headers — authenticate via first frame.
      this.ws.send(JSON.stringify({ action: "authenticate", token }));
    };

    this.ws.onmessage = (msg) => {
      const event = JSON.parse(msg.data);
      this.onEvent(event);
    };
  }

  sendMessage(message: string, chatId: string, integrationId: string) {
    // chat_id is required — obtain one from POST /v1/chats/create.
    this.ws.send(JSON.stringify({
      action: "send_message",
      message,
      chat_id: chatId,
      integration_id: integrationId,
    }));
  }

  close() {
    this.ws.close();
  }
}

// Usage
let streamingBuffer = "";
const chat = new TrellisChat("your_token", (event) => {
  switch (event.event) {
    case "chat_metadata":
      console.log("New chat:", event.data.id);
      break;
    case "processing":
      showLoadingIndicator();
      break;
    case "visualization":
      if (event.data.type === "table") {
        renderTable(event.data.headers, event.data.rows);
      } else if (event.data.type === "chart") {
        renderChart(event.data.chart_type, event.data.title, event.data.data);
      }
      break;
    case "text_delta":
      streamingBuffer += event.data.content;
      renderStreamingMessage(streamingBuffer);
      hideLoadingIndicator();
      break;
    case "message":
      displayMessage(event.data.content, event.data.id);
      streamingBuffer = "";
      break;
    case "error":
      showError(event.data.error);
      break;
  }
});

chat.sendMessage("Show me top 10 customers", "chat_abc123", "integration_id");

import requests
import json

def send_chat_message(message: str, integration_id: str, token: str):
    """Send a chat message and stream the response via SSE."""
    
    response = requests.post(
        "https://api.trellis.sh/v1/chats",
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "Accept": "text/event-stream",
        },
        json={
            "message": message,
            "integration_id": integration_id,
        },
        stream=True
    )
    
    current_event = None
    streaming_buffer = ""

    for line in response.iter_lines(decode_unicode=True):
        if not line:
            continue
            
        if line.startswith("event: "):
            current_event = line[7:]
        elif line.startswith("data: ") and current_event:
            data = json.loads(line[6:])

            if current_event == "visualization":
                if data["type"] == "table":
                    handle_table(data["headers"], data["rows"])
                elif data["type"] == "chart":
                    handle_chart(data["chart_type"], data.get("title"), data["data"])
            elif current_event == "text_delta":
                # Append the incremental chunk
                streaming_buffer += data["content"]
            elif current_event == "message":
                # Replace buffer with authoritative full content
                print(data["content"])
                streaming_buffer = ""

            yield {"type": current_event, "data": data}
            current_event = None


# Usage
for event in send_chat_message("Show me revenue by month", "integration_id", "token"):
    print(f"{event['type']}: {event['data']}")

import asyncio
import json
import websockets

async def chat_with_websocket(token: str, chat_id: str, integration_id: str, messages: list[str]):
    """Send multiple messages over a persistent WebSocket connection."""

    uri = "wss://api.trellis.sh/v1/chats/ws"

    async with websockets.connect(
        uri,
        additional_headers=[("Authorization", f"Bearer {token}")],
    ) as ws:
        # Wait for authentication confirmation
        auth_response = await ws.recv()
        auth_data = json.loads(auth_response)

        if auth_data["event"] != "authenticated":
            raise Exception("Authentication failed")

        for message in messages:
            # Send message — chat_id is required
            await ws.send(json.dumps({
                "action": "send_message",
                "message": message,
                "chat_id": chat_id,
                "integration_id": integration_id,
            }))

            # Receive events until we get the final message
            streaming_buffer = ""
            while True:
                response = await ws.recv()
                event = json.loads(response)

                if event["event"] == "visualization":
                    data = event["data"]
                    if data["type"] == "table":
                        handle_table(data["headers"], data["rows"])
                    elif data["type"] == "chart":
                        handle_chart(data["chart_type"], data.get("title"), data["data"])
                elif event["event"] == "text_delta":
                    # Append the incremental chunk
                    streaming_buffer += event["data"]["content"]
                elif event["event"] == "message":
                    # Authoritative full content
                    print(event["data"]["content"])
                    break
                elif event["event"] == "error":
                    print("Error:", event["data"]["error"])
                    break


# Usage — obtain chat_id first via POST /v1/chats/create
asyncio.run(chat_with_websocket(
    "your_token",
    "chat_abc123",
    "integration_id",
    ["How many orders last month?", "Break it down by region"]
))