Get Started With the WhatsApp Business Cloud API

This guide helps you get started with the WhatsApp Business Platform, and is intended for people developing for themselves or their organization, not on behalf of a client. All developers must follow WhatsApp’s Commerce Policy.

To send and receive a first message using a test number, complete the following steps:

1. Set up developer assets and platform access
2. Send a test message
3. Configure a Webhook
4. Receive a test message

Once you’re ready to use your app for a production use case, check the Next Steps section.

1. Set up Developer Assets and Platform Access

The WhatsApp Cloud API and WhatsApp Business Management API are part of Meta’s Graph API, so you need to set up a Meta developer account and a Meta developer app. To set that up:

• Register as a Meta Developer
• Enable two-factor authentication for your account
• Create a Meta App: Go to developers.facebook.com > My Apps > Create App. Select the "Business" type and follow the prompts on your screen.

From the App Dashboard, click on the app you would like to connect to WhatsApp. Scroll down to find the "WhatsApp" product and click Set up.

Next, you will see the option to select an existing Business Manager (if you have one) or, if you would like, the onboarding process can create one automatically for you (you can customize your business later, if needed). Make a selection and click Continue.

When you click Continue, the onboarding process performs the following actions:

• Your App is associated with the Business Manager that you chose, or that was created automatically.
• A WhatsApp test phone number is added to your business. You can use this test phone number to explore the WhatsApp Business Platform without registering or migrating a real phone number. Test phone numbers can send unlimited messages to up to 5 recipients (which can be anywhere in the world).

After that, your browser navigates to the Getting Started tab, where you can learn about and experiment with the WhatsApp Business Platform. The Getting Started tab contains tools and information to help you send test messages. It can be used with test phone numbers and any of your own phone numbers that you register.

2. Send a Test Message

In the Getting Started tab:

1. Select your test phone number in the From field. (Unless you have registered other phone numbers, this will be the only phone number in From.)
2. Enter the phone number you would like to message in the To field. Ensure the number is correct, and that you want to add it to your list of 5 possible message recipients —as you add phone numbers, follow the prompts on the screen to verify you have access to them. Once this number has been added, it cannot be removed from your list. Note: This limitation is only for WhatsApp-provided test phone numbers. Real phone numbers that you register do not have a limit on the number of recipients.
3. Once you enter a recipient phone number, the code sample on the page will be updated to demonstrate an API call that sends a test message to that number. The code sample will look something like this:

   curl -i -X POST \
     https://graph.facebook.com/v12.0/FROM_PHONE_NUMBER_ID/messages \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{ "messaging_product": "whatsapp", "to": "TO_PHONE_NUMBER", "type": "template", "template": { "name": "hello_world", "language": { "code": "en_US" } } }'
   
4. Finally, click Send message to send the first message. As an alternative, you can copy the code sample provided and execute it in your Terminal or in Postman. You have just sent a test message!

The code sample on the page is formatted for use in Unix-style terminal shells, and is expected to work on MacOS and distributions of Gnu/Linux. If you use Windows, we suggest you perform your first API call using Postman, to avoid platform-related cURL formatting concerns. If you are a Windows 10 user, cURL is available, but requires a different syntax than the one shown in the Getting Started tab to execute in PowerShell or cmd.exe. For more information, see cURL Comes to Windows or cURL for Windows. If you have access to the Windows Subsystem for Linux (WSL), you can also consider launching a Linux distribution and using its terminal.

3. Configure a Webhook

To get alerted when you receive a message or when a message’s status has changed, you need to set up a Webhooks endpoint for your app. Setting up Webhooks doesn’t affect the status of your phone number and does interfere with you sending or receiving messages.

To get started, first you need to create the endpoint. You can create a custom Webhook URL running on a web server, or use services that help you set up an endpoint, such as Glitch. See Create a Sample App Endpoint for Webhooks Testing for help.

Once your endpoint is ready, go to your App Dashboard.

4. Receive a test message

Now that your Webhook is set up, send a message to the test number you have used. You should immediately get a Webhooks notification with the content of your message!

Next Steps

Phone Number

When you’re ready to use your app for a production use case, you need to use your own phone number to send messages to your users. When choosing a phone number, consider the following:

• If you want to use a number that is already being used in the WhatsApp customer or business app, you will have to fully migrate that number to the business platform. Once the number is migrated, you will lose access to the WhatsApp customer or business app. See Migrate App Phone Number to Business Platform for information.
• We have a set of rules regarding numbers that can be used in the platform. Learn more .
• Once you have chosen your phone number, you have to add it to your WhatsApp Business Account. See How to Connect Your Phone Number to Your WhatsApp Business Account .

Opt-In

You are required to obtain user opt-in before sending proactive business-initiated messages. See Get Opt-In for WhatsApp for more information.

Pricing & Payment Methods

Businesses are charged per conversation, which includes all messages delivered in a 24 hour session. The first 1,000 conversations each month are free. If you want to send more than 1,000 conversations, you need to add a credit card to your account.

To set up a payment method, go to App Dashboard > WhatsApp > Configuration. Under Phone numbers, click Manage phone numbers. This leads you to your Business Manager account, where you can click Add Payment Method to add your credit card.

Credit card billing via Visa or Mastercard is the only available payment method. There are six currencies available for payment: USD, AUD, EUR, GBP, IDR, INR. Currently, payment by credit card is available if you are located in any of the following countries:

For more information, see Add a Credit Card to Your WhatsApp Business Platform Account .

Send More Messages

To send more business-initiated messages, you need to use message templates. WhatsApp message templates are specific message formats that businesses use to send out notifications or customer care messages to people that have opted in to notifications.

Before sending a message template, you need to create one or you can use one of our pre-approved templates. Check this guide to learn how to send message templates.

Incoming messages are unlimited, but there are limits for outgoing messages. See Messaging Limits for more information on messaging tiers.