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
- Open Customers and choose the Customer.
- Open the Pairing links tab and select Generate link.
- Optionally enter the expected phone number.
- 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 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.
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"]
}'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 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.