> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychert.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Group texting on Free and Shared lines

> Create a text group with verified recipients on an enabled shared line.

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.

> [!NOTE]
>
> 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

| Plan | Recipient requirements | Outbound usage |
| - | - | - |
| Free | Every recipient must be verified or joined to this project on this line and must have sent it an individual text within the last 24 hours. | One message unit per recipient for each group text. |
| Shared | Every recipient must be verified or joined to this project on this line with current routing access. | One message unit per recipient for each group text. |

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](https://docs.trychert.com/api/group-chats/create.md) 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](https://docs.trychert.com/facetime/authentication.md#project-keys) 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`

```bash cURL theme={null}
curl -X POST https://facetime.trychert.com/api/v1/shared-groups \
  -H "Authorization: Bearer $CHERT_API_KEY" \
  -H "X-Chert-Project-Id: $CHERT_PROJECT_ID" \
  -H "Idempotency-Key: group-create-001" \
  -H "Content-Type: application/json" \
  -d '{
    "line_id": "30000000-0000-4000-8000-000000000001",
    "recipients": ["+12125550100", "+12125550101", "+12125550102"],
    "text": "group message test",
    "consent_confirmed": true
  }'
```

```js Node.js theme={null}
const response = await fetch("https://facetime.trychert.com/api/v1/shared-groups", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CHERT_API_KEY}`,
    "X-Chert-Project-Id": process.env.CHERT_PROJECT_ID,
    "Idempotency-Key": "group-create-001",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    line_id: process.env.CHERT_LINE_ID,
    recipients: ["+12125550100", "+12125550101", "+12125550102"],
    text: "group message test",
    consent_confirmed: true,
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(JSON.stringify(result));
console.log(result.data.group_id);
```

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://facetime.trychert.com/api/v1/shared-groups",
    headers={
        "Authorization": f"Bearer {os.environ['CHERT_API_KEY']}",
        "X-Chert-Project-Id": os.environ["CHERT_PROJECT_ID"],
        "Idempotency-Key": "group-create-001",
    },
    json={
        "line_id": os.environ["CHERT_LINE_ID"],
        "recipients": ["+12125550100", "+12125550101", "+12125550102"],
        "text": "group message test",
        "consent_confirmed": True,
    },
    timeout=150,
)
response.raise_for_status()
print(response.json()["data"]["group_id"])
```

Replace the example line and phone numbers with your enabled line and eligible,
consenting recipients. Keep the API key on your server.

**line\_id** `string` *required*

UUID of the active shared line assigned to your project.

**recipients** `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.

**text** `string` *required*

Nonblank text of up to 4,000 characters.

**consent\_confirmed** `boolean` *required*

Must be `true` after all participants have agreed to group texting.

## Response

```json 202 Accepted theme={null}
{
  "data": {
    "group_id": "40000000-0000-4000-8000-000000000001",
    "message_id": "50000000-0000-4000-8000-000000000001",
    "state": "submitted"
  },
  "request_id": "60000000-0000-4000-8000-000000000001"
}
```

`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`

```bash theme={null}
curl -X POST "https://facetime.trychert.com/api/v1/shared-groups/$GROUP_ID/messages" \
  -H "Authorization: Bearer $CHERT_API_KEY" \
  -H "X-Chert-Project-Id: $CHERT_PROJECT_ID" \
  -H "Idempotency-Key: group-followup-001" \
  -H "Content-Type: application/json" \
  -d '{"text":"Thanks for joining."}'
```

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`.

```bash theme={null}
curl "https://facetime.trychert.com/api/v1/shared-groups/$GROUP_ID/messages" \
  -H "Authorization: Bearer $CHERT_API_KEY" \
  -H "X-Chert-Project-Id: $CHERT_PROJECT_ID"
```

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

| Code | HTTP | What to do |
| - | - | - |
| `invalid_request` | 422 | Check fields, UUIDs, distinct phone numbers, text length and consent. |
| `shared_group_invalid` | 422 | Exclude the sending line from the recipient list and confirm valid group input. |
| `shared_groups_disabled` | 409 | Confirm that group access is enabled and unexpired for this project and line. |
| `recipient_not_verified` | 403 | Verify or join every recipient on this project and line. |
| `shared_reply_window_closed` | 403 | On a Free trial, have each phone send an individual text to the line. |
| `shared_group_limit` | 429 | Your project has reached its group limit on this line. Send follow-ups to an existing `group_id` instead of creating a group. |
| `shared_group_conflict` | 409 | This recipient set already has a group on this line, or the idempotency key belongs to another request. Use your existing `group_id`, or a new key for a new request. If another project owns the set, text each phone on its own. |
| `shared_group_suspended` | 409 | The group is suspended after a membership change or a failed pre-send check. Stop sending to it and text each phone on its own. |
| `shared_group_not_found` | 404 | Check the group ID and project context. |
| `shared_group_unconfirmed` | 409 | An earlier message in this group is still `dispatching` or `unknown`. Read history to see whether it arrived. New group messages stay blocked until it resolves. |
| `shared_group_unavailable` | 502 | A pre-send group check failed and no text was sent. The group can be suspended as a result. Text each phone on its own instead. |
| `shared_group_outcome_unconfirmed` | 502 | The send outcome is uncertain. Save the returned IDs and request ID, then read history to check whether the text arrived. Do not resend with a new idempotency key. |

> [!WARNING]
>
> 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

* [Project API keys](https://docs.trychert.com/facetime/authentication.md#project-keys)
* [Dedicated Messaging API groups](https://docs.trychert.com/api/group-chats/create.md)
* [FaceTime group calls](https://docs.trychert.com/facetime/group-calls.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.