WhatsApp guide

Learn how to implement a custom WhatsApp authentication flow inside your application using the postpress API.

Step 1: Start a WhatsApp authentication

You can start a WhatsApp custom authentication in two ways:

With a QR code, scanned from the user's phone.
With a pairing code sent to a phone number.

POST to the accounts endpoint or use the matching SDK method when one is available.

Option A: QR code

Use the default WhatsApp custom authentication flow to request a QR code that the user scans from their phone.

curl --request POST \
     --url https://api.postpress.ai/v1/accounts \
     --header 'X-API-KEY: ${POSTPRESS_API_KEY}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "provider": "WHATSAPP"
}'

Option B: pairing code

If you want to connect the account with a phone number instead of a QR code, make the custom authentication call with pairing_phone_number.

The phone number must be sent in international format, using E.164 digits only: country code followed by the number. For example, 33612345678.

When pairing_phone_number is provided, postpress returns a checkpoint that contains the pairing code the user enters in the WhatsApp app on their phone.

curl --request POST \
     --url https://api.postpress.ai/v1/accounts \
     --header 'X-API-KEY: ${POSTPRESS_API_KEY}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "provider": "WHATSAPP",
  "pairing_phone_number": "33612345678"
}'

Step 2: Display the authentication challenge

If you use the QR code flow

Convert the textual QR code into a visual QR code with a suitable library, then display it to the user.

PHP library: chillerlan/php-qrcode
JavaScript library: soldair/node-qrcode

If you use the pairing code flow

Display the returned pairing code in your UI and ask the user to enter it on their phone in WhatsApp.

In most cases, WhatsApp opens a notification on the phone, or takes the user straight to the screen where the code can be entered.

Step 3: Listen for confirmation

After displaying the QR code or the pairing code, listen for the user to validate it so you know when the account is authenticated and connected to postpress. There are two ways to do this.

Option A: polling request on get account status

Make a GET request to the account endpoint. The request resolves only when the account is successfully connected. Implement a polling loop in your backend to handle it.

Option B: account status webhook

Configure an account status webhook to receive a notification when the status changes. Your backend reacts to the event when the account moves to OK, with no polling needed.

Updated May 2026