| Term | Meaning |
|---|---|
| Workspace | Your Blujay account. An API key belongs to one workspace and can see everything in it. |
| Phone number | A Blujay number your workspace messages from. It has a plan, a live send_status, and on Dedicated and AI Agent plans, limits, queue and health_status. |
| Plan | Free Plan, Dedicated or AI Agent. Decides who a number can message and which features it can use. See Plans. |
| Shared number | The Free Plan number, shared with other Free Plan workspaces. access_type: "shared". |
| Dedicated number | A number that is yours alone. access_type: "dedicated". Both Dedicated and AI Agent numbers are dedicated numbers. |
| Contact | A person saved in your workspace, with a phone number and optionally an email, name, tags, stage and assigned team member. |
| Verified contact | On the Free Plan, a person who texted your shared number first and was verified in Blujay. Only verified contacts can be messaged. |
| New contact | Someone a phone number has never texted before. The daily new-contact limit counts these. People who text you first never count. |
| Recipient | Who a message goes to: the to addresses on a send. |
| Participant | A person in a group chat. Your own numbers in the group are listed separately, in the chat’s phone_numbers. |
| Active chat | A chat Blujay still treats as current. Typing, read receipts, replies and effects need an active chat; otherwise they return UNSUPPORTED_CHAT_OPERATION. See Group chats. |
| Established iMessage group | A group chat whose first message has gone out over iMessage. Rename, add, remove, replies and effects need one. See Group chats. |
| Sender | On an inbound group message, the participant who wrote it (sender object). |
| Chat | A conversation on one of your numbers. direct with one person, or group with several. A chat has one chat_id for its whole life. |
| Direct chat | A chat between one of your numbers and one person. |
| Group chat | A chat between one of your numbers and two or more people. iMessage groups support rename, add and remove; see Group chats. |
| Message | One message in a chat, inbound or outbound, with a status. |
| Part | What a message contains: text, link, media or vcard. A message is a list of parts in order. |
| Attachment | A file you uploaded once, referenced by attachment_id, or a file someone sent you. |
| Contact card | A vCard you saved in Blujay and can send as a native contact card. Not the same as your number’s own Name & Photo, which the API doesn’t manage today. |
| Service | How a message travels: iMessage, RCS or SMS. Webhook payloads use lowercase. |
| Auto | Leaving out preferred_service. Blujay picks iMessage when the person can receive it, otherwise RCS or SMS. |
| Degradation | Something Blujay could not deliver because the message went out as RCS or SMS, for example an effect. Listed in degradations. |
| Capability check | POST /v1/capability/evaluate_service: whether a number can receive iMessage, RCS or SMS. |
| Reply | A text or a tapback from the contact. Replies lift the pre-reply rules and restart the 6-text count. Calls never count. |
| Pre-reply rules | The rules on sends before a contact replies: no links, no attachments, 300 characters. See Sending rules. |
| Opt-out | A record that a phone number or email must not be messaged. Sends return RECIPIENT_SUPPRESSED. |
| Idempotency key | The Idempotency-Key header that makes a retried write safe. See Idempotency. |
| Trace ID | trace_id in every response body and the X-Trace-ID header. Identifies one request. Include it when you contact support. |
| Webhook subscription | An HTTPS address where Blujay sends events, with the event types and phone numbers you chose. |
| Event | One thing that happened, delivered to a subscription with an event_id. |
| Webhook version | The date-named payload shape a subscription is pinned to. See Versions. |
| Workflow | An automation built in Blujay. The API can enroll a contact in one. |
Next steps
Key concepts
How the resources fit together.
Plans
What each plan can do.