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 ashello, 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 withfacetime: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
At least two distinct E.164 phone numbers with current verification and routing
access for this project and line. Order is normalized before storage.
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
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.
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
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.

