# Get a conversation

> One conversation with its last text, how many texts in are unread, and whether the person is waiting on you.

`GET /v1/conversations/{id}`

One conversation with its last text, how many texts in are unread, and whether the person is waiting on you.

Needs a key with the `messages:read` scope. [Keys and scopes](https://usebluebot.com/docs/concepts/api-keys)

## Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The conversation’s id. Starts with `conv_` |

## Example

```bash
curl "https://usebluebot.com/api/v1/conversations/conv_1Hq2LxW9cVbN3mKpRtYs0a" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY"
```

```ts
import BlueBot from '@usebluebot/sdk';

const client = new BlueBot({ apiKey: process.env.BLUEBOT_API_KEY });

const conversation = await client.conversations.get('conv_1Hq2LxW9cVbN3mKpRtYs0a');
console.log(conversation);
```

```python
import os
from bluebot import BlueBot

client = BlueBot(api_key=os.environ["BLUEBOT_API_KEY"])

conversation = client.conversations.get("conv_1Hq2LxW9cVbN3mKpRtYs0a")
print(conversation)
```

## Response

`200`: The conversation.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | A conv_ id. Starts with `conv_` |
| `object` | "conversation" | Yes |   |
| `kind` | string | Yes | `person` for one person, `group` for a group chat. One of `person`, `group` |
| `title` | string | Yes | The person’s name, the group’s name, or their numbers, as the inbox shows it. |
| `handle` | string or null | Yes | The person’s phone number or email address; null for a group. |
| `contact_id` | string or null | Yes | The person, for a one-to-one conversation. Starts with `ct_` |
| `chat_id` | string or null | Yes | The group chat, for a group. Starts with `chat_` |
| `participants` | array of strings | Yes | Everyone in it besides you: one handle for a person, the members for a group. |
| `service` | string or null | Yes | The service the last text used, when known. One of `imessage`, `sms` |
| `last_message` | object or null | Yes |   |
| `last_message.id` | string | Yes | A msg_ id. Starts with `msg_` |
| `last_message.direction` | string | Yes | One of `in`, `out` |
| `last_message.state` | string | Yes | The last text’s state. |
| `last_message.preview` | string or null | Yes | Its first 140 characters, or null when it had no words. |
| `last_message.files` | integer | Yes | How many files it carried. |
| `last_message.at` | timestamp | Yes | When it was sent or arrived. |
| `last_message_at` | timestamp or null | Yes | When the last text was sent or arrived. |
| `unread_count` | integer | Yes | Texts in that you haven’t opened in the dashboard. |
| `waiting` | boolean | Yes | True when the last text is theirs, so they are waiting on you. |
| `archived` | boolean | Yes | Marked done. A new text in brings it back. |
| `stopped` | boolean | Yes | The person is on your stop list. |
| `created_at` | timestamp | Yes | When the conversation started. |

The answer, `200`:

```json
{
  "id": "conv_1Hq2LxW9cVbN3mKpRtYs0a",
  "object": "conversation",
  "kind": "person",
  "title": "Maria Alvarez",
  "handle": "+15555550123",
  "contact_id": "ct_1Hq2LxW9cVbN3mKpRtYs0a",
  "chat_id": null,
  "participants": [
    "+15555550123"
  ],
  "service": "imessage",
  "last_message": {
    "id": "msg_1Hq2LxW9cVbN3mKpRtYs0a",
    "direction": "in",
    "state": "received",
    "preview": "Can we move the showing to 4?",
    "files": 0,
    "at": "2026-11-13T19:44:12.000Z"
  },
  "last_message_at": "2026-11-13T19:44:12.000Z",
  "unread_count": 1,
  "waiting": true,
  "archived": false,
  "stopped": false,
  "created_at": "2026-11-02T15:20:00.000Z"
}
```

## Errors

Every refusal has the same envelope and a page of its own. These are the ones this operation can give.

| Code                                                    | Status | What it means                                                                                                                               |
| ------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| [`unauthorized`](https://usebluebot.com/docs/errors/unauthorized)             | 401    | The request carried no key, or a key BlueBot doesn’t know: mistyped, revoked, or a test key sent to the live API.                           |
| [`insufficient_scope`](https://usebluebot.com/docs/errors/insufficient_scope) | 403    | The key doesn’t carry the scope the endpoint needs. Each endpoint’s reference names its scope.                                              |
| [`rate_limited`](https://usebluebot.com/docs/errors/rate_limited)             | 429    | Too many requests. A key may make 120 requests a minute. The `RateLimit` header says how many are left, and `Retry-After` how long to wait. |
| [`internal`](https://usebluebot.com/docs/errors/internal)                     | 500    | Something went wrong on BlueBot’s side. It was reported. Send the request again; with an Idempotency-Key that is always safe.               |
| [`not_found`](https://usebluebot.com/docs/errors/not_found)                   | 404    | There is no such thing on this account. Ids are prefixed by kind, so a message id starts with `msg_`.                                       |

## Try it