Core concepts

A few ideas explain almost everything about how the API behaves. Read this page once and the rest of the docs will make sense.

Organizations

Everything in BloomText belongs to an organization: a practice, clinic, agency, or health system. An API key is issued to one organization and can never see data from another. Retrieve the organization to confirm which one a key belongs to.

App users

Every API key belongs to an app user, a named member of your organization that represents your software, like “Intake Bot” or “Scheduling Sync”.

• It shows up as the sender of every message it writes, so staff always know what came from an integration.
• It can’t sign in to BloomText or administer the organization.
• It sees only the conversations it has been added to.

Conversations and membership

A conversation is a thread between people in your organization and, often, a patient or family member. Conversations are direct, group, or broadcast.

Membership is the access boundary. Your app user can read and write a conversation only while it’s a participant. Scopes decide what a key can do; membership decides where.

Messages, replies, and reactions

• A message carries either text (body) or a file (file).
• A reply is a message with reply_to_message_id set. List replies returns a message’s thread.
• Reactions are emoji on a message. They have no ID of their own; each is identified by the message, the user, and the emoji.

Broadcasts

A broadcast is a one-to-many campaign your staff send from BloomText. The API lets you read broadcasts and their delivery status. Reading a broadcast never grants access to the conversations it was sent to.

Exports

An export packages a conversation’s history into a file. Exports run asynchronously: start one, then poll it or listen for the export.ready webhook to get a short-lived download URL.

IDs, timestamps, and requests