# The Conversation object

> Attributes of a BloomText Conversation and the endpoints that return it.

Source: https://www.bloomtext.com/developers/api/reference/conversation-object/

Conversations with patients, one per patient and clinic phone number. Patient API.

### Attributes

- `id` (UUID, required): Unique ID of the conversation.

- `organization_id` (UUID, required): Organization the conversation belongs to.

- `type` (patient, direct, group, broadcast, required): A conversation with a patient, or a staff direct message, group, or broadcast. API keys see only `patient`.

- `title` (string, required): The conversation's name as the user sees it in BloomText.

- `patient` (PatientRef or null): The patient, for patient conversations. Null otherwise.

  Child attributes:
- `id` (UUID, required): ID of the patient.

- `name` (string, required): The patient's name, or their phone number if they have no name yet.

- `phone_number` (PhoneNumberRef or null): The clinic phone number, for patient conversations by SMS. Null otherwise.

  Child attributes:
- `number` (string, required): The phone number.

- `team` (string, required): The team it belongs to.

- `channel` (secure, sms, null): How the patient receives messages, for patient conversations. Null otherwise.

- `created_at` (timestamp, required): When the conversation was created.

- `last_message_at` (timestamp or null, required): When the latest message was sent. Null for a conversation with no messages.

- `unread_count` (integer, required): Always 0 with an API key, which has no read state. With OAuth, messages the person hasn't read.

- `seen_at` (timestamp or null, required): Always null with an API key. With OAuth, when the person last read the conversation.

- `messages_in_range` (integer or null): On List conversations with `after` or `before`: how many of its messages fell in the range. Null otherwise.

- `latest_message` (Message or null): On List conversations: the conversation's latest message in the range. Null otherwise.

  Child attributes:
- `id` (UUID, required): Unique ID of the message.

- `conversation` (ConversationRef, required): The conversation a message belongs to.

  Child attributes:
- `id` (UUID, required): ID of the conversation.

- `title` (string, required): The conversation's name as the user sees it.

- `sender` (Sender, required): Who sent a message.

  Child attributes:
- `id` (UUID, required): ID of the sender.

- `name` (string, required): The sender's display name.

- `kind` (staff, patient, api_key, api_identity, required): A staff member, a patient, an API key (`name` is the key's name, like "Reminder service"), or an API identity (the automated sender the key belongs to, like "Appointment reminders"; not a staff member).

- `patient` (PatientRef or null, required): The patient in the conversation, for patient conversations. Null otherwise.

  Child attributes:
- `id` (UUID, required): ID of the patient.

- `name` (string, required): The patient's name, or their phone number if they have no name yet.

- `channel` (app, secure, sms, required): How the message traveled: inside BloomText (`app`), by secure link, or by plain SMS.

- `phone_number` (PhoneNumberRef or null): The clinic phone number, for SMS messages. Null otherwise.

  Child attributes:
- `number` (string, required): The phone number.

- `team` (string, required): The team it belongs to.

- `delivery` (Delivery or null): Delivery status, for messages sent to a patient. Null otherwise.

  Child attributes:
- `status` (queued, sent, delivered, failed, undelivered, rejected, consent_requested, required): Where the message is: `queued` (accepted, not yet with the carrier), `sent` (with the carrier, or a secure message sent), `delivered` (the carrier confirmed it), `failed` or `undelivered` (it didn't reach the patient), `rejected` (BloomText didn't send it, because the patient opted out, the carrier blocks texts to them, an admin blocked the number, the number can't receive texts, the organization requires consent and the patient hasn't given it, or the text waited for consent and wasn't sent), or `consent_requested` (the organization requires consent before texting: BloomText asked the patient, and the message goes when they reply YES). For a message to several patients, the worst of theirs: `failed` if any failed, `delivered` only when all were.

- `error_code` (string or null): Why it wasn't delivered: the carrier's code, like `30005`, or BloomText's reason: `patient_opted_out`, `carrier_blocked`, `number_blocked`, `number_unreachable`, `consent_required` (the organization requires consent and the patient hasn't given it) or `consent_not_sent` (the text waited for consent and wasn't sent). Null otherwise.

- `detail` (string or null): What `error_code` means, in plain English. Null when there's no error.

- `updated_at` (timestamp, required): When the status last changed. Carrier reports arrive within minutes.

- `recipients` (array of object): For a message to several patients (a group conversation), each one's delivery. Absent for one patient.

- `campaign_id` (UUID or null): The campaign that sent this message. Null otherwise.

- `created_at` (timestamp, required): When the message was sent.

- `edited_at` (timestamp or null): When the message was last edited. Null if it never was.

- `type` (text, file, required): Whether the message carries text or a file.

- `body` (string or null): Message text. Null for file messages.

- `file` (FileReference or null): File metadata. Null for text messages.

  Child attributes:
- `id` (UUID, required): Unique ID of the file.

- `name` (string, required): Original file name.

- `mime` (string or null): MIME type, such as `application/pdf`.

- `size_bytes` (integer or null): File size in bytes.

- `reply_to_message_id` (UUID or null): Message this is a reply to. Null for top-level messages.

- `unread` (boolean, required): Always false with an API key, which has no read state. With OAuth, whether the connected person hasn't read it.

- `sent_via` (App or null): Null for messages sent in BloomText or with an API key. With OAuth, the app that sent it for the connected person; staff see this, patients don't.

  Child attributes:
- `client_id` (string, required): Your app's OAuth client ID.

- `name` (string, required): Your app's name as users and staff see it.

### Endpoints

| Method | Path | Endpoint |
| --- | --- | --- |
| GET | `/patient-conversations` | [List patient conversations](https://www.bloomtext.com/developers/api/reference/list-patient-conversations/) |
| GET | `/patient-conversations/{conversationId}` | [Retrieve a patient conversation](https://www.bloomtext.com/developers/api/reference/get-patient-conversation/) |
| GET | `/me/conversations` | [List conversations](https://www.bloomtext.com/developers/api/reference/list-conversations/) |
| GET | `/me/conversations/{conversationId}` | [Retrieve a conversation](https://www.bloomtext.com/developers/api/reference/get-conversation/) |

```json filename="The Conversation object"
{
  "id": "e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0",
  "organization_id": "6db1e3f5-9b7f-4f2b-8be1-0f1e1d7d7d8c",
  "type": "patient",
  "title": "Jane Doe",
  "patient": {
    "id": "5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77",
    "name": "Jane Doe"
  },
  "phone_number": {
    "number": "+15125550100",
    "team": "Front desk"
  },
  "channel": "sms",
  "created_at": "2026-09-21T15:04:05Z",
  "last_message_at": "2026-09-21T15:04:05Z",
  "unread_count": 0,
  "seen_at": null,
  "messages_in_range": null,
  "latest_message": null
}
```
