Overview

This article takes you through the steps needed for you to get started using WhatsApp with Vonage’s Messages and Dispatch API. Your WhatsApp number will have already been onboarded; the instructions below will help you access and use it.

Set Up WhatsApp Profile

To set up the WhatsApp Profile, follow the steps below:

1. Navigate to your Vonage API account dashboard.
2. From the left menu, select Messages and Dispatch.
3. Select Social Channels.
4. From the drop-down on the Social Channels page, select the API Key associated with the WhatsApp Number. If the WhatsApp number does not appear here, try searching for it under other API keys via the drop-down list.
5. To proceed to the profile edit page, select Edit.
   
6. On the profile's Edit page, fill in the WhatsApp profile information and upload a profile picture.
7. Select Save.
8. Sometimes the profile picture can look distorted at first. Save the settings and refresh the page.
9. Refer to the requirements for each field above the necessary boxes.
   

Plan Your Configuration

When planning your Configuration, consider the following:

• Will you use HTTP Basic authentication (username = API key, password = API secret) or JWT (JSON Web Tokens), i.e., tokens derived from a private key, to authenticate your messages? HTTP Basic is less secure but easier to implement than JWT. See our developer documentation for more information on authentication methods.
• In case you have more than one WhatsApp number, is it OK to receive the Message Status notifications for the messages sent from all these numbers in the same webhook? See our developer documentation for more information.
• In case you have more than one WhatsApp number, was each WhatsApp number configured in a different API key or not?
• In case you are using the SMS API too, is it OK to receive the inbound messages (SMS and WhatsApp) in the same webhook? And to receive the SMS Delivery Receipts in the same webhook where the Message Status notifications of WhatsApp are received?

Requests to send WhatsApp messages can be authenticated with HTTP Basic or with JWT.

• When using HTTP Basic, it is not necessary to create Applications. The Message Status notifications of the outbound messages will be delivered in a webhook shared by all the WhatsApp numbers configured in the same API key. Delivery Receipts of SMS sent out using this API key will be delivered to this webhook too.
• When using JWT, it is necessary to create Application(s). Each Application has a private key, from which JWTs are derived. If you need that the Message Status notifications for each WhatsApp number are delivered to different webhooks, you will need to create as many Applications as distinct webhooks you need, and you will have to use the JWTs derived from the private key corresponding to each WhatsApp number.

For the sake of simplicity, we recommend that Inbound Message webhooks work in pairs with Message Status webhooks. This means that, if you are using Applications, we recommend that you use the Inbound Message webhooks defined at Application level, and that if you are not using Applications, that you use the Inbound Message webhook shared by all WhatsApp numbers and SMS numbers / short codes configured in the same API key.

In case you have more than one WhatsApp number and/or you use the SMS API too and, additionally, you want to use HTTP Basic Authentication but you don’t want to use shared webhooks for Inbound Messages and Message Status notifications/Delivery Receipts, you can ask Vonage to create more API keys in your account, so that each WhatsApp number uses their separate pair of webhooks without the requirement to use JWTs.

Based on your decision, you may proceed to Option 1 or Option 2.

Option 1—Using HTTP Basic without Applications

Use this procedure when you are OK with receiving the Message Status notifications of WhatsApp, and the Delivery Receipts of SMS if sending SMS, to one shared webhook, and when you are OK with receiving the Inbound Messages of all your WhatsApp numbers and SMS number / short codes in a shared webhook.

1. Navigate to your Vonage API account dashboard.
2. Expand the menu by selecting your username.
3. Select Settings.
4. In the drop-down menu, choose the API key for which the WhatsApp number has been configured.
5. Under Default SMS settings:
   • In the Delivery Receipts field, enter the URL of the Message Status webhook.
   • In the Inbound Messages field, enter the URL of the Inbound Message webhook.
   • Set the HTTP Method to POST or POST-JSON (both values are valid and their difference only affect how inbound SMS are notified, not inbound WhatsApp messages).
6. Select Save Changes.
   

Option 2—Using JSON Web Tokens (JWT) with Applications

See the steps below for reference on how to create a Messages and Dispatch Application. Our developer documentation walks through the process in more detail.

1. Navigate to your Vonage API account dashboard.
2. From the menu, select Your applications.
3. In the drop-down menu, choose the API key for which the WhatsApp number has been configured.
4. Select Apply.
5. Select Create a New Application.
6. On the Create an Application page, give a friendly name to your Application.
7. Under Capabilities settings:
   • Enable the Messages capability.
   • Fill in the URLs of the Inbound Messages webhook and Message Status webhook.
8. Under Authentication, select Generate Public and Private Key. One file, normally named private.key, will be downloaded automatically. Store this file securely, as it contains the private key of the Application.
9. Select Generate New Application.
   
10. On the following page, select the Link Social Channels tab. You will see all the WhatsApp numbers configured in the API key of this Application.
    
11. Select Link to link the WhatsApp number to this Application.
12. If you need to create more Applications, repeat this process. Note that each WhatsApp number can be linked to a maximum of one Application.

Start Sending Messages

Congratulations! You are now ready to get started. Below are some other great resources to help your team get started creating and exchanging messages with WhatsApp users.

• Messages API Concept Overview
• Messages API Definitions and Code Snippets
• How to Create a Messages and Dispatch Application in Vonage API Dashboard
• How to Configure the Webhooks
• WhatsApp Message Template Guidelines
• WhatsApp Quality Rating and Messaging Limits Information

WhatsApp Analytics

To view your WhatsApp usage & analytics, follow the steps below:

1. Log in to your Facebook Business Account to access your Whatsapp Manager Dashboard.
   • Make sure that you are on the Vonage business page; from the drop-down in the upper right, select Vonage.
   • On the left, under Accounts, select WhatsApp Accounts.
   • Select your Company WABA.
   • On the Settings tab, navigate to your WhatsApp Manager.
2. Analytics can be viewed on the Insights tab at the left panel.
3. Select the WhatsApp phone number you want to view.
4. Select the country and time period to get the information required.
   

Note that there may be small discrepancies between the data shown in the WhatsApp portal and the data shown on our invoices. For more information, click here.