Your name and photo

Three commands touch this line's Messages name and photo. They are not interchangeable.

Share is the prompt Messages shows when you start talking to someone new. Without it, the recipient sees whatever their own address book has for your number, which for a new contact is usually only the number itself. Get and set address the line itself, { "lineId": … } with the line's id from GET /v1/whoami — not a conversation.

Sharing it

The target is a direct-message conversation. Groups are not supported, and neither is a bare phone number — you need a conversationId for a conversation the contact has already written into, because that is when the transport names it. Anything else is 422 validation_failed at target.conversationId, before anything is sent. See Addressing a conversation.

The payload is empty: send {}, or leave payload out and the API reads it as {}.

curl https://api.mapier.ai/v1/commands/name_photo.share \
  -H "Authorization: Bearer $MAPIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": {
      "kind": "conversation",
      "conversationId": "a0000000-0000-4000-8000-000000000001"
    },
    "payload": {}
  }'

Like every command but a live group.create, typing.start and message.read, this honours Idempotency-Key, so a retry adopts the original command rather than offering twice — see Idempotency.

How a share settles

The command settles succeeded whether iMessage showed the prompt or declined to — usually because the card has already been shared with that person — and nothing on it tells the two apart. Whether the prompt appears is iMessage's decision. Do not look for namePhoto on a share settlement: only a get's or a set's settlement carries it.

Reading the card

name_photo.get takes no payload. Its succeeded command frame carries the card as namePhoto: name (the name people see), firstName, lastName, and hasPhoto. The photo itself is never returned.

{ "name": "Northwind Support", "firstName": null, "lastName": null, "hasPhoto": true }

Setting the card

name_photo.set takes at least one of name, firstName, lastName and photoUrl — an https link to a JPEG, PNG, GIF, WEBP or HEIC image of at most 8 MiB, which the platform fetches before anything is sent. A photo left out is kept. Its succeeded frame carries the card as the line read it back.

A line whose device has not been updated to carry the card settles get or set failed with a capability errorCode, and a refused set changes nothing. While the line's sending is paused, a set is 503 at the POST and nothing is queued. Both commands honour Idempotency-Key. In test the line's card changes and the Sandbox page shows it; a photo link is checked but not drawn.

Related