group.leave

POST /v1/commands/group.leave

Takes the line out of an iMessage group chat. It is done only in a group chat: a conversation the transport reported as a group when it first saw it. Takes no arguments: payload is {} or absent.

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

Target

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

None. Any key in payload is 422 validation_failed at that key (payload.<key>) before anything is written.

What comes back

At once, beside the refusals above: 503 upstream_unavailable with details.reason: "connector_unavailable" while the line's device is offline.

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

• succeeded — the device sent the leave without an error. That means sent, not proven: nothing reads a leave back. In a group of fewer than 4 people, the line among them, the leave is sent, changes nothing and still settles succeeded — Apple lets a member leave only a group of at least 4.
• ambiguous with group_leave_unverified — the device's sending errored, so the line may still be in the group.
• failed with stale_target — the group was addressed right after its membership changed, before its next message. Wait for the next message frame from the group, then send the leave again under a new Idempotency-Key.
• expired with command_expired_before_execution — the transport's sending was paused: it accepted the leave and held it, and the command's time ran out before sending resumed. Nothing changed.

Treat succeeded and ambiguous alike: neither proves the line has left the group. After either, check on a phone in the group before you send a leave again.

In test

A test line has no group chat: the sandbox files none, so no conversation there is one. A well-formed group.leave on a test key is 422 validation_failed at target.conversationId, never a 202.

Request

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

Response

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

Then, on the response stream, the settlement of a leave whose sending errored:

{
  "commandId": "cmd-7",
  "logicalActionId": "leave-trip-planning",
  "status": "ambiguous",
  "errorCode": "group_leave_unverified",
  "conversationId": "a0000000-0000-4000-8000-000000000002",
  "type": "group.leave",
  "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.<key> for any key in the payload.
• 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: group_leave_unverified, stale_target and command_expired_before_execution. See Error codes.

Related