> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Add the Vault to an iMessage agent

> Text your users the Vault's links from your own number, or let an iMessage provider render them as native bubbles in the thread.

An agent that lives in iMessage has nothing to embed. Your agent texts the user a link, they tap it, Safari opens the Vault, and they are back in the thread when they are done. If you send through Linq, its native integration can render the same steps as bubbles in the thread instead.

## Text the add-a-card link

Create a vault session on your server and send its `url` in the conversation, worded however your agent talks.

```bash theme={null}
curl -X POST https://api.agentcard.sh/api/v2/vault_sessions \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```text theme={null}
Add a card once and I can start buying for you:
https://vault.agentcard.sh/v?vs=vs_2q9d1x8f3k2m4t7w.3k1v…
```

The user taps the link, types their card, and saves it with Face ID or Touch ID. One link is one enrollment: send it to one person, and bind the `user_id` you receive to that phone number. Sessions last 24 hours by default; if the user comes back later, create a new one rather than resending an old link.

If you would rather not build the message, have Agentcard deliver it. [`POST /api/v2/checkout/vault_link`](/api-reference/vault/vault-link) texts or emails a connected user their link from Agentcard.

## Text the approval link

When your agent reaches the payment form, `onApprovalUrl` fires with a link. Text it with what the user is approving:

```text theme={null}
shop.example.com is ready to charge $23.06. Approve here:
https://vault.agentcard.sh/authorize?id=cauth_9k2m…
```

The user taps it, sees the merchant and the amount, confirms with their passkey, and the purchase completes. Nobody approving within 15 minutes expires the authorization, and your agent learns that over `checkout_authorization.expired`.

## Send through a provider

If your agent texts through an iMessage provider, the link is the message body and nothing more. Two providers, same message:

<CodeGroup>
  ```bash Linq theme={null}
  curl -X POST https://api.linqapp.com/api/partner/v3/chats \
    -H "Authorization: Bearer $LINQ_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "'"$LINQ_PHONE_NUMBER"'",
      "to": ["+15551234567"],
      "message": { "parts": [{ "type": "text", "value": "Add a card once and I can start buying for you: '"$VAULT_URL"'" }] }
    }'
  ```

  ```bash Blooio theme={null}
  curl -X POST https://api.blooio.com/v4/messages \
    -H "Authorization: Bearer $BLOOIO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+15551234567",
      "text": "Add a card once and I can start buying for you: '"$VAULT_URL"'"
    }'
  ```
</CodeGroup>

Linq also ships a native Agentcard integration, where the card enrollment and the approval render as bubbles drawn in the thread and Linq hands your agent the card to check out with. If you send through Linq, read the [Linq page](/vault/integrations/imessage-providers/linq). Photon and Blooio carry the texted link as a plain message today.

## Confirm with webhooks

The user saying "done" is a claim. The webhook is the fact:

* `vault.session_linked` carries the `user_id` to bind to the phone number.
* `vault.card_stored` when the card lands in the vault.
* `checkout_authorization.approved`, `checkout_authorization.declined` and `checkout_authorization.expired` for each purchase.

Without a public endpoint, [poll the session](/vault/adding-a-card#option-b-poll-the-session) until its `status` is `linked`.

## Test it

A sandbox token creates a sandbox session. Text the link to your own phone, store any of [Stripe's published test cards](https://docs.stripe.com/testing), and rehearse a purchase against [shop.agentcard.sh](https://shop.agentcard.sh), a demo store on Stripe test mode.

Next: [Create a cart](/vault/creating-a-cart).