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

# Key concepts

> The handful of things the Blujay API is built around, and how they fit together.

```mermaid theme={null}
flowchart LR
  W[Workspace] --> P[Phone numbers]
  W --> C[Contacts]
  P --> CH[Chats]
  CH --> M[Messages]
  M --> PT[Parts: text, link, media, contact card]
  W --> WH[Webhook subscriptions]
  M -. events .-> WH
```

| Concept | What it is |
| - | - |
| **Workspace** | Your Blujay account. An API key belongs to one workspace and can see everything in it. IDs start with `workspace_`. |
| **Phone number** | A Blujay number your workspace sends from. Each one has a live sending status, limits and health. See [Phone numbers and limits](/phone-numbers.md). IDs start with `phone_`. |
| **Plan** | What your numbers can do. **Free Plan**: a shared number that can message up to 10 verified contacts. **Dedicated**: your own number with full functionality. **AI Agent**: your own number that only replies to people who text it first. See [Plans](/plans.md). |
| **Contact** | A person saved in Blujay, with a phone number (required when you create one through the API), name, tags, stage and assigned team member. See [Contacts](/contacts.md). IDs start with `contact_`. |
| **Recipient** | Who a message goes to. A recipient doesn't have to be a contact yet; Blujay creates the contact when you start a chat. |
| **Chat** | A conversation on one of your phone numbers: a **direct chat** with one person, or a **group chat** with several **participants**. You start one with its first message. IDs start with `chat_`. |
| **Message** | One message in a chat, inbound or outbound. An outbound message has a `status` that changes as it is sent, delivered and read. IDs start with `msg_`. |
| **Parts** | What a message contains: `text`, a `link`, `media` (a photo, video or file) or a `vcard` contact card. See [Send messages](/messaging/send-messages.md). |
| **Service** | How a message travels: `iMessage` (blue bubbles), or `RCS` and `SMS` (green bubbles). Leave out `preferred_service` (**Auto**) and Blujay chooses, or ask for one. See [iMessage, RCS or SMS](/messaging/choosing-a-service.md). |
| **New contact** | Someone a phone number has never texted before. Each Dedicated number can message a limited number of new contacts a day. See [Phone numbers and limits](/phone-numbers.md#new-contacts-per-day). |
| **Verified contact** | On the Free Plan, a person who texted your number first and was verified in the app. A Free Plan number can message only verified contacts. |
| **Attachment** | A file you upload once and send many times. IDs start with `att_`. See [Media](/messaging/media.md). |
| **Webhook subscription** | An HTTPS address on your server where Blujay sends events, such as new replies and delivery updates. IDs start with `whsub_`. See [Webhooks](/webhooks/overview.md). |
| **Event** | One thing that happened, delivered to your webhook. IDs start with `evt_`. See [Events](/webhooks/events.md). |
| **Workflow** | An automation you build in Blujay. The API can enroll contacts in one. See [Workflows](/workflows.md). |

Every term, including the ones other pages lean on, is in the [Glossary](/glossary.md).

## How a message flows

1. You send with `POST /v1/chats` (first message) or `POST /v1/chats/{chat_id}/messages` (follow-up). Blujay answers `202 Accepted` right away.
2. Blujay checks the [sending rules](/messaging/sending-rules.md), picks the service and sends from your phone number.
3. The message moves through its statuses: `accepted`, `sending`, `sent`, then `delivered` and `read` where the service reports them, or `failed`. Inbound messages have the status `received`. See [Track a message](/messaging/lifecycle.md).
4. Each change is sent to your [webhooks](/webhooks/overview.md). Replies arrive as `message.received`. See [Receive messages](/messaging/receive-messages.md).

## Rules that apply everywhere

* **One envelope.** Every response has `status`, `data` or `error`, `trace_id` and `timestamp`. See [Making requests](/making-requests.md).
* **Safe retries.** Send an `Idempotency-Key` on sends and other changes, and a retry never sends twice. See [Idempotency](/idempotency.md).
* **Stable errors.** Every error has a fixed `code` with its own page. See [Errors](/errors.md).
* **Live only.** There is no test mode; every call acts on your real workspace. See [Authentication](/authentication.md#test-and-live).
* **US numbers only.** Recipients must be US phone numbers.

## Next steps

> **[Quickstart](/quickstart.md)**
>
> Send your first message.

> **[Sending rules](/messaging/sending-rules.md)**
>
> What a message can contain before and after a reply.

> **[Plans](/plans.md)**
>
> What each plan lets your numbers do.

> **[Glossary](/glossary.md)**
>
> Every term the docs use.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.