Skip to content
Shortcut: /, ⌘K or Ctrl+K

Build your own pairing interface

Request QR codes and pairing codes from your backend and show them in your own interface.

View as Markdown

Direct pairing returns the raw QR code or pairing code for a Linked Devices Number, so you can show it in your own interface instead of the hosted QuickLink page.

Before you begin#

  • The team that owns the Number has direct-pairing access.
  • The Number exists in your project and connects through Linked Devices. New Numbers are created through QuickLink; direct creation is retired and returns 410 resource_gone.
  • Your server holds a credential with sessions:manage.
  • The Number is funded. Polymorfa checks funding when pairing starts; see Fund linked-device pairing.

Keep the credential on your server. Pass only the QR value or pairing code to the browser or app that shows it.

Pair with a QR code#

  1. Request the QR code

    Call Get QR code:

    Shell
    curl "https://api.polymorfa.com/messaging/$SESSION/pair/qr" \
      -H "Authorization: Bearer $POLYMORFA_KEY"

    The JSON response holds the value to encode in data.qr. Add ?format=image to receive a PNG instead.

  2. Show the code

    Render the value as a QR code. On the phone, the person opens WhatsApp, selects Linked devices, then Link a device, and scans it.

  3. WhatsApp rotates QR codes. Request a new code when the current one expires, and stop when the Number reports session.connected.

Pair with a phone number#

  1. Request a pairing code

    Call Request a pairing code with the phone number in international format:

    Shell
    curl -X POST "https://api.polymorfa.com/messaging/$SESSION/pair/code" \
      -H "Authorization: Bearer $POLYMORFA_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "phone": "+15550001111" }'

    The response holds the code in data.code.

  2. Enter the code on the phone

    In WhatsApp, the person opens Linked devices, selects Link a device, then Link with phone number instead, and enters the code.

Verify the connection#

Subscribe to session.connected on a webhook, or read the Number with Get session until its status is CONNECTED. Then send a test message.

See also#