chat_background.set

POST /v1/commands/chat_background.set

Sets the background of an iMessage conversation, by the background's name at payload.preset. It is done in a conversation with one person that the transport has confirmed is with that one person, or in a group chat it reported.

Honours Idempotency-Key: a retry under the same key adopts the first command rather than setting the background again. A set and a chat_background.remove each take a key of their own — see One key for each command.

Target

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

• a conversation the transport has not named;
• a conversation with one person it has not yet confirmed, with reason: conversation_not_confirmed — send the person a text first;
• 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

The published list of presets is one name long: gradient.

Each of these is 422 validation_failed before anything is sent:

• a preset that is missing or not on that list, at payload.preset;
• any other key, at that key (payload.<key>).

What comes back

At once, beside the refusals above, the transport can answer 503 upstream_unavailable:

• with details.reason: "connector_unavailable" while the line's device is offline;
• with details.reason: "outbound_paused" while the transport's sending is paused.

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

• succeeded — the device read the change back.
• failed with gateway_rejected — the device refused before changing anything: it was busy with another background change, could not find the conversation, or was without what a background change needs at that moment. Nothing changed, and the set can be sent again under a new Idempotency-Key.
• failed with stale_target — a group chat the device could not find among its own with the members the transport last saw. A group addressed right after its membership changed, before its next message, is one.
• failed with capability_not_negotiated — the line's device has not announced that it sets a background. Setting and removing are announced apart.
• expired with command_expired_before_execution — the device did not reach the change in time. Nothing changed.
• ambiguous with chat_background_unverified — the device began the change and could not read it back. It may or may not have been made.

Rarely, a set settles ambiguous with gateway_timeout instead, when the device's own call failed before it could say what it did. Read it as chat_background_unverified.

While a change is under way

A background change lets the line's other waiting commands go first. Once it has started, the transport hands the line's device no other command until the change is read back or given up on. So anything sent meanwhile, into any conversation on the line, waits for it — everything but a typing.start.

What the conversation path carries settles expired too when it waits past that path's expiry: a message into a confirmed conversation or a group chat, a reaction.tapback, a name_photo.share, a poll.vote.

The message a change leaves

On a live line a background set or removed in a conversation with one person also arrives as a message from that person with no text. It arrives whoever made the change: this command, or the person on their own phone.

It is a message frame and a message.received webhook whose text is null. It is stored in the conversation, counted as a received message, and leaves the conversation awaiting a reply in the console until the line next sends.

Nobody wrote anything, so there is nothing to answer. Skip a received message that has no text and no attachment rather than reply to it — see Inbound message events and Webhooks.

In a group chat the line's own change files nothing.

One key for each command

Give a set and a remove a key each. On a live line the transport reads the two as one verb: one Idempotency-Key reused across a set and a remove is answered with the first command and changes nothing more. On a test line the same reuse is 409 conflict with details.reason: "idempotency_key_reused".

In test

A test line carries a set in a conversation with one person and settles it as a live line does. Nothing draws the background, and no message with no text is filed. A test line has no group chat to set one in.

Request

curl https://api.mapier.ai/v1/commands/chat_background.set \
  -H "Authorization: Bearer $MAPIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: background-set-order-2481" \
  -d '{
    "target": {
      "kind": "conversation",
      "conversationId": "a0000000-0000-4000-8000-000000000001"
    },
    "payload": { "preset": "gradient" }
  }'

Response

{ "commandId": "cmd-14", "status": "queued", "disposition": "queued" }

Then, on the response stream:

{
  "commandId": "cmd-14",
  "logicalActionId": "background-set-order-2481",
  "status": "succeeded",
  "errorCode": null,
  "conversationId": "a0000000-0000-4000-8000-000000000001",
  "type": "chat_background.set",
  "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 the transport has not named, one with one person it has not confirmed — with reason: conversation_not_confirmed — or the address of someone this project has already exchanged messages with, in place of a conversation.
• 422 validation_failed at payload.preset or payload.<key>, as above.
• 409 conflict with details.reason: "idempotency_key_reused" on a test line for a key a chat_background.remove used.
• 503 upstream_unavailable with details.reason: "connector_unavailable" while the line's device is offline, or "outbound_paused" while the transport's sending is paused.
• 404 unsupported_command with reason: not_on_channel on a line of any other channel.

Settlement codes you will see for this command: gateway_rejected, stale_target, capability_not_negotiated, command_expired_before_execution, chat_background_unverified and gateway_timeout. See Error codes.

Related