Skip to content

Chat API

Send messages to AI agents and manage conversations programmatically.

Send Chat Message

Send a message to an AI agent and receive a response.

Endpoint: POST /chat/{slug}

Parameters

Parameter Type Location Required Description
slug string path Yes The unique identifier (slug) of your AI agent

Request Body

{
  "message": "Your message text here",
  "stream": false,
  "conversationId": "optional-conversation-id"
}
Field Type Required Description
message string Yes The message to send to the AI agent
stream boolean No Enable streaming responses (default: false)
conversationId string No Continue an existing conversation (null for new conversation)

Response

Success (200):

{
  "data": {
    "response": "AI agent's response text",
    "conversationId": "conv_abc123",
    "metadata": {
      "model": "gpt-4",
      "tokens": 150
    }
  },
  "error": null
}

Examples

Basic Chat

curl -X POST "https://PLATFORM-URL-PLACEHOLDER/v1/api/chat/support-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your business hours?",
    "stream": false
  }'

Continue Conversation

curl -X POST "https://PLATFORM-URL-PLACEHOLDER/v1/api/chat/support-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Can you elaborate on that?",
    "stream": false,
    "conversationId": "conv_abc123"
  }'

Streaming Response

curl -X POST "https://PLATFORM-URL-PLACEHOLDER/v1/api/chat/support-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Tell me a long story",
    "stream": true
  }'

Error Responses

400 - Bad Request: 

{
  "data": null,
  "error": {
    "name": "ValidationError",
    "message": "Message field is required",
    "details": {}
  }
}

401 - Unauthorized: 

{
  "data": null,
  "error": {
    "name": "UnauthorizedError",
    "message": "Invalid or missing API token",
    "details": {}
  }
}

404 - Not Found: 

{
  "data": null,
  "error": {
    "name": "NotFoundError",
    "message": "Agent with slug 'support-agent' not found",
    "details": {}
  }
}

Finding Your Agent Slug

The agent slug is the unique identifier for your agent. You can find it in the platform:

  1. Navigate to My Agents
  2. Click on your agent
  3. The slug is shown in the agent settings or URL

Alternatively, slugs are typically the lowercase, hyphenated version of your agent name: - "Customer Support" → customer-support - "Sales Bot" → sales-bot

Conversation Management

New Conversation

To start a new conversation, omit the conversationId field or set it to null:

{
  "message": "Hello",
  "conversationId": null
}

Continue Conversation

To continue an existing conversation, include the conversationId from the previous response:

{
  "message": "Follow-up question",
  "conversationId": "conv_abc123"
}

Streaming Responses

When stream: true is set, the response will be sent as Server-Sent Events (SSE):

curl -X POST "https://PLATFORM-URL-PLACEHOLDER/v1/api/chat/agent-slug" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello", "stream": true}' \
  --no-buffer

SSE Format: 

data: {"chunk": "Hello"}
data: {"chunk": " there!"}
data: {"chunk": " How"}
data: {"chunk": " can"}
data: {"chunk": " I"}
data: {"chunk": " help"}
data: {"chunk": "?"}
data: [DONE]

Best Practices

  1. Store Conversation IDs: Save conversationId values to maintain context across messages
  2. Handle Timeouts: Set appropriate timeouts for long-running conversations
  3. Error Handling: Implement retry logic for transient errors (429, 500)
  4. Rate Limiting: Respect rate limits and implement exponential backoff
  5. Streaming: Use streaming for better UX with long responses