Coexistence

Coexistence

This feature allows your client to connect to WhatsApp API with his own number and keep using his WhatsApp Business app together with it.

Partners can create onboarding link with this feature, which will enable the coexistence while client is completing the onboarding process.

Important remarks, make sure you read and understand them all:

1. Client can only onboard numbers that are present in the WhatsApp Business app, not the regular WhatsApp app. if client uses the regular WhatsApp app and want to use the api, it is possible to migrate number from one app to another, just let clients download the WhatsApp official business app and apply the same number. WhatsApp will migrate everything, and then they can onboard.

2. WhatsApp business app version must be 2.24.17 or higher.

3. While onboarding, the client will be asked if he wants to share history chats with the API. if he accept it, the system will extract 6 months of history, allowing you to get this (using getHistory) so you can show this in your system for complete user friendly experience. its completely up to you if you want the history or not (After client approves it). media are not supported, only written messages.

4. Every incoming message (from end users) will arrive to client's app (as it was before) and also to the API. so both of you are getting the same message.

5. Every outgoing message from the API will be visible inside client's WhatsApp mobile app.

6. Every outgoing message that is done by the client himself, from the WhatsApp app will initiate a webhook to tell you that client sent outgoing message from the app.

7. Groups are not supported. incoming / outgoing messages will only work on the mobile app and not be visible in the API.

8. In order to create a better use experience, you are limited to 20 messages per second (outgoing) and not 80 messages per seconds as if this was API only account.

9 Regarding pricing - everything that happens on the mobile app is free, as it was before the connection - incoming messages / outgoing messages - all the same as it was (outgoing messages dont' need a template from the mobile app). everything that is done from the API keeps the same pricing as before - marketing / utility template as it was.

Example use case so you better understand point number 9:

A client connected the "coexistence" onboarding. his mobile app and API are now synced.

assume you want to send a message to end user from the API, you must send a template if no open session in the last 24 hours.

The client however can send a message freely to new numbers, he doesn't "feel" the 24 hours session limitation from the WhatsApp app..

If end user sends a message to your client, you will get it by the API (as explained on item 4 above) and due to that, it opens a 24 hours session, as it is today so you can send free messages without templates from the API.

10. Disappearing messages (a messages that disappears after some time) will be disabled for the mobile app. (only groups can still use this feature).

11. "View once" messages (a messages that a client can read only once) will be disabled for the mobile app. (only groups can still use this feature).

12. All other special features from WhatsApp - will remain in the app only. (such as: Channels, status, greeting messages, away messages, voice and video calls, broadcast, live location messages etc).

13. Once "coexistence" onboarding completed, all linked devices (WhatsApp web / WhatsApp for mac/windows local app) will be disconnected and can be re-linked again in case needed. WhatsApp for windows and WearOS are not currently supported as "linked devices" to trigger event on outgoing messages webhook from the windows app or WearOS. so for windows users it is better to re-use linked devices with WhatsApp web instead. the client can use the Windows app for the linked devices, but the API will not see outgoing messages for any message that was sent in the windows app/wearOS.

14. During onboarding, the client will require to scan a QR or provide a code sent to his WhatsApp, to confirm the connection.

15. The client can stop using the shared solution coexistence (on his side) directly from his app at any time.

16. The end user must visit the WhatsApp Business app (from his phone) at least once in every 20 days to keep the connection active. this is similar rules for using WhatsApp web.

17. The display name, profile picture, profile settings (website, email, description) can only be changed / set by the client from the WhatsApp Business app and not from the API.

How to use and how to onboard coexistence client

1. From the partners platform, create a new onboarding, providing the "whatsapp" parameter to be 1. this will tell the system not to use existing verified number. the system will generate a temporary whatsapp number starting with 97257 until a real number is connected.

2. Now the client open the onboarding link, and selecting "Connect a Whatsapp Business App" when prompt the question to create a whatsapp account.

3. The client will be asked to provide the WhatsApp phone number, and then he will get a WhatsApp message (to his WhatsApp number) from the system to accept the connection. tell him to check his WhatsApp messages. once clicking on the WhatsApp message, it will open the camera on his phone, and a QR code will be shown for him to scan. he can either scan the QR code on the onboarding page, or enter a code instead (if camera is not working for any reason).

4. Once doing it, he can choose if he wants to share 6 months of history chats (no files) or not.

5. After client finishes the onboarding, the partner will get the same webhooks for setting up the account, with WhatsApp number (real number) and apiKey.

6. Once the onboarding finishes, tell the client to open the WhatsApp app on his phone (in case its not open in the foreground) to allow quick history sync (if he accepted it).

7. 10 minutes after onboarding completed, you can go to endpoint getHistory to see all his 6 months of history that was extracted. if no history is present there it means that the client did not gave permission to extract history. clean slate. 

8. Before you start onboarding coexistence clients, make sure you listen to 2 new webhooks: outgoing messages and contact messages. both are located in the webhook page. when the user sends a message directly from his mobile phone you will get a webhook of "outgoing" so you can know this event happened. when the recipient receive the message, you will also get read status webhook for that "outgoing" message. so its not only you get outgoing messages notification, you also get webhook about read status for those messages.

10. During onboarding (or right after) you might start getting the "contact" messages webhook to update you about all contacts that the client added to his phone book. alternatively, you can always access the Get Contacts endpoint to see all contacts.

11. Remember - client is in control. client decide the display name, the profile settings, if/when to disconnect the connection and so on.

If you have more questions regarding this, please contact support.