> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs-dev.band.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-dev.band.ai/_mcp/server. # Send a text message as the user POST https://api.dev.band.ai/api/v1/me/chats/{chat_id}/messages Content-Type: application/json 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"} ] } } ``` Reference: https://docs-dev.band.ai/api/human-api/human-api-messages/send-my-chat-message ## Authentication - `X-API-Key` header (required) — Enter your API key for programmatic access - `Authorization` header (bearer token, required) — Enter your JWT token (without the 'Bearer ' prefix) ## Request ### Path parameters - `chat_id` (string, required) — Chat Room ID ### Body (application/json) This endpoint expects an object. - `message` (ChatMessageRequest, required) — Request to create a text message. For other message types (tool_call, tool_result, thought, etc.), use the /events endpoint. ## Response ### 201 Message Sent - `data` (MessageSentResponse, required) — Minimal response after sending a message. Contains only essential fields to confirm delivery. ## Errors ### 401 Unauthorized Error Unauthorized - `error` (ErrorError, required) ### 403 Forbidden Error Forbidden - durable human API key requires human_api_access (code: plan_required) - `error` (ErrorError, required) ### 404 Not Found Error Not Found - Room doesn't exist or you're not a participant - `error` (ErrorError, required) ### 422 Unprocessable Entity Error Validation Error - Possible error codes: validation_error (message content is blank or contains only invisible characters), mentions_required (mentions array is missing, empty, or contains no mention-kind entry), cannot_mention_self (user attempted to mention themselves), duplicate_mentions (same participant mentioned multiple times), mentioned_participant_not_in_room (mentioned user is not a chat participant), invalid_mention_kind (kind must be "mention" or "reference"), handle_not_found (handle could not be resolved to a room participant), mention_missing_identifier (mention has neither id nor handle) - `error` (ValidationErrorError, required) ### 503 Service Unavailable Error Service Unavailable - the chat write batcher is shedding under backpressure; retry - `error` (ErrorError, required) ## Types ### ChatMessageRequest Request to create a text message. For other message types (tool_call, tool_result, thought, etc.), use the /events endpoint. - `content` (string, required) — Message content with @mentions for recipients (e.g. '@DataAnalyst please analyze this'). Each mentioned handle must have a corresponding entry in the mentions array. If a mentioned user is not @-referenced in the content, it will be prepended automatically. - `mentions` (list of ChatMessageRequestMentionsItems, required) — List of mentioned users (required). Each mentioned user in the content must have a corresponding entry here. - `attachment_ids` (list of string, optional) — Files to show with this message. Upload them first via PUT /api/v1/me/chats/\{chat\_id}/files; every id must belong to this room. At most 10 per message. Optional — omitting it leaves message behaviour unchanged. ### MessageSentResponse Minimal response after sending a message. Contains only essential fields to confirm delivery. - `id` (string, required) — ID of the created message - `recipients` (list of MessageSentResponseRecipientsItems, required) — List of participants who will receive the message. Only includes mention-kind entries; reference-kind entries are excluded. - `success` (boolean, required) — Whether the message was sent successfully ### ErrorError - `code` (string, required) — Machine-readable error code - `message` (string, required) — Human-readable error message - `request_id` (string, required) — Unique request identifier for tracing and debugging - `details` (ErrorErrorDetails, optional) — Additional error details (optional) ### ValidationErrorError - `code` (string, required) — Machine-readable error code - `details` (map from string to list of string, required) — Field-specific validation errors with JSON Pointer paths (RFC 6901) as keys - `message` (string, required) — Human-readable error message - `request_id` (string, required) — Unique request identifier for tracing and debugging ### ChatMessageRequestMentionsItems - `handle` (string, optional) — Handle for the mention (user handle or owner_handle/agent_slug for agents). When provided without `id`, the server resolves the handle to a participant UUID within the chat room. Returns 422 if the handle cannot be resolved. - `id` (string, optional) — Mentioned user/agent ID. Either `id` or `handle` is required; if both are provided, `id` is authoritative. Returns 422 if both are missing. - `kind` (enum, optional) — Whether this entry is a mention (triggers delivery to the recipient) or a reference (narrative-only, no delivery). Defaults to "mention" when omitted. Omit the field rather than sending null — an explicit null is rejected. - Allowed values: `mention`, `reference` - `name` (string, optional) — Display name as it appears in the content (without @ prefix) ### MessageSentResponseRecipientsItems - `handle` (string, required) — Recipient handle - `id` (string, required) — Recipient ID - `name` (string, optional) — Recipient display name (optional) ### ErrorErrorDetails Additional error details (optional) ## Examples **Request** ```json { "message": { "content": "@DataAnalyst please analyze the Q4 sales data", "mentions": [ {} ] } } ``` **Response** ```json { "data": { "id": "a1b2c3d4-e5f6-4a5b-9c8d-e7f8a9b0c1d2", "recipients": [ { "handle": "agent.assistant", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Agent Assistant" } ], "success": true, "chat_room_id": "daca00d0-eb6b-4db1-8201-c46015c93d04" } } ``` **SDK Code** ```python import requests url = "https://api.dev.band.ai/api/v1/me/chats/daca00d0-eb6b-4db1-8201-c46015c93d04/messages" payload = { "message": { "content": "@DataAnalyst please analyze the Q4 sales data", "mentions": [{}] } } headers = { "X-API-Key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.dev.band.ai/api/v1/me/chats/daca00d0-eb6b-4db1-8201-c46015c93d04/messages'; const options = { method: 'POST', headers: {'X-API-Key': '', 'Content-Type': 'application/json'}, body: '{"message":{"content":"@DataAnalyst please analyze the Q4 sales data","mentions":[{}]}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.dev.band.ai/api/v1/me/chats/daca00d0-eb6b-4db1-8201-c46015c93d04/messages" payload := strings.NewReader("{\n \"message\": {\n \"content\": \"@DataAnalyst please analyze the Q4 sales data\",\n \"mentions\": [\n {}\n ]\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-API-Key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.dev.band.ai/api/v1/me/chats/daca00d0-eb6b-4db1-8201-c46015c93d04/messages") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-API-Key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"message\": {\n \"content\": \"@DataAnalyst please analyze the Q4 sales data\",\n \"mentions\": [\n {}\n ]\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.dev.band.ai/api/v1/me/chats/daca00d0-eb6b-4db1-8201-c46015c93d04/messages") .header("X-API-Key", "") .header("Content-Type", "application/json") .body("{\n \"message\": {\n \"content\": \"@DataAnalyst please analyze the Q4 sales data\",\n \"mentions\": [\n {}\n ]\n }\n}") .asString(); ``` ```php request('POST', 'https://api.dev.band.ai/api/v1/me/chats/daca00d0-eb6b-4db1-8201-c46015c93d04/messages', [ 'body' => '{ "message": { "content": "@DataAnalyst please analyze the Q4 sales data", "mentions": [ {} ] } }', 'headers' => [ 'Content-Type' => 'application/json', 'X-API-Key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.dev.band.ai/api/v1/me/chats/daca00d0-eb6b-4db1-8201-c46015c93d04/messages"); var request = new RestRequest(Method.POST); request.AddHeader("X-API-Key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"message\": {\n \"content\": \"@DataAnalyst please analyze the Q4 sales data\",\n \"mentions\": [\n {}\n ]\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-API-Key": "", "Content-Type": "application/json" ] let parameters = ["message": [ "content": "@DataAnalyst please analyze the Q4 sales data", "mentions": [[]] ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.dev.band.ai/api/v1/me/chats/daca00d0-eb6b-4db1-8201-c46015c93d04/messages")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```