Skip to main content
Send an iMessage group text from your assigned shared line using your project API key. Save the returned group_id to send follow-ups and read the group’s history. This flow supports an active Free trial or a paid Shared allocation.
Group texting must be enabled for both your project and its assigned line. A line without it answers 409 shared_groups_disabled, so text each phone on its own there. Test sending and replies on your line before relying on it.

Availability by plan

Your allocation and group access must remain active. Existing contact, credit, project and line limits apply. An inbound group text counts once and retains the existing Free trial treatment for inbound credits. Use at least two distinct E.164 phone numbers in recipients, excluding the sending line. This route adds no fixed recipient-count maximum. Request size, contact limits, available usage and iMessage capabilities still bound the request. Three-recipient sending has been tested on an enabled line. This flow supports plain text. Email recipients, SMS fallback, attachments, reactions, renaming and participant changes are outside this group-texting flow. The dedicated Messaging API group guide documents its own authentication and routes.

Prepare the recipients

Each recipient must have current phone verification or join your project on the same line. In the shared messaging page, copy your project’s join phrase. Each phone sends that phrase to the assigned line and waits for the connection confirmation. For a Free trial, each phone then sends a separate ordinary text, such as hello, to open its 24-hour reply window. Sending the join phrase again is not an ordinary text. Make sure every person agrees to join a group and share their phone number and messages with the other participants. consent_confirmed records your application’s attestation of that agreement. Verification alone does not establish group consent.

Create a group

Use a project API key with facetime:write and send your project UUID in X-Chert-Project-Id. Each POST requires an Idempotency-Key of 8–200 characters. Keep the key and request body for recovery. Use a new key for each intentional new message. POST /api/v1/shared-groups
Replace the example line and phone numbers with your enabled line and eligible, consenting recipients. Keep the API key on your server.
string
required
UUID of the active shared line assigned to your project.
string[]
required
At least two distinct E.164 phone numbers with current verification and routing access for this project and line. Order is normalized before storage.
string
required
Nonblank text of up to 4,000 characters.
Must be true after all participants have agreed to group texting.

Response

submitted confirms that Chert received a message submission receipt. It does not confirm delivery to each phone, a read receipt or a reply. message_id identifies this API operation. group_id identifies the project-owned group for follow-ups and history.

Send a follow-up

POST /api/v1/shared-groups/{group_id}/messages
The response uses the same group_id, message_id and state fields. Every recipient’s verification, routing access and any Free trial reply window are checked again. The group has fixed membership. A changed participant set suspends the group. Further group sends and automatic reply routing stop for that group, so text each phone on its own instead.

Read history and replies

GET /api/v1/shared-groups/{group_id}/messages Use a project API key with facetime:read.
The response contains data.group_id, the group state and the newest 50 items. Each item contains id, direction, state, text, created_at and sender_index. For an inbound item, sender_index is a zero-based index into your recipient list sorted in ascending phone-number order. It is null for an outbound item. History is scoped to the authenticated project. Only replies to a group created and owned through this flow are eligible for this history. An existing external group is not automatically imported. Releasing or reassigning a line does not transfer a group’s history to another project.

Errors and uncertain sends

After an uncertain response, do not send the same text with a new idempotency key. An operation may already have reached iMessage. A dispatching or unknown operation blocks further messages until it is reconciled. Repeating a submitted request with the same key returns the existing receipt. Repeating an uncertain operation does not resend it.
Where available, error.details includes group_id, message_id and state for history checks. Chert also refuses an existing nonempty group before its first API text through this flow. Keep ownership records and request keys when diagnosing a failed create.

See also