name_photo.share

POST /v1/commands/name_photo.share

Offers your iMessage name and photo to the other party in a direct message, the same prompt Messages shows when you share your contact card. Takes no arguments.

Honours Idempotency-Key.

Target

On an iMessage line, live or test, the conversation at target.conversationId must be one the transport has named, which it does when the contact first writes into it. A share addressed by a phone number or an email instead, or into a conversation the transport has not named, is 422 validation_failed at target.conversationId before anything is sent — so the thread has to exist, with a message from the contact in it, first.

Payload

Empty — but the key is still required:

{}

Request

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": {}
  }'

Response

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

The command settles succeeded both when the card was offered and when iMessage declined to show the prompt — usually because the recipient already has the card — and the settlement does not tell the two apart. This settlement does not carry namePhoto: that card is name_photo.get's and name_photo.set's.

Errors

A command answers the one set of HTTP refusals POST /v1/commands/{type} publishes — every type the same codes, service_busy and no_line_capacity (capacity_exhausted from 2026-10-15) among them — so that table is the one to handle. What is particular to this type:

• 422 validation_failed at target.conversationId, and 400 bad_request with details.reason: "invalid_target" for a group's conversation (above), both before anything is sent.

A share the line could not offer settles on the stream, not as an HTTP refusal.

Related