How to use WhatsApp cloud API to send messages from your backend

In 2022, WhatsApp introduced their cloud messaging API that helps developers build WhatsApp messaging capabilities in their applications without using a third party WhatsApp API service such as Twilio.

In this tutorial, we'll learn how to setup and use the WhatsApp cloud API on a backend application. There are few steps to setup the cloud messaging account before we can use the API to send messages.

Setting up the Facebook app

In order to send WhatsApp messages programatically, you should create a Facebook app first. For that, goto https://developers.facebook.com, click on My Apps menu on top.

Click on the Create App button.

Choose the "Other" option in the next screen.

Choose Businessas the app type.

Add an app name, and your contact email and click the Create app button. Make sure not to use keywords like WhatsApp in the app as they are not allowed.

In the next screen, scroll down to the bottom and Set up WhatsApp to the newly created Facebook app. This enables the WhatsApp Cloud API functionality in your app.

Click on continue and then you'll be redirected to the WhatsApp app dashboard.

Getting the credentials

Now you've successfully created a Facebook app for using the WhatsApp cloud API. Now, you need the following credentials for accessing the WhatsApp message API.

Phone number ID

This is the ID of the From phone number you use to send WhatsApp messages. By default, there will be a free test phone number. Note that, the phone number and phone number ID is different. What you need to use in the API is the Phone number ID.

Access Token

You need an access token to authenticate the API via the Authorization: Bearer header. You can view the temporary access token from the API Setup menu on the left side.

Using the API

The endpoint of the WhatsApp cloud messaging API is

https://graph.facebook.com/v18.0/<PHONE_NUMBER_ID>/messages

You should authenticate it via the Authorization: Bearer <ACCESS_TOKEN> header.

And the body of the API call is

{
      "messaging_product": "whatsapp",
      "recipient_type": "individual",
      "to": "<TO_WHATSAPP_NUMBER>",
      "type": "text",
      "text": {
        "body": "Hey, this is a test message"
        }
    }

Depending on the message type, the request body changes.

You can get the list of supported message types and their request body structure from this link

Adding a real phone number

Once you have used the WhatsApp API to send a test message, you should add a real phone number to be used as the From Number.

For this, goto Configuration menu on the left side, navigate to the Phone Numbers section.

Also, there is an option to generate a permanent access token for your WhatsApp cloud API which might be required for your actual production use case.

Conversation Categories and Free Tier

WhatsApp conversations are categorized into one of the following categories:

• Marketing — Promotions, awareness, onboarding etc.

• Utility — Messages of transactional nature such as order confirmation

• Authentication — One time passwords, recovery information etc

• Service — Message that replies to customer enquiries.

Except for the Service messages, all other messages need to have a template. Service message can be responded within window period when a customer has replied to your message.

Every month, 1000 service messages are included in the free tier!

To read more about WhatsApp cloud API pricing and categories, read this guide.