group.create
Start a new group chat with two or more participants and an opening message.
POST /v1/commands/group.createCreates a group chat and sends its first message in one operation. iMessage has no concept of an empty group, so the opening message is required.
Routing path: admin. Idempotency-Key is ignored — see the warning
below.
Target
Prop
Type
Payload
Prop
Type
Request
curl $MAPIER_BASE_URL/v1/commands/group.create \
-H "Authorization: Bearer $MAPIER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"target": {
"kind": "new_group",
"participantExternalIds": ["+14155550100", "+14155550111"]
},
"payload": { "firstMessage": "kickoff" }
}'Retrying this request creates a second group. The admin path mints a fresh identity per call,
so an Idempotency-Key header is accepted and ignored. If a group.create times out, wait for
the settlement on the stream before deciding whether to retry.
Response
{ "commandId": "cmd-5", "status": "queued", "disposition": "queued" }The settlement carries the new group's conversationId, which is how you
address it afterwards:
{
"commandId": "cmd-5",
"logicalActionId": "cmd-5",
"status": "succeeded",
"errorCode": null,
"conversationId": "a0000000-0000-4000-8000-000000000002"
}conversationId is resolved on a best-effort basis after the group is created, and is omitted
if it could not be resolved in time. Handle its absence: if it is missing, the group still exists,
and its id will arrive with the first inbound message in it.
Errors
| Status | Code | Cause |
|---|---|---|
400 | group_create_requires_new_group_target_and_firstMessage | Wrong target kind, or no firstMessage |
422 | (varies) | A participant address failed validation |
503 | no_live_connector | No Mac available |
Settlement failures: gateway_rejected when iMessage refuses the group,
group_content_unverified when creation could not be confirmed.
Capabilities
Requires command.group_create.v1.