Send a message
/api/v1/chats/{chat_id}/messagesSend the chat's agent a message, as the app's Send does. The message waits with the chat's others until a turn takes it in, and the agent answers it in the chat.
A 202 response returns the stored message: queued while it waits for a turn, or steering when send_now gave it to the turn working now, which reads it before its next step. Until a turn takes it in, it is listed with the chat's waiting messages, where you can edit, delete or reorder it; then it appears in the chat's messages.
The turn that takes the message in runs with the credential that sent it: charged to that user API key, or as that integration for you. Like any run a key or an integration starts, it can't read your private environment variables. If the key stops working, or you withdraw the integration's consent, before the turn starts, the message is listed as failed with the reason.
Send a client_ref to make retries safe: sending again with the same reference returns the stored message. Up to 20 messages may wait in a chat; a 409 with code chat.messages_full means you should wait for the chat to take some in, or delete one. A 409 with code chat.not_active means the chat is archived.
Messages carry text only; attach files in the app.
Required access
Credentials: delegated token, user session, user API key
User API keys use the owner’s current permissions, subject to any key restrictions. Capability scopes below apply to automation account keys and delegated tokens.
Scope: chats:edit, agents:invoke
Only the member who started the chat, while an active member who isn't a viewer, through their user API key or an integration acting for them. Workspace owners and admins can't send to another member's chat, which answers 404.
A user-owned key prefixed gsmc_uk_, bound to one organization. It follows its owner's current membership, role and resource permissions, optionally restricted to read-only access. No X-Org-Id header is needed; a conflicting organization is rejected. Credential creation, personal connection setup and human attestations require a signed-in session. Runs are private to the calling user; sharing an agent grants access to your own personal memory of it, never to the agent's own memory.
In: header
Path Parameters
uuidHeader Parameters
Selects the active organization for a direct user session that has more than one membership. Automation account keys and delegated tokens are each bound to one organization and ignore it.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
A message for the chat's agent, as the chat's owner.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08/messages" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "content": "Summarize the open incidents, newest first.", "client_ref": "retry-safe-1c9e" }'{ "id": 0, "status": "failed", "content": "string", "client_ref": "string", "attachment_count": 0, "failure_message": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z"}