> For the complete documentation index, see [llms.txt](https://docs-conversational-ai.syntphony.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-conversational-ai.syntphony.com/syntphony-messaging-portal/messaging-tools/technology/whatsapp-add-phone-embedded-signin-guide.md). # Adding a WhatsApp Phone Number (Embedded Sign-In Guide) ## Introduction This guide explains how to connect a WhatsApp Business API phone number to the Syntphony Messaging Portal using **Embedded Sign-In** under **Technology**. It applies whether you are: * **Adding a new number** (first-time WhatsApp Cloud API setup on this platform), or * **Migrating an existing number** from another Business Service Provider (BSP). Both paths use the same Meta embedded signup experience in the portal. The difference is which option you choose inside the flow (add a new number versus migrate an existing one) and which prerequisites you complete beforehand. Typical completion time is **15–30 minutes** when prerequisites are ready. Migrations from another BSP may require extra lead time (for example, disabling Two-Step Verification with your current provider). Registering a number only in [Phone Configuration](/syntphony-messaging-portal/messaging-tools/administration/phone-configuration.md) does **not** connect it to WhatsApp. You must complete Embedded Sign-In for the number to be integrated with Meta. For scenario-specific checklists, see also: * [First-Time WhatsApp Onboarding (Customer Guide)](/syntphony-messaging-portal/messaging-tools/technology/whatsapp-first-time-embedded-signin-customer-guide.md) — new numbers only, no BSP migration. * [Embedded Sign-In](/syntphony-messaging-portal/messaging-tools/technology/embedded-sign-in.md) — short portal reference for operators. *** ## Before you start ### Required for all scenarios Complete all items before starting Embedded Sign-In. | Item | Status | Notes | | ----------------------------------- | ------ | ------------------------------------------------------------------------------------------------------ | | **1. Meta Business Manager access** | ☐ | You have admin (or equivalent) access to the Business Manager that owns or will own the WhatsApp setup | | **2. Phone number confirmed** | ☐ | Write it here: **+** \_\_\_\_\_\_\_\_\_\_\_\_\_ (country code required) | | **3. Number can receive OTP** | ☐ | The line can receive SMS or a voice call with a 6-digit verification code | | **4. Facebook/Meta login ready** | ☐ | The account you use has the permissions needed in that Business Manager | | **5. Session prepared** | ☐ | Stable browser, pop-up blockers disabled for the portal domain | ### Additional requirements when migrating from another BSP Complete these **in addition** to the table above if the number is already on WhatsApp via another provider. | Item | Status | Notes | | ------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------- | | **6. Current provider informed** | ☐ | Your current BSP knows you intend to migrate this number | | **7. Two-Step Verification (2FA) disabled** | ☐ | Your current BSP has disabled WhatsApp Two-Step Verification on the WABA; you have written confirmation | | **8. Migration window agreed** | ☐ | Preferred date/time for the session: \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ | **Important:** Do not start a migration in Embedded Sign-In until 2FA is confirmed off. Migration cannot complete while 2FA remains enabled on the existing WABA. ### Additional requirements when adding a new number | Item | Status | Notes | | ------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------ | | **6. Number eligible for API** | ☐ | The number is not active on WhatsApp consumer app, WhatsApp Business app, or another Cloud API registration you cannot release | | **7. Business details ready** | ☐ | Legal business name, website, category, and support contact information as Meta may request | *** ## Choose your path in Embedded Sign-In After you authenticate with Meta and grant permissions, the embedded flow asks how you want to connect the phone. Select the option that matches your situation: | Your situation | What to select in the flow | | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | The number is **not** yet on WhatsApp Cloud API through another BSP, or you are setting up WhatsApp for this business for the first time on this platform | **Add a new phone number** (or equivalent wording) | | The number is **already** registered for WhatsApp Business API with **another BSP** and you are moving it to this platform | **Connect existing WhatsApp number**, **Migrate phone number from another provider**, or similar migration option | If you are unsure, confirm with your platform team before starting. Choosing the wrong path can block verification or require restarting the flow. *** ## Step-by-step: Embedded Sign-In ### Phase 1: Open the flow in the portal | # | Action | Expected result | | - | --------------------------------------------------------------------------------------------------- | ---------------------------- | | 1 | Sign in to the Syntphony Messaging Portal | You reach the main workspace | | 2 | Open **Technology** → **Embedded Sign-In** (labels may vary, for example **Sign in with Facebook**) | Meta embedded signup opens | | 3 | Sign in with the Facebook/Meta account linked to your Business Manager | Authentication succeeds | ### Phase 2: Authorize and select business assets | # | Action | Expected result | | - | ------------------------------------------------------------------------------------------------------ | ------------------------------------ | | 4 | Accept the permissions requested so the platform can manage WhatsApp Business assets | Permissions granted; flow continues | | 5 | Select the correct **Business Manager** (create one only if Meta prompts and your process requires it) | Correct business context is selected | | 6 | Select or create the **WhatsApp Business Account (WABA)** that will own the phone | WABA is shown on screen | ### Phase 3: Connect the phone (path-specific) **Path A — New phone number** | Step | What to do | Expected result | | ---- | ---------------------------------------------------------------------------------- | ------------------------------- | | 7a | Choose to **add a new phone number** | New number entry screen appears | | 8a | Enter display name and business profile fields if Meta requests them | Profile step completed | | 9a | Enter the phone number with country code | Number accepted in the form | | 10a | Choose OTP delivery (**SMS** or **voice**), receive the 6-digit code, and enter it | Verification succeeds | **Path B — Migrate existing number from another BSP** | Step | What to do | Expected result | | ---- | ------------------------------------------------------------------------------------- | -------------------------------------------- | | 7b | Choose **migrate** / **connect existing** (not add new) | Migration path is selected | | 8b | Enter the **exact** number currently on the other BSP (with country code) | Number accepted in the form | | 9b | Choose OTP delivery (**SMS** or **voice**), receive the 6-digit code, and enter it | Verification succeeds; migration completes | | 10b | Confirm success in the portal (for example, Phone Number ID and WABA details visible) | Number is registered on this platform’s WABA | ### Phase 4: Portal follow-up | # | Action | Expected result | | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | 11 | Confirm the number appears in administration (or register it in [Phone Configuration](/syntphony-messaging-portal/messaging-tools/administration/phone-configuration.md) if your tenant requires a manual entry) | Number is available for [Source Configuration](/syntphony-messaging-portal/messaging-tools/administration/source-configuration.md) | | 12 | Link the number in a WhatsApp **source** with the correct bot | Routing is configured | | 13 | Run outbound and inbound test messages with your platform team | Send and receive paths verified | *** ## What happens after a successful connection ### Immediately * The phone is associated with your WABA in Meta and connected to the platform. * Approved templates, display name, and business profile generally remain when **migrating** from another BSP (subject to Meta rules and your WABA state). * You can proceed with source setup, templates, and operational messaging once your tenant is fully configured. ### Within 24 hours (typical) * Backend webhook and billing setup may be finalized by your platform team. * Production traffic should use the new platform connection only after your team confirms go-live. ### Billing * **New number:** Conversation charges apply per Meta and your platform agreement once messaging is active. * **Migration:** Messages may continue to bill through your previous BSP until migration completes; afterward, billing follows your agreement with this platform. *** ## Troubleshooting ### OTP not received * Confirm the number including country code. * Ensure the line can receive SMS or voice calls (IVR or call screening can delay voice OTP). * Retry verification from the flow; your platform team can start a new attempt if needed. ### Migration blocked by Two-Step Verification (2FA) * Contact your **current BSP** and request disablement of WhatsApp Two-Step Verification for the WABA. * Do not re-enable 2FA until migration finishes. * Restart Embedded Sign-In only after you have written confirmation that 2FA is off. ### Permission denied or wrong Business Manager * Sign in with a Facebook account that is **admin** on the correct Meta Business Manager. * Confirm the WABA and phone are linked to that Business Manager. * Retry the flow or contact your platform support team. ### Flow appears stuck * Do not close the browser immediately; Meta can take a few minutes to sync. * Note the step and time, refresh if advised, or resume with your platform team. ### Number registered in Phone Configuration but WhatsApp does not work * Complete [Embedded Sign-In](/syntphony-messaging-portal/messaging-tools/technology/embedded-sign-in.md) for that number; portal registration alone is not sufficient. * See [Phone Configuration](/syntphony-messaging-portal/messaging-tools/administration/phone-configuration.md). *** ## Important reminders **Do not:** * Start migration before 2FA is disabled on the source WABA (migration path only). * Use a number that is still bound to consumer WhatsApp or another API registration you cannot release (new number path). * Assume [Phone Configuration](/syntphony-messaging-portal/messaging-tools/administration/phone-configuration.md) replaces Embedded Sign-In. **Do:** * Keep the phone available for OTP during the session. * Stay in the correct Meta Business Manager context for the whole flow. * Complete [Source Configuration](/syntphony-messaging-portal/messaging-tools/administration/source-configuration.md) after the number is connected. *** ## Glossary | Term | Meaning | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | **2FA / Two-Step Verification** | Security setting on a WABA; must be disabled by the current BSP before migrating a number from another provider. | | **BSP** | Business Service Provider — the platform that hosts your WhatsApp Business API integration. | | **Embedded Sign-In** | Meta signup flow embedded in **Technology** that connects Business Manager, WABA, and phone assets to the portal. | | **OTP** | One-time passcode (typically 6 digits) sent by SMS or voice to verify phone ownership. | | **WABA** | WhatsApp Business Account in Meta; container for phone numbers, templates, and business profile. | | **Cloud API** | Meta-hosted WhatsApp Business API used for production messaging. | *** ## Related pages * [Technology](/syntphony-messaging-portal/messaging-tools/technology.md) * [Embedded Sign-In](/syntphony-messaging-portal/messaging-tools/technology/embedded-sign-in.md) * [First-Time WhatsApp Onboarding (Customer Guide)](/syntphony-messaging-portal/messaging-tools/technology/whatsapp-first-time-embedded-signin-customer-guide.md) * [Phone Configuration](/syntphony-messaging-portal/messaging-tools/administration/phone-configuration.md) * [Source Configuration](/syntphony-messaging-portal/messaging-tools/administration/source-configuration.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs-conversational-ai.syntphony.com/syntphony-messaging-portal/messaging-tools/technology/whatsapp-add-phone-embedded-signin-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.