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

# Retrieve a conversation

> GET /v1/conversations/{id} — fetch a single conversation with embedded messages

Returns a single conversation by its ID, with the full message thread embedded inline. Archived conversations are not returned.

```http theme={null}
GET /v1/conversations/{id}
```

## Authentication

Bearer token in the `Authorization` header. See [Authentication](/api-reference/authentication).

```http theme={null}
Authorization: Bearer rfl_live_...
```

## Path parameters

<ParamField path="id" type="string" required>
  Conversation ID prefixed with `conv_`.
</ParamField>

## Response

Returns a `Conversation` object with the full message thread embedded under `messages`.

### The Conversation object

<ResponseField name="id" type="string">
  Unique identifier prefixed with `conv_`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"conversation"`.
</ResponseField>

<ResponseField name="title" type="string">
  Conversation subject or summary.
</ResponseField>

<ResponseField name="status" type="string">
  Current status. One of `waiting_for_user`, `needs_first_response`, `needs_follow_up`, `scheduled_ai_response`, `assumed_resolved`, `resolved`, `spam`, `paused`, `investigating`.
</ResponseField>

<ResponseField name="supportLevel" type="string">
  Who is currently handling the conversation. One of `ai`, `human`.
</ResponseField>

<ResponseField name="channel" type="object">
  The channel the conversation belongs to.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Channel ID prefixed with `chan_`.</ResponseField>
    <ResponseField name="name" type="string">Channel display name.</ResponseField>
    <ResponseField name="type" type="string">Channel type (e.g. `email`, `widget`).</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="contact" type="object">
  The contact who started the conversation.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Contact ID prefixed with `ct_`.</ResponseField>
    <ResponseField name="name" type="string | null">Contact display name.</ResponseField>
    <ResponseField name="email" type="string | null">Contact email address.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="assignedToUser" type="object | null">
  The teammate the conversation is assigned to. `null` when unassigned.

  <Expandable title="properties">
    <ResponseField name="id" type="string">User ID prefixed with `user_`.</ResponseField>
    <ResponseField name="name" type="string | null">Display name, or `null` if no name is set.</ResponseField>
    <ResponseField name="email" type="string">User email address.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="topics" type="array">
  Topics applied to the conversation.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Topic ID.</ResponseField>
    <ResponseField name="name" type="string">Topic name.</ResponseField>
    <ResponseField name="color" type="string | null">Topic color (hex string), if set.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tags" type="array">
  Tags applied to the conversation.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Tag ID.</ResponseField>
    <ResponseField name="name" type="string">Tag name.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="urgencyScore" type="integer | null">
  Urgency rating from `1` (not urgent) to `3` (critical). `null` when unscored.
</ResponseField>

<ResponseField name="lastMessagePreview" type="string | null">
  First 200 characters of the conversation's opening message. Truncated with `…` when longer. `null` if the conversation has no messages.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 UTC timestamp of conversation creation.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 UTC timestamp of the most recent update.
</ResponseField>

<ResponseField name="waitingSince" type="string | null">
  ISO 8601 UTC timestamp of when the conversation started waiting for a response. `null` if not waiting.
</ResponseField>

<ResponseField name="firstHumanReplyAt" type="string | null">
  ISO 8601 UTC timestamp of the first human reply. `null` if no human has replied yet.
</ResponseField>

<ResponseField name="resolvedAt" type="string | null">
  ISO 8601 UTC timestamp of resolution. `null` while the conversation is open.
</ResponseField>

<ResponseField name="messages" type="array">
  Every message in the thread, ordered by `createdAt` ascending.

  <Expandable title="The Message object">
    <ResponseField name="id" type="string">Message ID prefixed with `msg_`.</ResponseField>
    <ResponseField name="object" type="string">Always `"message"`.</ResponseField>
    <ResponseField name="role" type="string">Who sent the message. One of `user` (the contact), `assistant` (Replyful AI), `human` (a teammate), `system`.</ResponseField>
    <ResponseField name="content" type="string | null">Plain-text body. `null` if the message has no text content.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 UTC timestamp of when the message was recorded.</ResponseField>
    <ResponseField name="sentAt" type="string | null">ISO 8601 UTC timestamp of delivery for outbound messages. `null` for inbound messages or not-yet-delivered drafts.</ResponseField>

    <ResponseField name="attachments" type="array">
      Non-inline files attached to the message.

      <Expandable title="properties">
        <ResponseField name="id" type="string">Attachment ID.</ResponseField>
        <ResponseField name="filename" type="string">Original filename uploaded by the sender.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

### Fetch a conversation

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.replyful.com/v1/conversations/conv_01HK7G3M8YPQ1A0R3N2X9Y4ZBC \
    -H "Authorization: Bearer rfl_live_..."
  ```

  ```ts Node.js theme={null}
  const res = await fetch(
    "https://api.replyful.com/v1/conversations/conv_01HK7G3M8YPQ1A0R3N2X9Y4ZBC",
    { headers: { Authorization: `Bearer ${process.env.REPLYFUL_API_KEY}` } },
  );
  const conversation = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.get(
      "https://api.replyful.com/v1/conversations/conv_01HK7G3M8YPQ1A0R3N2X9Y4ZBC",
      headers={"Authorization": f"Bearer {os.environ['REPLYFUL_API_KEY']}"},
  )
  res.raise_for_status()
  conversation = res.json()
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "conv_01HK7G3M8YPQ1A0R3N2X9Y4ZBC",
  "object": "conversation",
  "title": "Refund request",
  "status": "needs_first_response",
  "supportLevel": "ai",
  "channel": {
    "id": "chan_01HK6P9X2D3R5T7V9W1Y3Z5BCE",
    "name": "Support inbox",
    "type": "email"
  },
  "contact": {
    "id": "ct_01HK6QFE7T2N4P6S8U0W2Y4ABD",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "assignedToUser": {
    "id": "user_01HK6S2A4F6H8J0L2N4P6Q8RST",
    "name": "Grace Hopper",
    "email": "grace@acme.com"
  },
  "topics": [
    { "id": "tpc_01HK6RB...", "name": "Billing", "color": "#0098da" }
  ],
  "tags": [
    { "id": "tag_01HK6T7...", "name": "vip" }
  ],
  "urgencyScore": 2,
  "lastMessagePreview": "Hi, I'd like a refund on my last order...",
  "createdAt": "2026-04-29T14:30:00Z",
  "updatedAt": "2026-04-29T14:32:00Z",
  "waitingSince": "2026-04-29T14:32:00Z",
  "firstHumanReplyAt": null,
  "resolvedAt": null,
  "messages": [
    {
      "id": "msg_01HK7G3M8YPQ1A0R3N2X9Y4ZB1",
      "object": "message",
      "role": "user",
      "content": "Hi, I'd like a refund on my last order. Order #4821.",
      "createdAt": "2026-04-29T14:30:00Z",
      "sentAt": null,
      "attachments": [
        {
          "id": "att_01HK7G3M8YPQ1A0R3N2X9Y4ZB2",
          "filename": "receipt.pdf"
        }
      ]
    },
    {
      "id": "msg_01HK7G3M8YPQ1A0R3N2X9Y4ZB3",
      "object": "message",
      "role": "assistant",
      "content": "Thanks Ada — I can see order #4821 here. Could you confirm the email used at checkout so I can look up the payment?",
      "createdAt": "2026-04-29T14:32:00Z",
      "sentAt": "2026-04-29T14:32:00Z",
      "attachments": []
    }
  ]
}
```

## Error responses

| Status | `error.code`             | When                                                                                    |
| ------ | ------------------------ | --------------------------------------------------------------------------------------- |
| `401`  | `missing_api_key`        | The `Authorization` header is absent.                                                   |
| `401`  | `invalid_api_key`        | The token is malformed, unknown, or archived.                                           |
| `404`  | `conversation_not_found` | The conversation does not exist, belongs to another organization, or has been archived. |
| `422`  | `invalid_path_parameter` | The `id` path parameter is not a valid `conv_…` ID.                                     |
| `429`  | `too_many_requests`      | Rate limit exceeded. Honor `Retry-After`.                                               |

See [Errors](/api-reference/errors) for the full error envelope reference.