The Conversation object
Conversations with patients, one per patient and clinic phone number. Patient API.
Attributes
idUUIDRequiredUnique ID of the conversation.
organization_idUUIDRequiredOrganization the conversation belongs to.
typepatient, direct, group, broadcastRequiredA conversation with a patient, or a staff direct message, group, or broadcast. API keys see only patient.
titlestringRequiredThe conversation’s name as the user sees it in BloomText.
patientPatientRef or nullThe patient, for patient conversations. Null otherwise.
Show child attributes
idUUIDRequiredID of the patient.
namestringRequiredThe patient’s name, or their phone number if they have no name yet.
phone_numberPhoneNumberRef or nullThe clinic phone number, for patient conversations by SMS. Null otherwise.
Show child attributes
numberstringRequiredThe phone number.
teamstringRequiredThe team it belongs to.
channelsecure, sms, nullHow the patient receives messages, for patient conversations. Null otherwise.
created_attimestampRequiredWhen the conversation was created.
last_message_attimestamp or nullRequiredWhen the latest message was sent. Null for a conversation with no messages.
unread_countintegerRequiredAlways 0 with an API key, which has no read state. With OAuth, messages the person hasn’t read.
seen_attimestamp or nullRequiredAlways null with an API key. With OAuth, when the person last read the conversation.
messages_in_rangeinteger or nullOn List conversations with after or before: how many of its messages fell in the range. Null otherwise.
latest_messageMessage or nullOn List conversations: the conversation’s latest message in the range. Null otherwise.
Show child attributes
idUUIDRequiredUnique ID of the message.
conversationConversationRefRequiredThe conversation a message belongs to.
Show child attributes
idUUIDRequiredID of the conversation.
titlestringRequiredThe conversation’s name as the user sees it.
senderSenderRequiredWho sent a message.
Show child attributes
idUUIDRequiredID of the sender.
namestringRequiredThe sender’s display name.
kindstaff, patient, api_key, api_identityRequiredA 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).
patientPatientRef or nullRequiredThe patient in the conversation, for patient conversations. Null otherwise.
Show child attributes
idUUIDRequiredID of the patient.
namestringRequiredThe patient’s name, or their phone number if they have no name yet.
channelapp, secure, smsRequiredHow the message traveled: inside BloomText (app), by secure link, or by plain SMS.
phone_numberPhoneNumberRef or nullThe clinic phone number, for SMS messages. Null otherwise.
Show child attributes
numberstringRequiredThe phone number.
teamstringRequiredThe team it belongs to.
deliveryDelivery or nullDelivery status, for messages sent to a patient. Null otherwise.
Show child attributes
statusqueued, sent, delivered, failed, undelivered, rejected, consent_requestedRequiredWhere 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_codestring or nullWhy 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.
detailstring or nullWhat error_code means, in plain English. Null when there’s no error.
updated_attimestampRequiredWhen the status last changed. Carrier reports arrive within minutes.
recipientsarray of objectFor a message to several patients (a group conversation), each one’s delivery. Absent for one patient.
campaign_idUUID or nullThe campaign that sent this message. Null otherwise.
created_attimestampRequiredWhen the message was sent.
edited_attimestamp or nullWhen the message was last edited. Null if it never was.
typetext, fileRequiredWhether the message carries text or a file.
bodystring or nullMessage text. Null for file messages.
fileFileReference or nullFile metadata. Null for text messages.
Show child attributes
idUUIDRequiredUnique ID of the file.
namestringRequiredOriginal file name.
mimestring or nullMIME type, such as application/pdf.
size_bytesinteger or nullFile size in bytes.
reply_to_message_idUUID or nullMessage this is a reply to. Null for top-level messages.
unreadbooleanRequiredAlways false with an API key, which has no read state. With OAuth, whether the connected person hasn’t read it.
sent_viaApp or nullNull 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.
Show child attributes
client_idstringRequiredYour app’s OAuth client ID.
namestringRequiredYour app’s name as users and staff see it.
Endpoints
| Method | Path | Endpoint |
|---|---|---|
| GET | /patient-conversations | List patient conversations |
| GET | /patient-conversations/{conversationId} | Retrieve a patient conversation |
| GET | /me/conversations | List conversations |
| GET | /me/conversations/{conversationId} | Retrieve a conversation |