Key concepts

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. 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.
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. 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.
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.
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.
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.
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.
Event	One thing that happened, delivered to your webhook. IDs start with `evt_`. See Events.
Workflow	An automation you build in Blujay. The API can enroll contacts in one. See Workflows.

Every term, including the ones other pages lean on, is in the Glossary.

How a message flows

You send with POST /v1/chats (first message) or POST /v1/chats/{chat_id}/messages (follow-up). Blujay answers 202 Accepted right away.
Blujay checks the sending rules, picks the service and sends from your phone number.
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.
Each change is sent to your webhooks. Replies arrive as message.received. See Receive messages.

Rules that apply everywhere

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

Next steps

Quickstart

Send your first message.

Sending rules

What a message can contain before and after a reply.

Plans

What each plan lets your numbers do.

Glossary

Every term the docs use.

Get started

Messaging

Contacts

Webhooks

Build reliably

Resources

How a message flows

Rules that apply everywhere

Next steps

Quickstart

Sending rules

Plans

Glossary

​How a message flows

​Rules that apply everywhere

​Next steps

Quickstart

Sending rules

Plans

Glossary

How a message flows

Rules that apply everywhere

Next steps