Using a phone number already in use with WhatsApp App

If you want to use the Coexistence onboarding feature, please reach out to our Support Team.

Introduction

Now it's possible for business customers to onboard into WhatsApp Business API numbers that are already in use with WhatsApp Business App. Customers will then be able to use their WhatsApp Business App and WhatsApp Business API to message their customers simultaneously, without deleting the number from the WhatsApp app.

How it works

Customers who are successfully onboarded after choosing this option will then be able to use WhatsApp API to message their customers at scale but still have the ability to send messages on a one-to-one basis using the WhatsApp Business app while keeping messaging history between both apps in sync. If the customer sends the message from the WhatsApp app, you will receive the info to the phone number webhook.

Feature comparison

Existing feature on the WhatsApp Business App	Changes to features on the WhatsApp Business App AFTER onboarding to Cloud API	Is the WhatsApp Business app feature supported on Cloud API?
Individual (1:1) chats	Message Edit/Revoke is no longer supported.	Supported. All chat messages in the most recent 6 months can be synchronized. Messages sent and received are mirrored between the Cloud API and WhatsApp Business app.
Contacts	No change.	Supported. All contacts with a WhatsApp number can be synchronized.
Group chats	No change.	Not supported. Group chats will not be synchronized.
Phone number hiding chats	No change.	Not supported.
Disappearing messages	Disappearing messages will be turned off for all individual (1:1) chats	Not supported.
View once message	View once messages will be disabled for all individual (1:1) chats	Not supported.
Live location message	Live location messages will be disabled for all individual (1:1) chats	Not supported.
Broadcast lists	Broadcast list will be disabled. Business will not be able to create new Broadcast Lists. Existing Broadcast Lists will become read-only.	Not supported.
Voice and video calls	No change.	Not supported.
Business tools (eg. catalog, orders, status)	No change.	Not supported.
Messaging tools (eg. marketing messages, greeting message, away message, quick replies, labels)	No change.	Not supported.
Business profile (eg. business name, address, website)	No change.	Not supported.
Channels	No change.	Not supported.

Linked devices

Businesses can link up to four WhatsApp "companion" clients to their WhatsApp Business app account on other devices. Once a business customer onboards to Cloud API with an existing WhatsApp Business app account and number, all companion apps will be unlinked from the account, and the business can then re-link any supported companion apps.

WhatsApp users who use an unsupported companion client to message an onboarded business can do so, but the message will not trigger smb_message_echoes webhooks, so the business won't be able to mirror the message in their app.

Requirements

• The business customer must be using WhatsApp Business app version 2.24.17 or higher

• The business customer's phone number country code must be supported

• The webhook callback must be able to successfully accept and digest webhooks

• The business customer must have or create a Meta Business Manager

Unsupported countries and regions

• Australia

• India

• Japan

• Nigeria

• Philippines

• Russia

• South Korea

• South Africa

• Turkey

• European Union and European Economic Area

• United Kingdom

Onboarding

To onboard these numbers, 360Dialog Integrated Onboarding can be used or tech providers can also use their own Embedded signup.

Integrated Onboarding

This is the easiest way how to perform coexistence onboarding. Once the above requirements are met, you can trigger the onboarding using the signup link or connect button.

Onboarding steps

• Add a number that is already used in the WhatsApp Business app to the Meta Business Manager

• Create a 360dialog client account or use the already created one

• Trigger Integrated Onboarding

  • The client will go through the Integrated Onboarding so they must:

    • Phone number verification - OTP code

    • Scan the QR code

    • Share existing chat history (optional)

The step-by-step guide with more detailed info can be found here.

Own Embedded signup

Onboarding steps

• Setting your app

  • Subscribe to webhooks

    • history — describes past messages the business customer has sent/received

    • smb_app_state_sync — describes the business customer's current and new contacts

    • smb_message_echoes — describes any new messages the business customer sends with the WhatsApp Business app after having been onboarded

  • Customize Embedded Signup

    • Add a featureType property set to whatsapp_business_app_onboarding to the extras object in the launch method and callback registration portion of the Embedded Signup implementation code

• Triggering Embedded signup

• Connecting an existing number (Confirm number details and continue to fill up the business information)

• Phone number verification

• Scan the QR code

• Share chats (optional)

The step-by-step guide with more detailed info can be found here.

Webhooks

You will receive the following webhooks related to the onboarded numbers:

• history: Provides details about past messages the business customer has sent or received. Destination: history webhook will be sent to the partner's configured webhook URL in the following minutes after the onboarding succeeds.

• smb_app_state_sync: Describes the business customer's current and new contacts. Destination: smb_app_state_sync webhook will be sent to the partner's configured webhook URL in the following minutes after the onboarding succeeds.

• smb_message_echoes: Describes any new messages the business customer sends with the WhatsApp Business app after onboarding. Destination: smb_message_echoes webhook will be sent to the phone number's webhook URL.

History webhook

The history webhook is triggered when the business approves or declines sharing of their chat history. Below you can find the example structure. Below are the structures for both scenarios.

• Chat history sharing approved

{
  "id": "<EVENT_ID>",
  "event": "history",
  "data": {
    "id": "<WABA_ID>",
    "messaging_product": "whatsapp",
    "metadata": {
      "display_phone_number": "<BUSINESS_PHONE_NUMBER>",
      "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
    },
    "history": [
      {
        "metadata": {
          "phase": "<PHASE>", // Add appropriate phase value
          "chunk_order": <CHUNK_ORDER>,
          "progress": "<PROGRESS_VALUE>" // Add appropriate progress value
        },
        "threads": [
          {
            "id": "<WHATSAPP_USER_PHONE_NUMBER>",
            "messages": [
              {
                "from": "<BUSINESS_OR_WHATSAPP_USER_PHONE_NUMBER>",
                "to": "<WHATSAPP_USER_PHONE_NUMBER>", // Only included if SMB message echo
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<DEVICE_TIMESTAMP>",
                "type": "<MESSAGE_TYPE>",
                "<MESSAGE_TYPE>": {
                  "<MESSAGE_CONTENTS>" // Fill in message contents specifics
                },
                "history_context": {
                  "status": "<MESSAGE_STATUS>"
                }
              }
              // Additional message objects in thread would follow, if any
            ]
          }
          // Additional chat history thread objects would follow, if any
        ]
      }
    ]
  }
}

• Chat history sharing declined

{
      "id": "<EVENT_ID>",
      "event": "history",
      "data": {
        "id": "<WABA_ID>",
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "<BUSINESS_PHONE_NUMBER>",
          "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
        },
        "history": [{
          "errors": [{
            "code": 2593109,
            "title": "History sync is turned off by the business from the WhatsApp Business App",
            "message": "History sync is turned off by the business from the WhatsApp Business App",
            "error_data": {
              "details": "History sharing is turned off by the business"
            }
          }]
        }]
      }
    }

SMB App State sync webhook

The smb_app_state_sync webhook provides updates about the business customer's contacts, including future additions or changes. Below you can find the example structure.

{
      "id": "DM3",
      "event": "smb_app_state_sync",
      "data": {
        "id": "<WABA_ID>",
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "<BUSINESS_PHONE_NUMBER>",
          "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
        },
        "state_sync": [{
          "type": "contact",
          "contact": {
            "full_name": "<CONTACT_FULL_NAME>",
            "first_name": "<CONTACT_FIRST_NAME>",
            "phone_number": "<CONTACT_PHONE_NUMBER>"
          },
          "action": "<ACTION>",
          "metadata": {
            "timestamp": "<WEBHOOK_TIMESTAMP>"
          }
        },
        * Additional contacts would follow, if any */
      ]
    }
  }

SMB Message Echoes webhook

The smb_message_echoes webhook captures new messages sent by the business customer using the WhatsApp Business app after onboarding. This webhook ensures that partners can track and process these messages in real time. This webhook will be sent to the phone number level webhook. Below you can find the example structure.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "message_echoes": [
              {
                "from": "<BUSINESS_PHONE_NUMBER>",
                "to": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<WEBHOOK_TIMESTAMP>",
                "type": "<MESSAGE_TYPE>",
                "<MESSAGE_TYPE>": {
                  <MESSAGE_CONTENTS>
                }
              }
            ]
          },
          "field": "smb_message_echoes"
        }
      ]
    }
  ]
}