API Reference

The Tchao REST API gives you programmatic access to your conversations, websites, and analytics. Use it to build integrations, automate workflows, or connect Tchao to your existing tools.

Base URL

All API requests use the following base URL:

https://tchao.app/api/v1

Authentication

Authenticate by including your API key in the Authorization header as a Bearer token.

Authorization: Bearer tc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys use the tc_ prefix and are tied to your organization. All requests are scoped to the organization that owns the key.

Getting an API Key

1. Go to your organization dashboard
2. Navigate to Settings > Developer
3. Click Create API Key
4. Give it a descriptive name (e.g., "Zapier Integration")
5. Copy the key immediately -- it is only shown once

Tool Discovery

The API uses a tool-based architecture. List all available tools with a GET request:

curl https://tchao.app/api/v1/tools \
  -H "Authorization: Bearer tc_your_api_key"

Response:

{
  "success": true,
  "data": {
    "tools": [
      {
        "name": "list_conversations",
        "description": "List conversations for the organization...",
        "category": "conversation",
        "inputSchema": { ... }
      },
      {
        "name": "get_conversation",
        "description": "Get a single conversation with all its messages...",
        "category": "conversation",
        "inputSchema": { ... }
      }
    ]
  }
}

Each tool includes its name, description, category, and a JSON Schema describing its expected input.

Executing Tools

Call any tool by sending a POST request with the tool name in the URL and the input as a JSON body:

POST /api/v1/tools/{toolName}

Example -- list open conversations:

curl -X POST https://tchao.app/api/v1/tools/list_conversations \
  -H "Authorization: Bearer tc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "OPEN", "limit": 10}'

Success response:

{
  "success": true,
  "data": {
    "conversations": [
      {
        "id": "abc123",
        "visitorName": "John Doe",
        "visitorEmail": "john@example.com",
        "status": "OPEN",
        "createdAt": 1706000000000,
        "lastMessage": {
          "content": "I have a question about pricing",
          "senderType": "VISITOR",
          "createdAt": 1706000060000
        }
      }
    ],
    "nextCursor": null
  }
}

Error Handling

All errors follow a consistent format:

{
  "success": false,
  "error": "Description of what went wrong",
  "code": "ERROR_CODE"
}

Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing or invalid API key
NOT_FOUND	404	Tool or resource not found
VALIDATION_ERROR	400	Invalid request body or parameters
RATE_LIMITED	429	Too many requests, slow down
INTERNAL_ERROR	500	Unexpected server error

Code Examples

Node.js

const API_KEY = "tc_your_api_key";
const BASE_URL = "https://tchao.app/api/v1";

async function callTool(toolName: string, input: Record<string, unknown> = {}) {
  const response = await fetch(`${BASE_URL}/tools/${toolName}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(input),
  });

  return response.json();
}

// List open conversations
const result = await callTool("list_conversations", { status: "OPEN" });
console.log(result.data.conversations);

Python

import requests

API_KEY = "tc_your_api_key"
BASE_URL = "https://tchao.app/api/v1"

def call_tool(tool_name, input_data=None):
    response = requests.post(
        f"{BASE_URL}/tools/{tool_name}",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=input_data or {},
    )
    return response.json()

# List open conversations
result = call_tool("list_conversations", {"status": "OPEN"})
print(result["data"]["conversations"])

cURL

# List all tools
curl https://tchao.app/api/v1/tools \
  -H "Authorization: Bearer tc_your_api_key"

# Get conversation stats
curl -X POST https://tchao.app/api/v1/tools/get_conversation_stats \
  -H "Authorization: Bearer tc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'

# Send a message
curl -X POST https://tchao.app/api/v1/tools/send_message \
  -H "Authorization: Bearer tc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"conversationId": "abc123", "content": "Thanks for reaching out!"}'

Available Tools

Tools are organized by category:

Category	Tools
Conversation	list_conversations, get_conversation, send_message, close_conversation
Website	list_websites, get_website
Analytics	get_conversation_stats

See the individual tool reference pages for full parameter details and example responses.

Next Steps

• MCP Integration -- Connect Tchao to AI assistants
• Conversation Tools -- Manage conversations via API
• Website Tools -- Access website configuration
• Analytics Tools -- Get conversation statistics