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.

The two outcomes

not_offered is not an error. It usually means 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 — so treat no_effect here as "the recipient already has it" rather than as a failure to retry.

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