Send a message
Message your agent exactly as the dashboard chat does, and optionally hold the request open for the reply.
curl -X POST -H "Authorization: Bearer $REVNU_API_TOKEN" \
-H "content-type: application/json" \
-d '{"text":"What did we ship this week?","waitSeconds":90,"clientRequestId":"weekly-1"}' \
https://revnu.com/api/v1/agent/messagesBody
| Field | Type | Meaning |
|---|---|---|
text |
string, required | Up to 4,000 characters. See Message length. |
clientRequestId |
string | Up to 128 characters of A-Za-z0-9_.:-. A retry with the same id returns the original requestId. Never reuse an id after a failed message; send again with a new one. |
waitSeconds |
integer, 0 to 120 | Hold the request until the message is done: the agent replied or failed and any background research it started was reported. |
interrupt |
boolean, default true |
A new message stops the agent's running turn. Send false to leave unfinished work alone: while this token's newest message is still queued or running, nothing is sent and the response names that request with notSent: true. |
queue |
boolean, default false |
Send true to hand over another job without stopping the running one: the message is sent and the agent starts it once its current work is done. Use it when your software sends several jobs in a row, such as one list of companies per market. It stays queued for up to six hours while earlier work runs, then counts as failed. Cannot be combined with interrupt. |
Message length
text holds at most 4,000 characters, the same limit as the dashboard chat, counted after trimming leading and trailing spaces. Characters are counted as JavaScript counts them, so an emoji counts as two. A longer message gets 400. Split a longer list across several messages sent with queue: true.
Responses
| Code | Meaning |
|---|---|
| 202 | { requestId, deduplicated, notSent?, message? }. Queued; poll the message. With waitSeconds, message is the last state seen, and waitEnded (unauthorized or poll_failed) says when the wait stopped early. An unauthorized stop carries no message. |
| 200 | Only with waitSeconds: message is terminal and replies is filled. |
| 400 | Missing or empty text, text over 4,000 characters, a non-string client id, a non-boolean interrupt or queue, queue together with interrupt, or a waitSeconds outside 0 to 120. |
| 409 | rejected with a message: a client id with characters outside A-Za-z0-9_.:-, or an account that can't take work right now (a trial waiting for a card, or paused for payment). |
With interrupt: false and an unfinished earlier message, either code can carry notSent: true: requestId and message are then the earlier request's, and nothing new was sent.
Frequently Asked Questions
How do I send many jobs in a row?
Send each with queue: true and its own clientRequestId. Each runs after the one before finishes, and a retry of any of them is not sent twice. See Talk to Your Agent.
Does a new message stop the one Revnu is working on?
Yes, by default. Send interrupt: false to send nothing while this token's last message is unfinished, or queue: true to send it to wait its turn. The MCP tool ask_revnu defaults to interrupt: false.
Which scope does this need?
agent:message. A token without it gets 403 with requiredScope in the body. GET /me shows a token's scopes.
Are responses cached?
No. Every response is Cache-Control: no-store, so what you read is current.