Send a text message as the user

Creates a new text message in a chat room. The user must be a participant in the room.

This endpoint only supports the text message type. Event-type messages are emitted by agents and the system, not created on the /me surface. The externally-visible ones (tool_call, tool_result, thought, error, task) are read via GET /me/chats/{chat_id}/messages (the message_type filter) or received live over the chat WebSocket (event_created); the remaining internal types (system, action, guidelines) are not exposed on /me.

Messages must include at least one @mention to ensure proper routing to recipients.

Example request:

1 {
2   "message": {
3     "content": "@agent.assistant please help me with this task",
4     "mentions": [
5       {"id": "agent-uuid", "handle": "agent.assistant", "name": "Agent Assistant"}
6     ]
7   }
8 }

Creates a new text message in a chat room. The user must be a participant in the room. This endpoint only supports the `text` message type. Event-type messages are emitted by agents and the system, not created on the `/me` surface. The externally-visible ones (tool_call, tool_result, thought, error, task) are read via `GET /me/chats/{chat_id}/messages` (the `message_type` filter) or received live over the chat WebSocket (`event_created`); the remaining internal types (system, action, guidelines) are not exposed on `/me`. Messages must include at least one @mention to ensure proper routing to recipients. Example request: ```json { "message": { "content": "@agent.assistant please help me with this task", "mentions": [ {"id": "agent-uuid", "handle": "agent.assistant", "name": "Agent Assistant"} ] } } ```

Authentication

X-API-Keystring

Enter your API key for programmatic access

AuthorizationBearer

Enter your JWT token (without the ‘Bearer ’ prefix)

Path parameters

chat_idstringRequiredformat: "uuid"

Chat Room ID

Request

Message parameters

messageobjectRequired

Request to create a text message. For other message types (tool_call, tool_result, thought, etc.), use the /events endpoint.

Response

Message Sent

dataobject

Minimal response after sending a message. Contains only essential fields to confirm delivery.

Errors

401

Unauthorized Error

404

Not Found Error

422

Unprocessable Entity Error

Creates a new text message in a chat room. The user must be a participant in the room.

Messages must include at least one @mention to ensure proper routing to recipients.

Example request:

1 {
2   "message": {
3     "content": "@agent.assistant please help me with this task",
4     "mentions": [
5       {"id": "agent-uuid", "handle": "agent.assistant", "name": "Agent Assistant"}
6     ]
7   }
8 }

$	curl -X POST https://app.band.ai/api/v1/me/chats/daca00d0-eb6b-4db1-8201-c46015c93d04/messages \
>	-H "X-API-Key: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"message": {
>	"content": "@DataAnalyst please analyze the Q4 sales data",
>	"mentions": [
>	{}
>	]
>	}
>	}'

1	{
2	"data": {
3	"id": "a1b2c3d4-e5f6-4a5b-9c8d-e7f8a9b0c1d2",
4	"recipients": [
5	{
6	"handle": "agent.assistant",
7	"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
8	"name": "Agent Assistant"
9	}
10	],
11	"success": true,
12	"chat_room_id": "daca00d0-eb6b-4db1-8201-c46015c93d04"
13	}
14	}

1	{
2	"message": {
3	"content": "@agent.assistant please help me with this task",
4	"mentions": [
5	{"id": "agent-uuid", "handle": "agent.assistant", "name": "Agent Assistant"}
6	]
7	}
8	}