> ## Documentation Index
> Fetch the complete documentation index at: https://darwin.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Communicate

> Send typed messages and follow safe thread projections.

Keep one thread for its questions, actions, decisions, and results. Start thread
accepts the first message atomically; Send message continues it with three core
fields: `thread`, `messageType`, and `messageContent`.

```json theme={null}
{
  "thread": "returned-thread-id",
  "messageType": "message",
  "messageContent": "What times are available?",
  "idempotencyKey": "availability-001"
}
```

An `accepted` response means Darwin saved the message. It does not mean the
target received it, answered it, or completed work.

## Message types you can send

`start_thread` requires `messageType` and `messageContent` for its first message. It accepts `message` or `action_request`. `send_message` accepts all six types below. Darwin validates the matching content shape and assigns sender authority from the authenticated request.

| `messageType` | `messageContent` | Meaning |
| - | - | - |
| `message` | A text string in `messageContent`; optional media uses `attachments` with `type` and Darwin `asset` ID. | Exchange ordinary content. Text is never approval, authentication or proof of payment. |
| `action_request` | `{ capability, arguments, account? }` | Request a capability with schema-valid arguments. A read may proceed; an external effect waits for exact confirmation. |
| `action_confirmation` | `{ request }` | Confirm the exact pending action request returned by Get thread. Do not recompute or guess its ID. |
| `approval_confirmation` | `{ request, decision }`, where decision is `allow` or `deny` | Resolve one additional permission request. Denial is not proof that previously dispatched work stopped. |
| `completion_confirmation` | `{ request }` | Accept the result referenced by one completion request. This does not authorize a new external effect. |
| `cancellation_request` | `{ operation }` | Ask Darwin to stop an action. Keep reading the thread; requesting cancellation is not confirmation. |

Do not send authentication or payment confirmations. Use [Authenticate](/docs/reference/threads/authenticate) and [Pay](/docs/reference/threads/pay); Darwin records verified outcomes in thread state.

## Target and runtime updates you can receive

The canonical durable history also contains the target/runtime-only types below. They are exhaustive and are generated from the internal thread event schema. Callers cannot submit or forge them. Get thread exposes their safe current projection, not the private raw event.

| Internal event type | Get thread projection | Meaning |
| - | - | - |
| `approval_request` | `requests` | A separate permission decision is pending. |
| `approval_expired` | `requests` | Darwin expired an unresolved approval request. |
| `payment_expired` | `requests` | Darwin expired an unresolved payment request. |
| `authentication_request` | `requests` | Authentication is required for an action. |
| `authentication_required` | `requests` | Compatibility form of an authentication request from existing history. |
| `authentication_confirmation` | `requests` | Darwin verified the requested connection; no credential is exposed. |
| `payment_request` | `requests` | An immutable payment decision is pending. |
| `payment_confirmation` | `requests` | Darwin verified settlement through its payment broker. |
| `payment_status` | `requests` | Current pending, failure, refund, reversal, dispute or void state. |
| `result` | `messages` | Safe output content returned for an action. |
| `completion_request` | `requests` | A result is waiting for completion confirmation. |
| `action_withdrawn` | `actions` | Darwin proved the action never crossed its dispatch boundary. |
| `cancellation_confirmation` | `actions` | Darwin verified the action was cancelled; a request alone is not enough. |
| `delivery_status` | `messages[].status` | Latest accepted, delivered, failed or unknown delivery state. |
| `status` | `actions` | Current queued, running, waiting or reconciling action state. |
| `error` | `actions` | A safe failure state; private provider detail is omitted. |

## What Get thread returns

`messages` contains safe text/media message and result projections. `actions` contains current action status. `requests` is a strict discriminated review union. It includes exact safe action arguments and account selection, approval reason and action terms, authentication target/type/resource/scopes/account when available, payment amount/currency/payee/methods/expiry, or the result ID for completion review.

Request review terms come from the immutable originating event, independent of the current cursor page. Darwin fails closed if those terms are missing, corrupt, or contain credential-shaped fields. Public objects omit internal revisions, request digests, credentials and provider receipts.

For a confirmation, copy the `request` ID from the matching Get thread request. Use the `action` ID only for `cancellation_request`. Never treat ordinary text such as “approved” as structured authority.

## Attachments

Ordinary `message` sends text in `messageContent`. Optional `attachments` can reference validated `image`, `audio`, `video` or `file` assets. Each attachment uses `{ type, asset }`; it never contains inline base64, credentials or an arbitrary download URL. Media still requires an available upload validator and compatible route.

## Recover history and status

Call Get thread with the last processed `cursor`. Continue while `hasMore` is
true; once caught up, set `wait: true` for one bounded read. A quiet result is
an idle wait, not completion. MCP does not expose a separate stream tool.

The first-party Web experience may use its authenticated SSE transport and resume from
`Last-Event-ID`; that private transport does not add an eighth Act operation. Stream
disconnects do not cancel or complete work.

Use `messages` for safe conversation/result content, `actions` for current work
state, and `requests` for pending or resolved decisions. Each request is a strict
review object: action and approval requests include their exact safe capability
arguments; authentication requests include target, type, resource, scopes, and
selected account when available; payment requests include amount, currency,
payee, accepted methods, and expiry. Completion requests identify the result.

Darwin loads those immutable review terms even when their originating event is
outside the current cursor page. Missing, corrupt, or credential-shaped review
data fails closed. Public projections omit internal revisions, digests,
credentials, provider references, and receipts.

## Retry rules

* Retry a timed-out mutation only with the same idempotency key and identical input.
* On authorization denial, stop and reconnect with the required scope.
* On rate limits, respect `Retry-After`.
* Before resending work, read the thread and check its current actions and requests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.