---
title: "Start an iMessage group chat"
method: POST
path: "/v1/imessage/groups"
tags: ["iMessage"]
---

# Start an iMessage group chat

`POST /v1/imessage/groups`

Creates a group chat from one of your senders and sends its first
message. The provider processes it asynchronously: the response carries
the request id, and the thread appears in the inbox (with its group
conversation id) on the first webhook. Starting a group counts as
messaging new contacts, so the sender needs the provider's
init-conversations add-on and the same sending intervals apply; without
it the request fails with 409 `recipient_must_message_first`. WhatsApp
groups need a `name`.

## Request body

- object
  - `accountId` string, required — The iMessage account (sender) that opens the group
  - `contacts` string[], required — Participant handles (E.164 phones or iMessage emails)
  - `text` string, required — The first message
  - `name` string — Group name (required for WhatsApp groups)
  - `channel` 'imessage' | 'sms' | 'rcs' | 'whatsapp'

## Response `202`

Group creation accepted

- object
  - `success` boolean
  - `requestId` string — The provider's request id (not the group id)

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `404` — Account not found
- `409` — The sender cannot start conversations (code: recipient_must_message_first)

## Changes

- **2026-09-25** `2c04683ce694` — 4 info
  - added the optional property `details/adAccountId` to the response with the `400` status
  - added the optional property `details/createdObjects` to the response with the `400` status
  - added the optional property `details/stage` to the response with the `400` status
  - added the optional property `details/unconfirmedWrite` to the response with the `400` status
- **2026-09-21** `339f59df69dd` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/imessage/groups/post.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) · [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/b2325332041a?raw)