This step-by-step tutorial provides information on how to send your first message. See Before You Start to get a list of the assets you need to have before completing this tutorial.
This guide is divided into three stages:
- Stage 1: Prepare – First, get the access token you need to use in all of the following API calls. Then, you set up your Webhooks and subscribe to your WABA. Finally, get a phone number’s ID and register it.
- Stage 2: Enable the customer service window – When certain customers send a message to a business, that business gets 24 hours of free messages with them. For testing purposes, we want to enable this window, so you can send as many messages as you would like. To do that, send a test message from the consumer app to the phone number you just registered. Once the message is received, you get a Webhook notification with that number’s WhatsApp ID.
- Stage 3: Send a message – With a registered phone number, a system user access token, and the WhatsApp ID or the phone number for the person you want to reach, you can send your first message.
If you are a Business Service Provider (BSP), you need to have Embedded Sign Up integrated to use the Cloud API. For more information, see Embedded Signup Overview.
Before You Start
Businesses setting up their integration need to have the following assets:
| Asset | Specific Instructions |
|---|---|
| Business Manager | You can use an existing, or set up a new one. Save the Business Manager ID. |
| WhatsApp Business Account (WABA) | See Create a WhatsApp Business Account for the WhatsApp Business API for help. |
| Meta App | If you don’t have an app, you need to create one with the “Business” type. Remember to add a display name and a contact email to your app. Your app must go through App Review and request Advanced Access to the following permissions: whatsapp_business_management — Used to manage phone numbers, message templates, registration, business profile under a WhatsApp Business Account. To get this permission, your app must go through App Review.whatsapp_business_messaging — Used to send/receive messages from WhatsApp users, upload/download media under a WhatsApp Business Account. To get access to this permission, reach out to your representative and provide your Meta app ID.If you’re working as a BSP (Business Solution Provider), feel free to use the same Meta app across different clients and WABAs. But be aware that each app can only have one webhook endpoint. |
| System User | See Add System Users to Your Business Manager for help. Currently, a Meta App with whatsapp_business_messaging and whatsapp_business_management permissions has access to up to:1 admin system user, and1 employee system userWe recommend using the admin system user for your production deployment. See About Business Manager Roles and Permissions for more information. |
| Business Phone Number | This is the phone number the business will use to send messages. Businesses must use a test phone number for this release. Use your existing WhatsApp Manager to add a phone number. Phone numbers need to be verified through SMS/voice call, either through Embedded Signup flow or manual verification. You cannot verify your phone with Graph API. The verification status of a phone number doesn’t impact the migration between On-Premises and Cloud API. If you don’t have access to Embedded Signup to verify phone numbers, we recommend verifying the phone numbers using the On-Premises solution, and then migrating those numbers to the Cloud API. There is no limit to the amount of business phone numbers that can be onboarded to the Cloud API. A single phone number can only be used on one platform at a time: One phone number for Cloud API and another number for On-Premises. This means that you cannot use a production phone number with both the On-Premises and Cloud APIs. We recommend doing any testing with a test number (either an existing test number or a new one) and then moving your own phone number to the Cloud API when you’re confident you’re ready for production use. |
| Consumer Phone Number | This is a phone number that is currently using the consumer WhatsApp app. This number will be receiving the messages sent by your business phone number. |
Step 1: Get System User Access Token
Graph API calls use access tokens for authentication. For more information, see Access Tokens. We recommend using your system user to generate your token.
To generate a system user access token:
- Go to Business Manager > Business Settings > Users > System Users to view the system user you created.
- Click on that user and select Add Assets. This action launches a new window.
- Under Select Asset Type on the left side pane, select Apps. Under Select Assets (in the middle pane), choose the Meta app you want to use (your app must have the correct permissions). Enable Develop App for that app.
- Select Save Changes to save your settings and return to the system user main screen.
- Now you are ready to generate your token. Still on the system user main screen, click Generate Token and, again, select your Meta app. After selecting the app, you see a list of available permissions. Select
whatsapp_business_managementandwhatsapp_business_messagingand click Generate Token. - A new window opens with your system user, assigned app and access token. Save your token.
- Optionally, you can click on your token and see the Token Debugger. In your debugger, you should see the two permissions you have selected. You can also directly paste your token into the Access Token Debugger.
Step 2: Set up Webhooks
With Webhooks set up, you can receive real-time HTTP notifications from the WhatsApp Business Platform. This means you get notified when, for example, you get a message from a customer or there are changes to your WhatsApp Business Account (WABA).
To set up your Webhook, you need to create an internet-facing web server with a URL that meets Meta’s and WhatsApp’s requirements. See Creating an Endpoint for instructions on how to do that. If you need an endpoint for testing purposes, you can generate a test Webhooks endpoint.
App Setup
Once the endpoint is ready, configure it to be used by your Meta app:
In your App Dashboard, find the WhatsApp product and click Settings. Scroll down until you find the webhooks section and click Configure a webhook. After the click, a dialog appears on your screen and asks you for two items:
- A callback URL: This is the URL Facebook will be sending the events to. See the Webhooks, Getting Started guide for information on creating the URL.
- A verification token.
After adding the information, click Verify and Save.
Back in the settings section of your App Dashboard, you will see the Webhooks section has been updated with the information you just provided. Under the callback URL and the token, you will see the Webhook fields —those are the fields you want to get in your webhook notifications.
Under Webhook fields, click Manage. A dialog box will appear with all the current fields. Click Subscribe for the fields you want to be included in your notifications.
You only need to set up Webhooks once for every application you have. You can use the same Webhook to receive multiple event types from multiple WhatsApp Business Accounts. For more information, see our Webhooks section.
