> ## 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. # Add a group participant > Adds a phone number or email address to an active iMessage group chat. One of your Blujay numbers in the group makes the change. If more than one of your numbers is in the group, set `from_phone_number_id` to choose which one. Adding someone who is already in the group returns `200` with `status: already_active`. Send an `Idempotency-Key` so you can safely retry. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/chats/{chat_id}/participants openapi: 3.1.0 info: title: Blujay API version: 1.0.0 description: >- The Blujay API lets you send and receive iMessage, RCS and SMS messages from your Blujay phone numbers, manage contacts, and receive real-time webhooks. Every response uses the same JSON envelope and carries a `trace_id` you can share with support. Authenticate with your workspace API key. servers: - url: https://api.blujay.io description: Production security: - PublicApiKey: [] tags: - name: Auth description: Check which workspace and credential a request is using. - name: Chats description: >- Direct and group conversations between your Blujay numbers and your contacts. - name: Messages description: Send, read, edit, unsend and retry messages. - name: Phone Numbers description: >- Your Blujay numbers, whether each can send right now, and their live sending limits. - name: Capability description: >- Check whether a phone number can be reached by iMessage, RCS or SMS before you send. - name: Contacts description: Create, find, update, tag, assign and opt out contacts. - name: vCards description: >- Saved contact cards that you can send in a message. Recipients get a native contact card over iMessage, SMS or RCS. - name: Team Members description: People in your workspace you can assign contacts to. - name: Workflows description: Enroll contacts in workflows you start manually. - name: Attachments description: >- Upload files once and reuse them in messages, or download files from messages. - name: Webhooks description: Subscribe to events, inspect delivery attempts and verify signatures. paths: /v1/chats/{chat_id}/participants: post: tags: - Chats summary: Add a group participant description: > Adds a phone number or email address to an active iMessage group chat. One of your Blujay numbers in the group makes the change. If more than one of your numbers is in the group, set `from_phone_number_id` to choose which one. Adding someone who is already in the group returns `200` with `status: already_active`. Send an `Idempotency-Key` so you can safely retry. operationId: addPublicChatParticipant parameters: - $ref: '#/components/parameters/ChatId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicGroupParticipantMutationInput' examples: addParticipant: value: handle: '+15555550123' from_phone_number_id: phone_abc123 responses: '200': description: >- The person was already in the group, or this `Idempotency-Key` was already used for the same request. headers: X-Trace-ID: $ref: '#/components/headers/XTraceID' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: - data properties: data: $ref: '#/components/schemas/AcceptedGroupParticipantMutation' '202': description: The add was accepted. headers: X-Trace-ID: $ref: '#/components/headers/XTraceID' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: - data properties: data: $ref: '#/components/schemas/AcceptedGroupParticipantMutation' examples: accepted: value: status: success data: chat_id: chat_abc123 operation: participant_add status: accepted participant: handle: '+15555550123' type: phone status: active from_phone_number_id: phone_abc123 trace_id: trc_8f2a1c0e4b7d timestamp: '2026-10-14T22:00:00.000Z' '400': description: >- The request is invalid, more than one of your numbers is in the group and `from_phone_number_id` is missing (`PHONE_NUMBER_REQUIRED`), or the chat isn't an active iMessage group (`UNSUPPORTED_CHAT_OPERATION`). headers: X-Trace-ID: $ref: '#/components/headers/XTraceID' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/IdempotencyConflict' '503': $ref: '#/components/responses/PhoneNumberUnavailable' security: - PublicApiKey: [] components: parameters: ChatId: name: chat_id in: path required: true schema: $ref: '#/components/schemas/ChatId' IdempotencyKey: name: Idempotency-Key in: header required: false schema: type: string minLength: 1 maxLength: 255 description: > A unique value you choose (1–255 characters) that makes this request safe to retry. Send the same key with the same request and Blujay returns the original response instead of doing the work again. Use a new key for each new action. Blujay keeps keys for at least 24 hours. Keys are separate for each API key and each route family (for example every `POST /v1/chats/{chat_id}/messages` shares one). Reusing a key with a different request returns `409 IDEMPOTENCY_REQUEST_MISMATCH`. Sending it while the first request is still running returns `409 IDEMPOTENCY_IN_PROGRESS`; retry shortly. schemas: PublicGroupParticipantMutationInput: type: object additionalProperties: false required: - handle properties: handle: type: string examples: - '+15555550124' minLength: 1 description: The participant's phone number or email address. from_phone_number_id: $ref: '#/components/schemas/PhoneNumberId' description: >- `from_phone_number_id` picks which of your numbers makes the change. It is optional only when one of your numbers is in the group. SuccessEnvelope: type: object description: Wraps every successful response. The result is in `data`. required: - status - trace_id - timestamp properties: status: type: string enum: - success trace_id: $ref: '#/components/schemas/TraceId' timestamp: type: string examples: - '2026-10-14T17:01:00.000Z' format: date-time client_request_id: type: string description: >- Your `X-Request-ID` header value, echoed back when you send one. Not included on the send responses (`POST /v1/chats`, `POST /v1/chats/{chat_id}/messages`, `POST /v1/messages/{message_id}/retry`); keep your own mapping from your request ID to the returned message ID there. AcceptedGroupParticipantMutation: type: object additionalProperties: false required: - chat_id - operation - status - participant - from_phone_number_id properties: chat_id: $ref: '#/components/schemas/ChatId' operation: type: string enum: - participant_add - participant_remove status: type: string enum: - accepted - already_active - already_removed description: >- `already_active` for an add of someone already in the group, `already_removed` for a removal of someone who already left; neither contacts the phone. participant: type: object additionalProperties: false required: - handle - type - status properties: handle: type: string examples: - '+15555550124' type: type: string enum: - phone - email status: type: string enum: - active - left from_phone_number_id: $ref: '#/components/schemas/PhoneNumberId' ErrorEnvelope: type: object description: >- Wraps every error response. Branch on `error.code`, and include `trace_id` when you contact support. required: - status - error - trace_id - timestamp properties: status: const: error error: $ref: '#/components/schemas/PublicError' trace_id: $ref: '#/components/schemas/TraceId' timestamp: type: string examples: - '2026-10-14T17:01:00.000Z' format: date-time client_request_id: type: string description: Your `X-Request-ID` header value, echoed back when you send one. ChatId: type: string examples: - chat_abc123 pattern: ^chat_[A-Za-z0-9_-]+$ PhoneNumberId: type: string examples: - phone_abc123 pattern: ^phone_[A-Za-z0-9_-]+$ TraceId: type: string examples: - trc_8f2a1c0e4b7d pattern: ^trc_[A-Za-z0-9_-]+$ PublicError: type: object required: - code - message - type - http_status - retryable - doc_url - details properties: code: type: string description: Stable, machine-readable error code. Branch on this value. examples: - RATE_LIMIT_EXCEEDED - QUEUE_UNAVAILABLE - FEATURE_NOT_ENABLED message: type: string description: Human-readable explanation. It can change, so don't parse it. type: type: string description: Broad error category. examples: - validation - auth - idempotency - rate_limit - queue - feature_gate http_status: type: integer description: The HTTP status code of the response. enum: - 400 - 401 - 403 - 404 - 409 - 413 - 415 - 422 - 429 - 500 - 502 - 503 retryable: type: boolean description: Whether sending the same request again later can succeed. doc_url: type: string format: uri description: Link to documentation for this error code. details: type: array description: >- Extra structured context, such as the fields that failed validation or the limit you hit. items: type: object additionalProperties: true retry_after: type: integer minimum: 1 description: >- Seconds to wait before retrying. Also sent as the `Retry-After` header. reset_at: type: string examples: - '2026-10-14T17:01:00.000Z' format: date-time description: When the limit you hit resets. headers: XTraceID: description: >- Unique ID for this request. It matches `trace_id` in the body. Include it when you contact Blujay support. schema: $ref: '#/components/schemas/TraceId' RetryAfter: description: Seconds to wait before retrying. schema: type: integer minimum: 1 responses: NotFound: description: The resource doesn't exist or isn't in your workspace. headers: X-Trace-ID: $ref: '#/components/headers/XTraceID' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' IdempotencyConflict: description: > The `Idempotency-Key` conflicts with an earlier request: - `IDEMPOTENCY_REQUEST_MISMATCH`: the key was already used for a different request. - `IDEMPOTENCY_KEY_MISMATCH`: on sends, the `Idempotency-Key` header and `message.idempotency_key` don't match. - `IDEMPOTENCY_IN_PROGRESS`: a request with this key is still running. Retry shortly. headers: X-Trace-ID: $ref: '#/components/headers/XTraceID' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: mismatch: value: status: error error: code: IDEMPOTENCY_REQUEST_MISMATCH message: Idempotency key was reused with a different request shape type: idempotency http_status: 409 retryable: false doc_url: https://docs.blujay.io/errors/idempotency-request-mismatch details: [] trace_id: trc_8f2a1c0e4b7d timestamp: '2026-10-14T00:00:00.000Z' keyMismatch: value: status: error error: code: IDEMPOTENCY_KEY_MISMATCH message: Idempotency key header and body value do not match type: idempotency http_status: 409 retryable: false doc_url: https://docs.blujay.io/errors/idempotency-key-mismatch details: [] trace_id: trc_8f2a1c0e4b7d timestamp: '2026-10-14T00:00:00.000Z' inProgress: value: status: error error: code: IDEMPOTENCY_IN_PROGRESS message: An idempotent request with this key is already in progress type: idempotency http_status: 409 retryable: true doc_url: https://docs.blujay.io/errors/idempotency-in-progress details: [] trace_id: trc_8f2a1c0e4b7d timestamp: '2026-10-14T00:00:00.000Z' PhoneNumberUnavailable: description: >- The messaging network couldn't accept the request right now (`PHONE_NUMBER_UNAVAILABLE`). Nothing was changed. Retry after `Retry-After` seconds. headers: X-Trace-ID: $ref: '#/components/headers/XTraceID' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: phoneNumberUnavailable: value: status: error error: code: PHONE_NUMBER_UNAVAILABLE message: This service is temporarily unavailable type: phone_number http_status: 503 retryable: true doc_url: https://docs.blujay.io/errors/phone-number-unavailable details: [] retry_after: 30 trace_id: trc_8f2a1c0e4b7d timestamp: '2026-10-14T00:00:00.000Z' securitySchemes: PublicApiKey: type: http scheme: bearer bearerFormat: blu_... description: > Your workspace API key, sent as `Authorization: Bearer blu_...`. Workspace admins can find it in the Blujay app under **API**. An API key has full access to your workspace and works on every endpoint. There is no test mode: every key sends real messages and changes real data, so keep it secret and use it only from your server. Each API key can make 600 read requests and 120 write requests per minute, plus 60 attachment requests per minute. Over a limit you get `429 RATE_LIMIT_EXCEEDED` with `Retry-After`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.