sunrai · help
Back to SunrAI

Connect WhatsApp Business

Connect a Meta WhatsApp Cloud API number for customer messages in the SunrAI inbox.

Updated3 min readintegrations

Connect one Meta WhatsApp Cloud API number to receive customer messages and reply from the shared SunrAI inbox.

Before you start

  • You must be a SunrAI team Owner or Admin.
  • You need a Meta Business Portfolio, a WhatsApp Business Account, and a Cloud API phone number.
  • Create a Meta system-user access token for the same Meta App with whatsapp_business_management and whatsapp_business_messaging. Keep the token and App Secret private.

Collect these values from Meta before opening SunrAI:

  • Meta App ID
  • WhatsApp Business Account (WABA) ID
  • Phone Number ID
  • System-user access token
  • Meta App Secret
  • Display phone number in E.164 format, such as +15551234567

Connect the number

  1. Open the WhatsApp admin card

    In SunrAI, open Settings → Integrations → WhatsApp admin.

  2. Generate the webhook verify token

    In the WhatsApp card, generate a verify token. Copy both that token and the displayed webhook URL. The token belongs only to the current SunrAI team.

  3. Configure the webhook in Meta

    In your Meta app's WhatsApp webhook configuration, paste the SunrAI callback URL and verify token. Complete Meta's verification challenge, then subscribe the app to the messages field.

  4. Save the Meta credentials

    Enter the App ID, WABA ID, Phone Number ID, access token, App Secret, and display number in SunrAI. Save credentials verifies the token's App and scopes, confirms that the phone belongs to the WABA, and confirms that the App is subscribed to the WABA before activating the channel. The access token and App Secret are encrypted and are never returned to the browser.

  5. Enable intelligence only if wanted

    WhatsApp Intelligence is a separate opt-in. When enabled, SunrAI can extract project signals from inbound text after the original inbox message is stored. Receiving and replying in the inbox does not require this toggle.

Verify it worked

  1. The card should show Meta confirmed, including the verified display name or phone number.
  2. Send a WhatsApp message from a customer phone to the connected business number.
  3. Return to the card and choose Test connection. The recent-inbound list should show the message.
  4. Open the shared inbox and confirm that the message appears in the customer's canonical thread.

Free-form replies are allowed only within Meta's 24-hour customer-service window. Outside that window, SunrAI blocks the reply until approved Meta template sending is available.

Troubleshooting

"Meta rejected the access token or Phone Number ID" — Confirm the token belongs to the same Business Portfolio and has access to the WABA and phone number. If the token was rotated, paste the replacement into SunrAI and save again.

Meta cannot verify the webhook — Copy a fresh per-team verify token from SunrAI and make sure the callback URL is exactly https://www.sunrai.ai/api/webhooks/whatsapp.

Meta is confirmed but no messages appear — In Meta, confirm that the app is subscribed to the WABA's messages webhook field. Then send a new inbound message and run Test connection again.

A reply says the 24-hour window has closed — Ask the customer to send a new message. Meta does not permit a free-form outbound message to reopen the conversation; an approved template is required.

Related

← More on Integrations