# Customer pairing links

> Let a customer connect one Number without granting Console access.

A Customer pairing link lets the person holding a phone connect one WhatsApp
Number to their Customer record. The recipient does not need a Polymorfa
account or Console access.

## Generate a link

**Console:**

1. Open **Customers** and choose the Customer.
2. Open the **Pairing links** tab and select **Generate link**.
3. Optionally enter the expected phone number.
4. Select **Create link**, then copy the URL.

The Console shows the raw URL only after creation, so copy it before closing
the dialog.

**API:**

Call [Create a customer pairing link](https://docs.polymorfa.com/api/customers/create-customer-pairing-link)
with an `Idempotency-Key` and a key that has `customers:manage`. The URL is
returned only in the first response; a repeat with the same key returns
`url: null`.

```bash cURL
curl -X POST "https://api.polymorfa.com/platform/customers/$CUSTOMER_ID/pairing-links" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Idempotency-Key: pairing-crm_456-1" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "00000000-0000-4000-8000-000000000001",
    "expectedPhone": "+15551234567",
    "methods": ["qr", "phone"]
  }'
```

```typescript TypeScript
const link = await platform.customers.createPairingLink(
  customerId,
  { projectId: "<project-id>", expectedPhone: "+15551234567", methods: ["qr", "phone"] },
  { idempotencyKey: "pairing-crm_456-1" },
);

// Your application sends the URL over its own private channel; this is not an SDK method. Do not log it.
await sendToCustomer(customerId, link.data.data.url);
```

*TypeScript:*

List links with `listPairingLinks(customerId, projectId)` and revoke one with
`revokePairingLink(customerId, pairingLinkId, projectId)`.

The default link lifetime is 24 hours. Pairing-link lists show status and
metadata but never reveal the URL again.

When the recipient opens the link, Polymorfa issues a separate hosted
[QuickLink](https://docs.polymorfa.com/numbers/quicklink) and sends the recipient there. The
QuickLink remains active until the connection finishes or it is cancelled. The
Customer link never contains the QuickLink credential.

## Recipient flow

The recipient lands on the hosted page, scans a QR code or enters a pairing
code on the phone, and confirms the connection. Polymorfa verifies the
connected number before assigning it to the Customer. The link moves through
these states:

| State | Meaning |
| --- | --- |
| **Generated** | The link can start a connection attempt. |
| **Opened** | A recipient exchanged the durable link and Polymorfa reserved an attempt. |
| **Connecting** | A QuickLink session is active. |
| **Connected** | The verified Number was assigned to the Customer. The link cannot be reused. |
| **Failed** | The attempt failed. The same durable link can start another attempt unless it reached a safety limit. |
| **Expired** | The link passed its expiry time. |
| **Revoked** | A project member ended the link. |

A connected, expired, or revoked link cannot start another session. Generate a
new link instead.

## Lock the link to a phone number

Enter an expected phone number when only one WhatsApp identity is acceptable.
The value belongs to this invitation and is never inferred from a Customer
profile. It must be a valid international number. Polymorfa verifies the actual
connected Number before assigning it to the Customer.

When you create the link, Polymorfa checks the expected phone with one of your
connected Numbers. A number confirmed as not on WhatsApp fails with
`400 phone_not_registered`; when no connected Number can check it, the link is
created anyway.

If the numbers do not match, Polymorfa rejects the connection and requests
cleanup of the pending Number. Check that cleanup has finished before the
recipient retries the same durable link. Three phone mismatches revoke it.
Generate a new link with the correct number, or omit the restriction when any
verified Number is acceptable.

## Revoke or recover a link

Select **Revoke** beside a Generated, Opened, Connecting, or Failed link when it
was sent to the wrong person or is no longer needed. Revocation prevents
another exchange of the durable URL.

Recipient errors have these recovery actions:

- **This link is unavailable:** ask for a new link. The original expired, was
  revoked, connected a Number, or does not exist.
- **This link reached its limit:** ask for a new link after repeated attempts.
- **Pairing is temporarily unavailable:** wait briefly and open the same link
  again.
- **The connected phone does not match:** retry with the expected phone. After
  three mismatches, ask for a new link.

Treat a pairing link like an invitation. Send it only to the intended recipient
and revoke it if it is exposed.

## Saved invitation settings

Creating a Customer invitation saves the project's QuickLink settings and the
resolved profile for its expected phone. Changes to appearance, history policy,
connection preference, legal links or callback URLs apply to new invitations.
Opening an existing invitation uses its original settings and does not repeat
the original phone lookup. Pairing methods remain the only policy that creation
can override; when omitted, they come from the saved project settings.

An unavailable invitation must be replaced. The exchange endpoint returns
`410` without creating a session when the invitation cannot be used.

A retry after confirmation has attached the number resumes completion for that
same number. It does not attach another session or duplicate Customer events.
Terminal Meta Cloud API failures update the Customer invitation and produce its
failure event before the recipient is sent to the failure callback.
