Skip to main content
Auth. HMAC v1 or bearer token — see Authentication. Status. Live · Idempotent: Yes when message.idempotency_key is supplied.
Creates an iMessage group and returns a Chert chat.id. Use that chat.id for follow-up messages, history, typing, mark-read, reactions to messages, and group operations. Group creation uses the same route as direct chat creation: send POST /api/v1/chats with 2-31 recipients in to.

​
Request

POST /api/v1/chats 
curl -X POST https://console.trychert.com/api/v1/chats \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15555550100",
    "to": ["+14155551234", "+14155559876"],
    "message": {
      "subject": "Launch follow-up",
      "parts": [
        { "type": "text", "value": "Starting this group here." }
      ],
      "idempotency_key": "group-launch-follow-up-001"
    }
  }'
Use a text-only first message when creating a group. Send media attachments or rich links afterward with POST /api/v1/chats/{id}/messages.

​
Response

{
  "chat": {
    "id": "0f2d3c1a-8b4e-4f6a-90d2-1a3b4c5d6e7f",
    "display_name": "Launch follow-up",
    "handles": [
      { "service": "imessage", "address": "+14155551234" },
      { "service": "imessage", "address": "+14155559876" }
    ],
    "is_group": true,
    "service": "imessage",
    "health_score": 87,
    "created_at": "2026-05-01T12:00:00Z"
  },
  "message": {
    "id": "46eb1003c8b54b7ea8f1c2b03e9a7d12",
    "chat_id": "0f2d3c1a-8b4e-4f6a-90d2-1a3b4c5d6e7f",
    "parts": [{ "type": "text", "value": "Starting this group here." }],
    "status": "sent",
    "direction": "outbound",
    "created_at": "2026-05-01T12:00:00Z",
    "delivered_at": null,
    "read_at": null,
    "service": "imessage"
  }
}

​
Body

​
from
string
required
Sender phone number from Phone numbers.
​
to
string[]
required
2-31 E.164 phone numbers.
​
message.parts
object[]
required
First group-create message parts. Use one text part for the initial group creation.
​
message.subject
string
Optional group display name.
​
message.idempotency_key
string
Optional retry key. Reuse the same key and body to safely retry the create call.

​
Response fields

​
chat.id
string
Chert chat id for this group. Use it with /api/v1/chats/{id}/messages and group-management routes.
​
chat.handles
object[]
Known group participant handles. This is useful for display and debugging, but the durable group identity is the Chert chat.id.
​
message.id
string
Message id for the first outbound group message. Use this id with message-scoped routes such as reactions.

​
Externally-created groups

If a Chert-managed number is added to a group outside the API, Chert creates a chat.id for that group when the number receives the first group event. The group is identified internally by the upstream group conversation key, then decorated with the participant handles and display name that are available on the event. This means silent membership changes are not visible until a message, reaction, or other group event reaches the Chert line.

​
Errors

CodeHTTPWhen
1001400Missing from, to, or message.parts.
1003400Invalid phone number.
2006403from is not assigned to this tenant.
4001502Downstream delivery failed.
1006422More than 31 recipients.
4099501Group creation included media/rich links in the first message.
See the full error code reference.

​
See also