Chat API

The Chat API allows you to send messages to your AI assistant and receive responses programmatically. Core API

Endpoints Overview

Send Message

POST

Send a message and receive a response.

Stream Response

POST SSE

Real-time streaming responses.

Get History

GET

Retrieve conversation messages.

List Conversations

GET

Paginated conversation list.

Send a Message Stable

POST /chat/{botId}/message

Send a message to your AI assistant and receive a response.

Request

{
  "message": "What are your business hours?",
  "conversationId": "conv_123456",  // Optional - omit to start new conversation
  "metadata": {                      // Optional - custom data
    "userId": "user_789",
    "source": "mobile_app"
  }
}

Response

{
  "success": true,
  "data": {
    "response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
    "conversationId": "conv_123456",
    "messageId": "msg_789012"
  }
}

Parameters

Parameter	Type	Required	Description
message	string	Yes	The user’s message
conversationId	string	No	Continue existing conversation
metadata	object	No	Custom data to attach

Conversation Continuity

Include the conversationId from previous responses to maintain context across messages. This enables multi-turn conversations where the assistant remembers earlier messages.

Streaming Responses Stable SSE

POST /chat/{botId}/stream

For real-time responses, use the streaming endpoint with Server-Sent Events (SSE):

JavaScript

const response = await fetch(`https://api.mygptassistants.com/api/v1/chat/${botId}/stream`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ message: 'Tell me a story' }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  // Process streamed chunks
  console.log(chunk);
}

Python

import requests

response = requests.post(
    f'https://api.mygptassistants.com/api/v1/chat/{bot_id}/stream',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json',
    },
    json={'message': 'Tell me a story'},
    stream=True
)

for chunk in response.iter_content(chunk_size=None, decode_unicode=True):
    print(chunk, end='', flush=True)

Better UX with Streaming

Streaming provides a better user experience for longer responses. Users see the response being generated in real-time rather than waiting for the complete answer.

Get Conversation History Stable

GET /chat/{botId}/conversations/{conversationId}

Retrieve the full message history for a conversation.

Response

{
  "success": true,
  "data": {
    "conversationId": "conv_123456",
    "messages": [
      {
        "id": "msg_001",
        "role": "user",
        "content": "Hello",
        "timestamp": "2024-01-15T10:00:00Z"
      },
      {
        "id": "msg_002",
        "role": "assistant",
        "content": "Hi! How can I help you today?",
        "timestamp": "2024-01-15T10:00:01Z"
      }
    ],
    "metadata": {
      "createdAt": "2024-01-15T10:00:00Z",
      "messageCount": 2
    }
  }
}

Message Object

Field	Type	Description
id	string	Unique message ID
role	string	user or assistant
content	string	Message text
timestamp	ISO date	When message was sent

List Conversations Stable

GET /chat/{botId}/conversations

List all conversations for a bot with pagination.

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	20	Items per page (max 100)
since	ISO date	-	Filter conversations after this date

Response

{
  "success": true,
  "data": {
    "conversations": [
      {
        "id": "conv_123456",
        "preview": "What are your business hours?",
        "messageCount": 5,
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "hasMore": true
    }
  }
}

Error Handling

Code	Description	Solution
400	Invalid request body	Check request format
401	Invalid or missing API key	Verify authentication
404	Bot or conversation not found	Check IDs
429	Rate limit exceeded	Implement backoff
500	Server error	Retry with backoff

Retry Logic

Implement exponential backoff for 429 and 5xx errors. Start with a 1-second delay and double it with each retry, up to a maximum of 32 seconds.

Quick Integration Guide

1. Get your API key

   Generate a key in Settings → API Keys.

2. Send your first message

   Use the /chat/{botId}/message endpoint.

3. Store the conversation ID

   Save conversationId from the response.

4. Continue the conversation

   Include conversationId in subsequent requests.

5. Add streaming (optional)

   Use /chat/{botId}/stream for real-time UX.

API Reference Summary

Endpoint	Method	Description
/chat/{botId}/message	POST	Send message, get response
/chat/{botId}/stream	POST	Stream response (SSE)
/chat/{botId}/conversations/{id}	GET	Get conversation history
/chat/{botId}/conversations	GET	List all conversations

Related Topics

Authentication API key setup and security

Webhooks Real-time event notifications

Conversations Managing conversations in dashboard

API Overview API basics and rate limits