Sharing your contact card

name_photo.share offers your iMessage name and photo to the other party in a direct message — the contact-card share Messages prompts about 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.

It takes no arguments at all. The only thing you choose is who to offer it to.

Sending it

The target is a direct-message conversation. Groups are not supported, and neither is a bare phone number — you need a conversationId, which means the conversation must already exist. See Addressing a conversation.

The payload is empty, but the payload key itself is still required. Omitting it entirely is rejected with 400 target_and_payload_required.

curl $MAPIER_BASE_URL/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 the other agent-turn commands, this honours Idempotency-Key, so a retry adopts the original command rather than offering twice. Group commands do not — see Idempotency for which is which.

Reading the outcome

The command settles succeeded whether iMessage actually showed the prompt or declined to — usually because the card has already been shared with that person, so there was nothing left to offer. Whether the prompt appears is iMessage's decision, not something the command overrides, and the settlement event carries only status and errorCode, so it does not report which of the two happened.

Treat a succeeded settlement as "the recipient has your card or already had it". There is no signal anywhere in the API that distinguishes them, and nothing to retry either way.

Sharing requires a Mac advertising command.name_photo_share.v1. A host without it settles the command failed with unsupported_capability or capability_not_negotiated rather than rejecting the request up front.

Related