Relay

Docs navigation

Connect WhatsApp

Nothing arrives in the Inbox until a WhatsApp number is connected. This page covers the connect screen at Settings → WhatsApp, the two ways most accounts connect, and what to do if something isn't working.

What you need

  • A Meta Business account, and admin rights on it — Relay needs that to generate credentials and subscribe the number for webhooks.
  • A phone number for WhatsApp. It must not already be registered on the regular WhatsApp or WhatsApp Business consumer app (delete it there first, or use a fresh number) — unless you're using the "I already use the WhatsApp Business app" option described below, which is the one case where the number stays exactly where it is.

Relay shows this as a short "Before you connect" readiness check before you start, so a connection attempt doesn't fail partway through.

Choosing how to connect

Open Settings → WhatsApp. If the account has no number connected yet, you'll see a method picker (only the methods your platform has enabled are shown):

  • Sign up with Meta ("Connect with WhatsApp") — Meta's Embedded Signup, a guided multi-step popup. This method is off by default, behind a platform setting (platform_connection_methods.embedded.enabled). When it's off, its tile simply doesn't appear — if it's the only method disabled, you go straight to manual entry with no picker shown at all.
  • Enter credentials manually — paste your Phone Number ID, WhatsApp Business Account ID, and access token by hand. This is the default when Embedded Signup is off.
  • I already use the WhatsApp Business app — the Coexistence method, described below.
  • Connect via provider — onboarding through a WhatsApp Business Solution Provider. Where enabled but not yet built for your platform, this tile just says so and stops there.

Once a number is connected, the method picker is gone for good — the screen switches to a status/management view instead, and changing connection method requires disconnecting first.

Cloud API vs. Coexistence

Both connect the same way (Embedded Signup, or manual credentials for Cloud API), but they behave differently once connected:

Cloud API (the ordinary case) — the number lives on WhatsApp's Cloud API and stops working on any phone. After connecting, Relay may need to register the number: a form asking for its 6-digit two-step verification PIN, with this help text:

"Your number's 6-digit PIN. We use it to register the number so Meta delivers incoming messages to Relay. If the number is new, choose a PIN and we'll set it. Leave blank to connect now and finish later — you won't receive messages until it's done."

If Embedded Signup finishes without registering, Relay shows: "WhatsApp connected, but the number is not registered yet, so incoming messages may not reach Relay. Enter your 6-digit PIN below to finish."

Coexistence — for a number that's already live in the customer's WhatsApp Business App on their phone. Relay drives the same number through the Cloud API alongside the phone, rather than instead of it. Practically, that means:

  • No PIN, ever. The registration step that Cloud API numbers go through would deregister the number from the phone, so Relay never runs it for Coexistence — there's no PIN field, and no "finish registration" step to complete.
  • Sends are paced to 20 messages/second on that number, because the handset shares the same throughput.
  • Chat history import runs once, for about 24 hours after linking, to bring existing conversations from the phone into Relay. If it times out before finishing, anything left over stays only on the phone — starting it again means disconnecting and reconnecting the number, which restarts the whole window.
  • Before you connect, Relay discloses what stops working on the phone once the number is linked: disappearing messages, view-once photos and videos, live location sharing, broadcast lists, and group chats (group chats aren't carried by the Cloud API at all, so they never reach Relay either). None of this can be undone from Relay once the number is linked.

The connection status panel

Once connected, the status panel shows:

  • Connected via — Manual setup, Meta Embedded Signup, Coexistence, or Business Solution Provider.
  • Its number, and whether it's live / not live.
  • Last inbound message time, or "No inbound messages received yet".
  • A row of readiness checks — configuration saved, token readable, number reachable on Meta, WABA subscribed to Relay, and (Cloud API only) number registered for webhooks — each with a hint if it's failing.
  • For a Coexistence connection specifically, the registration check is replaced with a note: "This number is deliberately never registered for Cloud API webhooks — that registration is what would disconnect it from the WhatsApp Business app on your phone. Subscribing your WhatsApp Business Account is the whole wiring here, and it's done."

A failing check here always comes with a hint telling you what to do next, right below the checklist.

Below the status panel, a collapsed "Change or disconnect this number" section holds the ability to edit stored credentials (manual connections) or start a fresh Embedded Signup (embedded/Coexistence), and to disconnect. Disconnecting only removes the stored WhatsApp credentials for the workspace — contacts, conversations, and messages are kept.

Troubleshooting

  • A readiness check is failing. The status panel's hint tells you exactly what to do — usually re-saving credentials, or (for the token check) that ENCRYPTION_KEY changed on the server and the configuration needs resetting and re-entering.
  • "Connected, but not receiving yet." The connection is live but nothing inbound has arrived. Send a test WhatsApp message to the number and confirm it appears in the Inbox — if it doesn't within a minute or two, revisit the readiness checklist.
  • You disconnected a Cloud API number and want to reconnect. Reconnecting is the normal path — its registration step is what actually stops and restarts delivery, and it's not destructive for Cloud API. This is not the same as disconnecting a Coexistence number; see the warning above.
  • Still stuck? Contact support.