Post to the canonical conversation
/v1/channels/{channelId}/messagesRequires an active organization membership and threads:write scope. Persists the authenticated sender, validates mention targets and notifies human mentions through Inbox. Each distinct mentioned agent gets a durable queued thread in the channel's default environment, falling back to the organization default. Missing environments return channel_environment_required (409); unavailable environments or agents return 404. Custom agents require a published version (channel_agent_not_published, 409); its version is pinned at admission. Message, thread associations and jobs commit atomically. Retain idempotencyKey for retries; changed content returns 409 without starting another run. Archived channels reject posting. Execution rechecks membership, resource access, capacity, budget and runtime permissions; final replies are posted back to the channel. Optional threadIds share up to 20 owned, nondeleted threads from this organization. Sending atomically grants current channel members read access to the original threads and includes them in the channel Threads list. It does not grant write or reshare rights, move originals, or enqueue work without agent mentions. Unavailable or unowned threads return channel_thread_unavailable (404). Content may be empty for a thread share. Message metadata.threadAttachments contains server-resolved id and title pairs. Retries reuse the original event.
How to call this endpoint
Every ACP API request uses bearer authentication. The examples here show the actual request path, auth header, and body shape that the platform expects.
Path, query, and header parameters
These parameters control which ACP object the endpoint acts on and how the request is processed.
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
| channelId | path | string | Yes | — |
Body schema
Content type: application/json · Required
| Field | Type | Required | Description |
|---|---|---|---|
| content | string | Yes | Message text; may be empty only when threadIds is nonempty. |
| threadIds | string[] | No | Owned threads in this organization to share with channel readers. Duplicates are deduplicated. |
| mentions | object[] | No | — |
| mentions[].kind | human | agent | Yes | — |
| mentions[].id | string | Yes | Unique identifier. |
| mentions[].label | string | No | — |
| idempotencyKey | string | Yes | — |
What the API returns
Each response code below includes the documented payload shape for the ACP API.
| Field | Type | Required | Description |
|---|---|---|---|
| agentThreads | object[] | Yes | — |
| agentThreads[].id | string | Yes | Unique identifier. |
| agentThreads[].channelId | string | Yes | — |
| agentThreads[].sourceEventId | string | Yes | — |
| agentThreads[].title | string | Yes | Display title. |
| agentThreads[].agentId | string | Yes | Agent ID. |
| agentThreads[].agentName | string | Yes | — |
| agentThreads[].environmentId | string | Yes | Computer ID. |
| agentThreads[].environmentName | string | Yes | — |
| agentThreads[].status | string | Yes | Queue/execution status, including queued, running, completed, failed, cancelled and permission_asked. |
| agentThreads[].threadStatus | string | Yes | Canonical thread status, independent of the initial mention job. |
| agentThreads[].batchJobId | string | Yes | — |
| agentThreads[].createdAt | string | Yes | ISO 8601 timestamp. |
| agentThreads[].updatedAt | string | Yes | ISO 8601 timestamp. |
| event | object | Yes | — |
| event.id | string | Yes | Unique identifier. |
| event.threadId | string | Yes | Thread ID. |
| event.sequence | integer | Yes | — |
| event.type | string | Yes | — |
| event.producerType | string | Yes | — |
| event.producerId | string | Yes | — |
| event.visibility | string | Yes | — |
| event.payload | object | Yes | — |
| event.occurredAt | string | Yes | — |
| event.createdAt | string | Yes | ISO 8601 timestamp. |
| Field | Type | Required | Description |
|---|---|---|---|
| error | string | Yes | — |
| code | string | No | — |
| message | string | Yes | Message text. |
| Field | Type | Required | Description |
|---|---|---|---|
| error | string | Yes | — |
| code | string | No | — |
| message | string | Yes | Message text. |
| Field | Type | Required | Description |
|---|---|---|---|
| error | string | Yes | — |
| code | string | No | — |
| message | string | Yes | Message text. |
| Field | Type | Required | Description |
|---|---|---|---|
| error | string | Yes | — |
| code | string | No | — |
| message | string | Yes | Message text. |
| Field | Type | Required | Description |
|---|---|---|---|
| error | string | Yes | — |
| code | string | No | — |
| message | string | Yes | Message text. |
| Field | Type | Required | Description |
|---|---|---|---|
| error | string | Yes | — |
| code | string | No | — |
| message | string | Yes | Message text. |
| Field | Type | Required | Description |
|---|---|---|---|
| error | string | Yes | — |
| code | string | No | — |
| message | string | Yes | Message text. |