Send Message

Endpoint

POST /messages
Base URL: https://api.example-ai.com/v1

Description

Send a message into an existing or new conversation.
This endpoint is used to deliver user messages to the AI or to other participants, and optionally trigger AI responses depending on your configuration.

Authentication

Authorization: Bearer sk_test_51_fakeapikey123456

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer <token>
Content-Type	string	Yes	application/json

Request Parameters

Body Parameters

Name	Type	Required	Description
conversation_id	string	No	Existing conversation ID. If omitted, a new conversation may be created.
sender_id	string	Yes	ID of the sender, e.g. usr_82hd92.
sender_type	string	Yes	user, agent, or system.
text	string	Yes	Message body text.
reply_to_message_id	string	No	Optional message ID this message is replying to.
metadata	object	No	Free-form metadata (tags, channel info, etc.).
auto_reply	boolean	No	If true, triggers an AI reply for this message. Default: true.

Example Request

curl

curl -X POST "https://api.example-ai.com/v1/messages" \
  -H "Authorization: Bearer sk_test_51_fakeapikey123456" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "con_9s2kd81",
    "sender_id": "usr_82hd92",
    "sender_type": "user",
    "text": "Can you summarize my last 5 calls?",
    "metadata": {
      "channel": "web",
      "locale": "en-US"
    },
    "auto_reply": true
  }'

Example Response

{
  "status": "success",
  "message": "Message sent successfully.",
  "data": {
    "conversation_id": "con_9s2kd81",
    "message": {
      "id": "msg_45kd01",
      "sender_id": "usr_82hd92",
      "sender_type": "user",
      "text": "Can you summarize my last 5 calls?",
      "metadata": {
        "channel": "web",
        "locale": "en-US"
      },
      "created_at": "2026-03-15T14:22:11Z"
    },
    "auto_reply_enqueued": true
  }
}

Error Responses

400 Bad Request

{
  "status": "error",
  "message": "Field 'text' is required.",
  "data": null
}

401 Unauthorized

{
  "status": "error",
  "message": "Invalid or expired token.",
  "data": null
}

404 Not Found

{
  "status": "error",
  "message": "Conversation not found: con_9s2kd81.",
  "data": null
}

500 Server Error

{
  "status": "error",
  "message": "Failed to enqueue message. Please retry.",
  "data": null
}

Code Examples

curl

curl -X POST "https://api.example-ai.com/v1/messages" \
  -H "Authorization: Bearer sk_test_51_fakeapikey123456" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": "usr_82hd92",
    "sender_type": "user",
    "text": "Hello from curl!"
  }'

JavaScript (fetch)

const payload = {
  conversation_id: 'con_9s2kd81',
  sender_id: 'usr_82hd92',
  sender_type: 'user',
  text: 'Hello from fetch!',
  auto_reply: true
};

const response = await fetch('https://api.example-ai.com/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_51_fakeapikey123456',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

const result = await response.json();
console.log(result.data);

TypeScript (axios)

import axios, { AxiosResponse } from 'axios';

interface SendMessagePayload {
  conversation_id?: string;
  sender_id: string;
  sender_type: 'user' | 'agent' | 'system';
  text: string;
  reply_to_message_id?: string;
  metadata?: Record<string, unknown>;
  auto_reply?: boolean;
}

interface SendMessageResponse {
  status: 'success' | 'error';
  message: string;
  data: {
    conversation_id: string;
    message: {
      id: string;
      sender_id: string;
      sender_type: string;
      text: string;
      metadata?: Record<string, unknown>;
      created_at: string;
    };
    auto_reply_enqueued: boolean;
  } | null;
}

const payload: SendMessagePayload = {
  sender_id: 'usr_82hd92',
  sender_type: 'user',
  text: 'Hello from axios + TypeScript!'
};

const res: AxiosResponse<SendMessageResponse> = await axios.post(
  'https://api.example-ai.com/v1/messages',
  payload,
  {
    headers: {
      Authorization: 'Bearer sk_test_51_fakeapikey123456'
    }
  }
);

console.log(res.data.data?.message.id);

Notes

• If conversation_id is omitted, a new conversation may be automatically created depending on your workspace configuration.
• AI auto-replies are typically delivered via webhooks or a separate “get events” API.