Send Message to Collab Agent | Athena

Submit a message to a collab agent through its Programmatic channel. The agent must have the channel explicitly enabled (programmaticEnabled) and must be shared with the caller. With wait=false (default) the submission is queued and the endpoint returns 202 immediately; the resulting session appears in Athena under the caller’s account. With wait=true the request long-polls: the connection stays open while the agent runs and the final agent message is returned verbatim in the reply field — size client timeouts for multi-minute runs. Submissions from the same caller with the same clientThreadKey continue one conversation until 24 hours of inactivity.

Submit a message to a collab agent through its Programmatic channel. The agent must have the channel explicitly enabled (programmaticEnabled) and must be shared with the caller. With wait=false (default) the submission is queued and the endpoint returns 202 immediately; the resulting session appears in Athena under the caller's account. With wait=true the request long-polls: the connection stays open while the agent runs and the final agent message is returned verbatim in the reply field — size client timeouts for multi-minute runs. Submissions from the same caller with the same clientThreadKey continue one conversation until 24 hours of inactivity.

Authentication

X-API-KEYstring

API Key authentication via header

Path parameters

asset_idstringRequired

Asset id of the collab agent to message

Request

This endpoint expects an object.

messagestringRequired1-32000 characters

The message text to submit to the agent. Delivered verbatim as the user turn of the agent session.

clientThreadKeystring or nullOptional<=128 characters

Optional caller-chosen conversation key. Submissions from the same caller with the same key continue one agent session (until 24 hours of inactivity); different keys hold independent conversations. Omitted, all of a caller’s submissions to this agent share one ‘default’ thread.

voiceUpdateHandlestring or nullOptional<=256 characters

Reserved for Athena voice surfaces (the OpenAI Live Console). An opaque callback handle for a live voice conversation that delegated this submission: the run gains a send_voice_update tool that streams interim updates back to that conversation. Requires wait=true. Leave unset for ordinary submissions.

waitbooleanOptionalDefaults to false

When false (default), the submission is queued and the endpoint returns 202 immediately. When true, the request long-polls: the connection is held open while the agent runs (typically seconds to a few minutes) and the final reply is returned in the response.

Response

Agent run completed inline (wait=true) and the final reply is included

statusstring

‘accepted’ when the submission was queued (wait=false, HTTP 202); ‘completed’ when the agent run finished inline (wait=true, HTTP 200).

threadKeystring

The conversation key this submission was routed under — the clientThreadKey from the request, or ‘default’.

replystring or nullOptional

The agent’s final message, verbatim. Null on 202 responses, and null on completed runs where the agent declined to reply (it invoked its dont_respond tool).

sessionIdstring or nullOptional

Asset id of the Athena session that handled the submission. Null on 202 responses (the session is resolved asynchronously).

Errors

403

Forbidden Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

500

Internal Server Error

502

Bad Gateway Error

503

Service Unavailable Error

$	curl -X POST https://api.athenaintel.com/api/v0/collab-agents/asset_id/messages \
>	-H "X-API-KEY: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"message": "Summarize yesterday'\''s pipeline changes.",
>	"clientThreadKey": "crm-sync-42",
>	"wait": true
>	}'

1	{
2	"status": "completed",
3	"threadKey": "crm-sync-42",
4	"reply": "Three pipeline changes landed yesterday: ...",
5	"sessionId": "asset_5c4f0b6e-93d1-4b3a-9a94-2f6f4f1f9a10"
6	}