Using Authorization Tokens for the WhatsApp Business Platform

The WhatsApp Business Platform makes it easy to send WhatsApp messages to your customers and automate replies. Here, we’ll explore authentication using the Cloud API, hosted by Meta.

We’ll start with generating and using a temporary access token and then replace it with a permanent access token. This tutorial assumes you’re building a server-side application and won’t need additional steps to keep your WhatsApp application secrets securely stored.

Managing Access and Authorization Tokens

First, let’s review how to manage authorization tokens and safely access the API.

Prerequisites

Start by making sure you have a developer account on Meta for Developers. You’ll also need WhatsApp installed on a mobile device to send test messages to.

Creating an App

Before you can authenticate, you’ll need an application to authenticate you.

Once you’re signed in, you see the Meta for Developers App Dashboard. Click Create App to get started.

Next, you’ll need to choose an app type. Choose Business.

After that, enter a display name for your application. If you have a business account to link to your app, select it. If not, don't worry. The Meta for Developers platform creates a test business account you can use to experiment with the API. When done, click Create App.

Then, you’ll need to add products to your app. Scroll down until you see WhatsApp and click the Set up button:

Finally, choose an existing Meta Business Account or ask the platform to create a new one and click Continue:

And with that, your app is created and ready to use. You’re automatically directed to the app’s dashboard.

Note that you have a temporary access token. For security reasons, the token expires in less than 24 hours. However, you can use it for now to test accessing the API. Later, we’ll cover how to generate a permanent access token that your server applications can use. Also, note your app’s phone number ID because you’ll need it soon.

Click the dropdown under the To field, and then click Manage phone number list.

In the popup that appears, enter the phone number of a WhatsApp account to send test messages to.

Then, scroll further down the dashboard page and you’ll see an example curl call that looks similar to this:

curl -i -X POST https://graph.facebook.com/v13.0/<YOUR PHONE NUMBER ID>/messages -H 'Authorization: Bearer <YOUR ACCESS TOKEN>' -H 'Content-Type: application/json' -d '{ "messaging_product": "whatsapp", "to": "<PHONE NUMBER TO MESSAGE>", "type": "template", "template": { "name": "hello_world", \"language\": { \"code\": \"en_US\" } } }'

Note that the Meta for Developers platform inserts your app’s phone number ID and access token instead of the <YOUR PHONE NUMBER ID> and <YOUR ACCESS TOKEN> placeholders shown above. If you have curl installed, paste the command into your terminal and run it. You should receive a “hello world” message in WhatsApp on your test device.

If you’d prefer, you can convert the curl request into an HTTP request in your programming language by simply creating a POST request that sets the Authorization and Content-Type headers as shown above, including the JSON payload in the request body.

Since this post is about authentication, let’s focus on that. Notice that you’ve included your app’s access token in the Authorization header. For any request to the API, you must set the Authorization header to Bearer <YOUR ACCESS TOKEN>.

Remember that you must use your token instead of the placeholder. Using bearer tokens will be familiar if you’ve worked with JWT or OAuth2 tokens before. If you’ve never seen one before, a bearer token is essentially a random secret string that you, as the bearer of the token, can present to an API to prove you’re allowed to access it.

Failure to include this header causes the API to return a 401 Unauthorized response code.

Creating a Permanent Access Token

Knowing that you need to use a bearer token in the Authorization header of an HTTP request is helpful, but it’s not enough. The only access token you’ve seen so far is temporary. Chances are that you want your app to access the API for more than 24 hours, so you need to generate a longer-lasting access token.

Fortunately, the Meta for Developers platform makes this easy. All you need to do is add a System User to your business account to obtain an access token you can use to continue accessing the API. To create a system user, do the following:

• Go to Business Settings.

• Select the business account your app is associated with.
• Below Users, click System Users.
• Click Add.
• Name the system user, choose Admin as the user role, and click Create System User.
• Select the whatsapp_business_messaging permission.
• Click Generate New Token.
• Copy and save your token.

Your access token is a random string of letters and numbers. Now, try re-running the earlier request using the token you just created instead of the temporary one:

curl -i -X POST https://graph.facebook.com/v13.0/<YOUR PHONE NUMBER ID>/messages -H 'Authorization: Bearer <YOUR ACCESS TOKEN>' -H 'Content-Type: application/json' -d '{ "messaging_product": "whatsapp", "to": "<PHONE NUMBER TO MESSAGE>", "type": "template", "template": { "name": "hello_world", \"language\": { \"code\": \"en_US\" } } }'

Your test device should receive a second hello message sent via the API.

Best Practices for Managing Access Tokens

It’s important to remember that you should never embed an App Access Token in a mobile or desktop application. These tokens are only for use in server-side applications that communicate with the API. Safeguard them the same way you would any other application secrets, like your database credentials, as anyone with your token has access to the API as your business.

If your application runs on a cloud services provider like AWS, Azure, GCP, or others, those platforms have tools to securely store app secrets. Alternatively there are freely-available secret stores like Vault or Conjur. While any of these options may work for you, it’s important to evaluate your options and choose what works best for your setup. At the very least, consider storing access tokens in environment variables and not in a database or a file where they’re easy to find during a data breach.

Conclusion

In this post, you learned how to create a Meta for Developers app that leverages the WhatsApp Business Platform. You now know how the Cloud API’s bearer access tokens work, how to send an access token using an HTTP authorization header, and what happens if you send an invalid access token. You also understand the importance of keeping your access tokens safe since an access token allows an application to access a business’ WhatsApp messaging capabilities.

Why not try using the Cloud API, hosted by Meta if you're considering building an app for your business to manage WhatsApp messaging? Now that you know how to obtain and use access tokens, you can use them to access any endpoint in the API.