Get Started

This guide helps you get started with Cloud API and is intended for people developing for themselves or their organization, not on behalf of a client. If you're developing on behalf of a client, see this form. All developers must follow our 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 Cloud API and 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. If you are asked to choose a Use Case as part of the app creation flow, choose Other as your use case, then select Business.

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. This will:

1. Associate your app with the Business Manager account that you selected earlier (or had created for you).
2. Generate a WhatsApp Business Account.
3. Generate a test business phone number and associate it with your WhatsApp Business Account. You can use this number with the API to send an unlimited number of messages to up to 5 recipient phone numbers. Recipient phone numbers can be any valid number, but you must verify each one in the next step.
4. Redirect you to the WhatsApp > Getting Started (or Setup) panel in the App Dashboard.

2. Send a Test Message

In the WhatsApp > Getting Started (or Setup) panel:

1. Select your test phone number in the From field.
2. Enter the recipient 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 pre-approved message template to that number. Message templates are the only type of message that can be sent to customers who have yet to message you, or have not messaged you in the last 24 hours. Thus, message templates are primarily used to open marketing, utility, and authentication conversations with customers.

   The updated code sample will look something like this:

   curl -i -X POST \
     https://graph.facebook.com/v17.0/105954558954427/messages \
     -H 'Authorization: Bearer EAAFl...' \
     -H 'Content-Type: application/json' \
     -d '{ "messaging_product": "whatsapp", "to": "15555555555", "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 panel 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 not 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 Existing WhatsApp Number to a Business Account 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 Add a Phone Number .

Opt-In

You are required to obtain user opt-in before opening marketing, utility, and authentication conversations with customers.

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.

If you’re a developer who is developing for yourself or your organization, not on behalf of a client, you may add a credit card to your WhatsApp Business account. To set up a credit card as 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. Currently only Visa and Mastercard are supported.

There are six currencies available for payment: USD, AUD, EUR, GBP, IDR, INR. Credit card payment method is available if you’re located in any of the countries listed in the Business Manager Supported Countries for WhatsApp Business Credit Card Billing help center article.

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

Scale Conversations

To be able to open more marketing, utility, and authentication conversations, 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.