Auth. HMAC v1 or bearer token — see Authentication.
Status. Live · Idempotent: Yes when
message.idempotency_key is supplied.chat.id. Use that chat.id for follow-up messages, history, mark-read, reactions to messages, and group operations. Typing indicators in group chats are not yet available on every phone line — where unsupported, POST /api/v1/chats/{id}/typing returns 4099 NOT_SUPPORTED for the group instead of applying the indicator.
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
Response
Body
string
required
Sender phone number from Phone numbers.
string[]
required
2-31 E.164 phone numbers or Apple ID email handles.
object[]
required
First group-create message parts. Use one
text part for the initial group creation.string
Optional group display name.
string
Optional retry key. Reuse the same key and body to safely retry the create call.
Response fields
string
Chert chat id for this group. Use it with
/api/v1/chats/{id}/messages and group-management routes.object[]
Known group participant handles. This is useful for display and debugging, but the durable group identity is the Chert
chat.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 achat.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
See the full error code reference.

