Location

An iMessage line can ask a contact to share their location: a message.send whose payload is kind: "location_request" puts Apple's "Share My Location?" card in their thread. If they tap Share, their location arrives later as events — never on the send's own settlement.

{ "kind": "location_request" }

That is the whole payload. Any other key beside kind, a text included, is 422 validation_failed at that key before anything is written. To say why you are asking, send a text first.

Where a request can go

A location request travels on the line's conversation path alone: into a one-to-one conversation the transport has confirmed is with that one person, which it does the first time they write into it. A group, or a conversation not confirmed yet, is 422 validation_failed with reason: conversation_not_confirmed before anything is written. A request to a line on any other channel is 404 unsupported_command with reason: not_on_channel.

A reply is target.replyToMessageId, as on any send.

What succeeded means

succeeded means the card was sent — never that the person shared. Whether they share, and for how long, is theirs to decide in Messages, and nothing on the request's command frame changes when they do.

What the Mac behind the line can send is not known before a request is sent. A Mac that has not announced location requests — or replies on one, for a reply — is sent nothing: the command is accepted with a 202 and then settles failed with capability_constraint_violation (or capability_not_negotiated), failureClass: capability.

What comes back

A share reaches you as three event types, and only if you ask for them: location.share_started, location.updated with a new position about every 30 seconds, and location.share_ended. Open the stream with ?events=locations to get them as event: location frames, or subscribe a webhook endpoint to them by name — they are not in a new endpoint's default set. See Location events.

A location belongs to the contact on their one-to-one conversation with the line, never to a group, and is filed only for a contact your project already holds.

A worked request

curl https://api.mapier.ai/v1/commands/message.send \
  -H "Authorization: Bearer $MAPIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pickup-4821-location-ask" \
  -d '{
    "target": {
      "kind": "conversation",
      "conversationId": "a0000000-0000-4000-8000-000000000001"
    },
    "payload": { "kind": "location_request" }
  }'

In test

On a test line the card is sent and delivered to the sandbox phone, and nobody shares back. To rehearse the events, the sandbox phone can share a location through the console's sandbox routes; the Sandbox page has no control for it yet. See Location events.

Related