Initial setup

This is a long guide, and most of the work happens in Meta's developer portal rather than in Connect. Set aside a decent block of time and work through it in order. The steps are numbered continuously from 1 to 60 so you can keep track of where you are.

Only admin users can configure WhatsApp. What you set here applies to every WhatsApp user in your organisation, so you only do it once.

Before you get started

If you're already using WhatsApp Business on a phone, you'll have to delete that account before you can link the number to Connect. A number can't be on WhatsApp Business and Connect at the same time.

• Back up your WhatsApp Business account first and note down anything important. None of it is migrated to Connect.
• Work through most of this guide before you delete the existing account. Leave it until just before you verify the phone number in the Meta developer portal, so your existing setup keeps working for as long as possible.
• Verification sends a code by text message or phone call, so have access to the phone number you're adding.

Register as a Meta developer

If you haven't got a Meta developer account already, you can register with an existing personal or business Facebook account.

1. Go to https://developers.facebook.com/async/registration and follow the steps to register.

The phone number you give here should be your own contact number, not the business number you're planning to use with WhatsApp.

Meta's registration guide has more detail if you need it.

Create a business app

2. From the Meta apps dashboard, click Create App.

3. Enter an app name and a contact email address, then click Next. We suggest calling the app Connect.

4. Under Add use cases, select Connect with customers through WhatsApp, then click Next.

5. Choose the business portfolio you want to link WhatsApp to, then click Next.

If you already use other Meta services, pick the same portfolio. Creating a new one just for WhatsApp usually means Meta blocks access until you've sent them verification documents.

6. Under Requirements, click Next.

7. On the Overview step, click Go to dashboard.

Configure webhooks

For the next few steps you'll be copying values between the Meta developer portal and Connect, so keep both open in separate tabs.

8. Go to https://connect.cosoft.co.uk/apps.

9. Click Configure WhatsApp. If you're not an admin in Connect, this option won't be there.

10. Copy the callback URL.

11. Back in the Meta developer portal, on your app dashboard, click Use cases.

12. Next to Connect with customers through WhatsApp, click Customize.

13. In the left-hand panel, under Other tools, click Tools.

14. Scroll down to Configuration and click Webhooks.

15. Paste the callback URL you copied from Connect into the Callback URL field.

16. Switch back to Connect and copy the verify token.

17. Switch back to the Meta developer portal and paste the verify token.

18. Click Verify and save.

19. Scroll down to the Messages webhook and click the toggle to subscribe to it.

Add a system user and generate an API key

20. Open https://business.facebook.com/home/accounts in a new tab. This is Meta Business Suite, a different site from the developer portal you've been using.

Click the account dropdown at the top left.

21. Click the settings cog next to the business portfolio you're linking WhatsApp to.

22. Click System users.

23. Click Add.

24. Enter connect as the system user name, choose Admin as the role, then click Create system user.

25. Click Assign Assets.

26. Tick the Connect app you created earlier, then select Manage app under Full control.

27. Click Assign assets.

28. Click Done.

29. Click Generate token.

30. Select your Connect app from the dropdown and click Next.

31. Set the token expiry to Never, then click Next.

32. Open the permissions dropdown and search for whatsapp. Tick both whatsapp_business_messaging and whatsapp_business_management.

33. Check the dropdown says "2 options selected", then click Generate token.

34. Click Copy.

35. Switch back to Connect and paste in the API key.

You'll generate three values across the next few steps: this API key, an app secret, and a phone number ID. Paste each one somewhere temporary as you go, so nothing is lost if the Connect tab closes before you've saved.

36. Back in the Meta Business Suite tab, click Done. There's nothing else to do there, so you can close that tab.

Get your app secret

37. Back in your Meta developer portal tab, click Basic under App settings.

38. Click Show next to the App secret field. You'll be asked for your Facebook password.

39. Select the app secret value and copy it.

40. Switch back to Connect and paste in the app secret.

Add a phone number

This is the point to delete your existing WhatsApp Business account, if you have one on the number you're about to add.

41. In the Meta developer portal, click Use cases.

42. Next to Connect with customers through WhatsApp, click Customize.

43. Click API Setup.

44. Open the phone number dropdown and click Add phone number.

45. Enter your business details, then click Next.

46. Enter the phone number you want to use, then click Next.

47. If Meta says the number is already registered, follow Meta's instructions to delete it from the device it's registered on.

Two things worth knowing here:

• Read the advice at the top of this guide about backing up your messages before you delete an existing account.
• If the Next button won't respond, delete the last digit of the number and type it again. That usually reactivates it.

48. Once the number is verified, check it's selected in the From dropdown, then copy the WhatsApp Business Account ID.

Take care to copy the Business Account ID and not the phone number ID. They sit next to each other and are easy to mix up.

49. Back in Connect, paste in the WhatsApp Business Account ID.

50. Click Save.

Add the phone number to Connect

51. Your phone number should now show under Ready to add in the Connect WhatsApp settings. Click the green plus button next to it.

52. Once it's added you may see an icon next to the number showing that WhatsApp is still verifying it. That goes away on its own.

If you see errors about your API key or WhatsApp Business ID, go back and check the permissions you assigned to the API key in step 32. Changes take a few minutes to propagate from WhatsApp, so wait 10 minutes and refresh before assuming something is wrong.

53. If there's a Register button next to the phone number, click it.

54. You'll be asked for a 6-digit PIN.

55. What you enter depends on whether the number already has two-step verification:

• If it does, enter that number's existing 6-digit two-step verification PIN.
• If it doesn't, choose any 6-digit number. That becomes the number's two-step verification PIN, so make a note of it.

Publish your app

56. In the Meta developer portal, click Publish.

Meta may ask you to complete some requirements before it will let you publish, and what those are depends on how your business is set up.

57. Once you've dealt with any requirements, click Publish.

Test the integration

WhatsApp should now be live in Connect. Give it a few minutes for the new settings to sync before you test.

58. Click Messages in Connect.

59. From another WhatsApp device, send a message to your business number. It should turn up in Connect.

If it doesn't appear, refresh your browser, or log out and back in to make sure Connect has picked up the new settings.

60. Reply and send, to check messaging works both ways.

That's the setup done. See Using WhatsApp for the day-to-day detail, including the 24-hour reply window WhatsApp enforces.