# Send your connected agent a message on a board

> Page: https://docs.plotwork.dev/api/post-orgs-org-boards-board-agents-connection-messages. Index of every page: https://docs.plotwork.dev/llms.txt

Keeps a message in the thread of one agent connection on the board, for the agent's next wait_for_board_messages, open_board or read_board_tab, and shows it on that thread's screens: sent, then delivered when the agent reads it, then answered.

`POST /orgs/{org}/boards/{board}/agents/{connection}/messages`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Send your connected agent a message on a board. |
| What does it take? | A JSON body of type [`BoardMessageBody`](https://docs.plotwork.dev/api/schemas.md#boardmessagebody). |
| What does it return? | Status 200 with a body of type [`BoardMessageSent`](https://docs.plotwork.dev/api/schemas.md#boardmessagesent). |
| What can go wrong? | `400` the body is not valid: no text, a text too long, or too many problems; `401` not signed in; `403` boards are not on for the organisation (boards.not_enabled), or the caller is not the member who connected this agent (boards.not_your_agent); `404` no such organisation, board, tab or agent connection, or one not open to the caller: the cases look alike; `422` the message holds something that looks like a secret, and the organisation blocks them (boards.secret_blocked, the findings masked); `429` too many requests; `503` organisations or boards are not set up on this server. Every failure uses the one error envelope. |

## What it does

Keeps a message in the thread of one agent connection on the board, for the agent's next wait_for_board_messages, open_board or read_board_tab, and shows it on that thread's screens: sent, then delivered when the agent reads it, then answered. Only the member who connected the agent may send, or also an owner or admin when the organisation's setting says so; anyone else gets 403 boards.not_your_agent. The text and the problems are scanned for secrets. A thread keeps its last 50 messages, for 30 days at most. Audited as orgs.board.agent_message, without the words.

## Path parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `org` | `string` | yes | The organisation's id or its slug. |
| `board` | `string` | yes | The board's id: 22 letters and digits. |
| `connection` | `string` | yes | The agent connection's id, as the board's presence names it. |

## Request body

The body has the type [`BoardMessageBody`](https://docs.plotwork.dev/api/schemas.md#boardmessagebody).

| Field | Type | Required | Description |
|---|---|---|---|
| `text` | `string` | yes | What the person asks of their agent, in their words. Kept on the board like a tab, never in the audit log. at least 1 character; at most 2000 characters. |
| `tab` | `string \| null` | no | The tab on screen, or null. at least 12 characters; at most 12 characters; pattern `^[0-9A-Za-z]+$`. |
| `revision` | `string \| null` | no | The revision on screen, or null for main. at least 12 characters; at most 12 characters; pattern `^[0-9A-Za-z]+$`. |
| `problems` | `BoardAgentProblem[]` | no | The tab's problems, for Send problems. |
| `problems[].code` | `string` | yes | pattern `^[A-Z]\d{3,4}$`. |
| `problems[].severity` | `"error" \| "warning"` | yes |  |
| `problems[].line` | `integer` | yes | minimum 1; maximum 1000000. |
| `problems[].column` | `integer` | yes | minimum 1; maximum 1000000. |
| `problems[].message` | `string` | yes | at least 1 character; at most 500 characters. |
| `problems[].hint` | `string \| null` | yes | at least 1 character; at most 500 characters. |

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | The message, as its thread shows it, and how many things in it look like a secret. | [`BoardMessageSent`](https://docs.plotwork.dev/api/schemas.md#boardmessagesent) |
| 400 | The body is not valid: no text, a text too long, or too many problems. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 401 | Not signed in. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 403 | Boards are not on for the organisation (boards.not_enabled), or the caller is not the member who connected this agent (boards.not_your_agent). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 404 | No such organisation, board, tab or agent connection, or one not open to the caller: the cases look alike. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 422 | The message holds something that looks like a secret, and the organisation blocks them (boards.secret_blocked, the findings masked). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 429 | Too many requests. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 503 | Organisations or boards are not set up on this server. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

A 200 answer has the type [`BoardMessageSent`](https://docs.plotwork.dev/api/schemas.md#boardmessagesent).

| Field | Type | Required | Description |
|---|---|---|---|
| `message` | `BoardMessage` | yes |  |
| `message.id` | `string` | yes |  |
| `message.connection` | `string` | yes |  |
| `message.owner` | `string` | yes |  |
| `message.at` | `integer` | yes |  |
| `message.from` | `"person" \| "agent"` | yes |  |
| `message.label` | `string` | yes |  |
| `message.text` | `string` | yes |  |
| `message.tab` | `string \| null` | yes |  |
| `message.revision` | `string \| null` | yes |  |
| `message.problems` | `BoardAgentProblem[]` | yes |  |
| `message.problems[].code` | `string` | yes | pattern `^[A-Z]\d{3,4}$`. |
| `message.problems[].severity` | `"error" \| "warning"` | yes |  |
| `message.problems[].line` | `integer` | yes | minimum 1; maximum 1000000. |
| `message.problems[].column` | `integer` | yes | minimum 1; maximum 1000000. |
| `message.problems[].message` | `string` | yes | at least 1 character; at most 500 characters. |
| `message.problems[].hint` | `string \| null` | yes | at least 1 character; at most 500 characters. |
| `message.inReplyTo` | `string \| null` | yes |  |
| `message.status` | `"sent" \| "delivered" \| "answered"` | yes | sent: kept for the agent; delivered: the agent read it; answered: the agent replied. |
| `message.deliveredAt` | `integer \| null` | yes |  |
| `message.answeredAt` | `integer \| null` | yes |  |
| `secrets` | `object` | yes |  |
| `secrets.count` | `integer` | yes |  |
| `secrets.kinds` | `string[]` | yes |  |

## See also

| Doc | Why |
|---|---|
| [API reference](https://docs.plotwork.dev/api/reference.md) | Every endpoint, and the error envelope |
| [Schemas](https://docs.plotwork.dev/api/schemas.md) | Every request and response type |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |