group.update

POST /v1/commands/group.update

Renames an iMessage group chat, or adds or removes one member. One action per command. It is done only in a group chat: a conversation the transport reported as a group when it first saw it.

Honours Idempotency-Key: on a live line a retry under the same key adopts the first command rather than making the change twice. A test line has no group chat, so there every well-formed call is refused before a key is adopted — see In test.

Target

A group's conversationId reaches you on the message frames from the group: every message someone writes there arrives under the group's own id, with isGroup: true.

Each of these is 422 validation_failed at target.conversationId before anything is sent:

• a conversation with one person;
• a conversation the transport has not named yet;
• in place of a conversation, the address of someone this project has already exchanged messages with.

An address this project has never exchanged messages with is refused at the field you wrote it at, as for every command done in a conversation.

Payload

One action, at payload.action.

Each of these is 422 validation_failed before anything is written:

• no action, or one that is not rename, add_participant or remove_participant, at payload.action;
• a name that is missing, blank, over 128 characters or holds an ASCII control character, at payload.name;
• an address the channel cannot read, or one with an ASCII control character, over 512 characters or not in composed Unicode (NFC), at payload.participantExternalId;
• any key the action does not take, at that key (payload.<key>).

rename

{ "action": "rename", "name": "Trip planning" }

add_participant and remove_participant

{ "action": "add_participant", "participantExternalId": "+14155550122" }

One person per command. The platform reads the address the way the channel reads one — a phone number to E.164, an email lower-cased — and sends it in that canonical form.

Adding someone already in the group, or removing someone who is not in it, is accepted and then settles failed with command_claim_invalid. The transport judges that against the members as it last saw them.

What comes back

At once, beside the refusals above:

• 409 conflict with details.reason: "group_has_no_messages_yet" — an add or a remove into a group the transport has seen no message in yet.
• 503 upstream_unavailable with details.reason: "connector_unavailable" — the line's device is offline.

Otherwise 202, then one command frame on the response stream:

• succeeded — the device read the change back.
• failed with command_claim_invalid — an add of someone already in the group, or a remove of someone who is not.
• failed with stale_target — the group was addressed right after its membership changed, before its next message. Until that message arrives, a group.update, a group.leave or a message sent into the group settles this way. Wait for the next message frame from the group, then send again under a new Idempotency-Key.
• failed with gateway_rejected — the device refused the change before making it. A removal that would leave the group smaller than Apple allows is one.
• failed with capability_constraint_violation, failureClass: capability — an add or a remove on a device that has not announced member changes. Nothing changes.
• expired with command_expired_before_execution — the transport's sending was paused: it accepted the command and held it, and the command's time ran out before sending resumed. Nothing changed.
• ambiguous with group_update_unverified — the device sent the change and could not read it back. It may or may not have happened. Check the group's name or members on a phone in it before you send the change again.

In test

A test line has no group chat: the sandbox files none, so no conversation there is one. A well-formed group.update on a test key is 422 validation_failed at target.conversationId, never a 202. A malformed payload is refused at its field there too, as on a live line. To see a change land, use a live line.

Request

curl https://api.mapier.ai/v1/commands/group.update \
  -H "Authorization: Bearer $MAPIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rename-trip-planning-1" \
  -d '{
    "target": {
      "kind": "conversation",
      "conversationId": "a0000000-0000-4000-8000-000000000002"
    },
    "payload": { "action": "rename", "name": "Trip planning" }
  }'

Response

{
  "commandId": "cmd-6",
  "status": "queued",
  "disposition": "queued",
  "lineId": "0192a7b0-3e4f-7051-8c6d-7e8f9a0b1c2d",
  "lineSelection": "reused_active_chat"
}

Then, on the response stream:

{
  "commandId": "cmd-6",
  "logicalActionId": "rename-trip-planning-1",
  "status": "succeeded",
  "errorCode": null,
  "conversationId": "a0000000-0000-4000-8000-000000000002",
  "type": "group.update",
  "messageId": null,
  "externalId": null,
  "namePhoto": null,
  "projectId": "b0000000-0000-4000-8000-000000000002",
  "environment": "live",
  "failureClass": null
}

Errors

A command answers the one set of HTTP refusals POST /v1/commands/{type} publishes, so that table is the one to handle. What is particular to this type:

• 422 validation_failed at target.conversationId for a conversation with one person, one the transport has not named, or the address of someone this project has already exchanged messages with, in place of a conversation — and, on a test line, for every well-formed call.
• 422 validation_failed at payload.action, payload.name, payload.participantExternalId or payload.<key>, as above.
• 409 conflict with details.reason: "group_has_no_messages_yet" for an add or a remove into a group the transport has seen no message in yet.
• 503 upstream_unavailable with details.reason: "connector_unavailable" while the line's device is offline.
• 404 unsupported_command with reason: not_on_channel on a line of any other channel.

Settlement codes you will see for this command: command_claim_invalid, stale_target, gateway_rejected, capability_constraint_violation, command_expired_before_execution and group_update_unverified. See Error codes.

Related