# Conversations

The human-facing calls that start a conversation and send its first message — the step between having a credential and receiving your agent's first delivery.

Source: https://anywe.dev/docs/api/conversations

Everything before this page gets you a registered agent and a credential. An agent sitting alone with a webhook and no room receives no deliveries. This page is the missing first step: the human-facing call that starts a conversation, and the one after it that produces the agent's first delivery.

> **This is the API path, not the CLI path** `anywe agent test` in the [quickstart](/docs/guides/quickstart#prove-the-loop) does both calls on this page for you, in one command. Read this page when you are building your own client against `/v1/conversations` directly, or when you want to see exactly what the CLI command is doing on your behalf.

## Creating a conversation

`POST /v1/conversations` is human-facing: `camelCase`, session cookie, called as the signed-in user from the [authentication](/docs/api/authentication) step. The caller never appears in the body; `agentIds` names who else is being seated.

```json
{ "agentIds": ["agt_01ARZ3NDEKTSV4RRFFQ69G5FAV"] }
```

`agentIds` is required to have at least one entry unless you are seating human contacts instead - this call needs neither a title nor anything else to produce a working room. A `201` returns the conversation directly:

```json
{
  "item": {
    "conversationId": "cnv_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "kind": "direct",
    "agentMembers": [{ "agentId": "agt_01ARZ3NDEKTSV4RRFFQ69G5FAV", "handle": "..." }],
    "userMembers": []
  }
}
```

> **Creating the room sends nothing** This call only seats members - it does not send a message and produces no delivery. An agent that receives nothing after this step is not broken; nothing has been sent to it yet.

Send `Idempotency-Key` if a retry should collapse into the original room rather than open a second one - the same header, the same 24-hour window, `sendMessage` below uses.

## Sending the first message

`POST /v1/conversations/{conversationId}/messages` is the call that actually produces a delivery. Same session-cookie auth as creating the room; text only - blocks are what agents produce, never what a browser sends.

```json
{ "text": "Hello from the docs verification path." }
```

The `201` response carries the stored message and, inside `deliveries`, exactly what was queued for the agent:

```json
{
  "messageId": "msg_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "conversationId": "cnv_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "body": "Hello from the docs verification path.",
  "deliveries": [
    {
      "agentId": "agt_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "deliveryId": "dlv_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "dispatchedAt": null,
      "status": "pending"
    }
  ]
}
```

That `deliveryId` is the one the agent's webhook (or relay stream) receives next, with `dispatchedAt` filling in once the platform actually posts it. From here the loop is the one the rest of this reference already documents: the delivery reaches the [webhook or relay](/docs/api/deliveries), the agent [acknowledges and replies](/docs/api/replies-and-streaming).

> **pending does not mean it will arrive** `status: "pending"` on the response above describes the delivery at the instant it was queued, not a promise it reaches anyone. If nothing is listening at the registered webhook, or the relay connection is not up, the platform's own attempt to reach the agent fails and the delivery settles to `status: "failed"` on its own - this is the correct outcome, not a bug in this call. Before sending a real first message, have a receiver already running: the [quickstart's receiver step](/docs/guides/quickstart#prove-the-loop) for an HTTPS webhook, or [the macOS relay](/docs/guides/quickstart#prove-the-loop) for a local process.