Relay

Meta app and webhook setup

One-time Meta developer, app and webhook configuration that a Relay deployment needs before workspaces can connect WhatsApp numbers.

Audience: Teams operating a Relay deploymentLast updated 12 October 2026
Connecting a number to your workspace?
You don't need this page. Follow the quick start instead. This page is for the team that runs the Relay platform itself.

Complete the sections in order. Each depends on the one before it.

Meta developer and business accounts

  1. Create a Meta developer account

    Register at developers.facebook.com.

  2. Create a Meta Business account

    Create it at business.facebook.com.

  3. Complete business verification

    Required for production messaging. Verification usually takes 1 to 3 business days.

Meta app

  1. Create a Business-type app

    Add the WhatsApp product to it.

  2. Add Facebook Login for Business

    Embedded Signup, which workspaces use to connect numbers, runs on Facebook Login for Business.

  3. Copy the app credentials into the backend configuration
    Meta valueBackend setting
    App IDMETA_APP_ID
    App secretMETA_APP_SECRET
    Embedded Signup configuration IDMETA_EMBEDDED_SIGNUP_CONFIG_ID

    Store the app secret as a secret; never commit it or expose it to the browser.

  4. Add the OAuth redirect URIs

    In Facebook Login for Business›Settings, add both URLs to Valid OAuth Redirect URIs:

    Valid OAuth Redirect URIs
    https://<your-app-domain>/onboarding/whatsapp/callback
https://<your-app-domain>/onboarding
  5. Allow your domain for the JavaScript SDK

    In the same panel, set Allowed Domains for the JavaScript SDK to the bare domain, for example www.bm-relay.com, with no https:// and no trailing slash.

  6. Add the app domain

    In App settings›Basic›App domains, add the bare domain, for example bm-relay.com. Then complete the Data Use Checkup again, or Meta keeps Login paused.

"Feature unavailable" after signing in
This Meta error almost always means the allowed domain is malformed: it includes https://, a path, or a trailing slash. Correct it and retry.

Webhook

  1. Set the callback URL
    Callback URL
    https://<your-api-domain>/api/v1/webhooks/whatsapp
  2. Set the verify token

    Use the same value in Meta and in the backend setting META_WEBHOOK_VERIFY_TOKEN.

  3. Subscribe to webhook fields, then verify and save
    Webhook fields
    messages
message_template_status_update
account_update
phone_number_name_update
business_capability_update

Go-live checklist

  • A production number is registered and verified, and its display name is approved.
  • At least one message template is approved, so campaigns can start conversations.
  • The webhook has received a test event from Meta.
  • Onboarding reaches the Live stage for a test workspace.

When the checklist is complete, workspaces can connect numbers from the onboarding page.