Understanding WhatsApp messaging
Starting June 1st 2023 WhatsApp will switch to a use case based pricing model for all businesses globally sending WhatsApp messages. Price changes will only apply to WhatsApp fees. There will not be any changes to Vonage platform fees. Information on the WhatsApp Business Platform pricing changes, can be found on the WhatsApp website.
WhatsApp Business Solution messages can only be sent by businesses that have been approved by WhatsApp. This business profile will also have a green verified label to indicate that it is a legitimate business.
The advantage of WhatsApp is that the identifier of users on the platform is their mobile phone number.
NOTE: WhatsApp is in Limited Availability and Vonage cannot guarantee you will receive a WhatsApp account.
Setting up a WhatsApp Business Account
You can sign up for a WhatsApp Business Account via the Vonage API Dashboard. Navigate to the Social channels page of the Dashboard and select the option to set up a WhatsApp Business Account.
Using existing WhatsApp Business Number
If you already have a WhatsApp Business Number and would like to use that number with the Vonage Messages API, the WhatsApp Product page has more details about how to get started using WhatsApp with Vonage.
NOTE: Once a WhatsApp number is integrated with the API it cannot be used in the mobile app.
Rules for Messaging Customers
WhatsApp has a concept of a 24 hour customer care window, during which a business can freely message an end user. The 24 hour window can be initiated in two ways:
- An end user sends a message to the business
- A business sends a templated message to the end user. The 24 hour window starts as soon as the end user replies.
Templates must be approved by WhatsApp before they can be used to send messages to an end user. When the 24 hour window expires, a new 24 hour customer care window must be initiated again. It is important to be aware that 24 hour customer care windows are not the same as the 24 hour billable conversation window.
WhatsApp Conversation-Based Pricing
Vonage now offers a Conversation-Based Pricing model for WhatsApp messaging. This is in line with the pricing model introduced by WhatsApp at the start of February 2022.
- What is a conversation? A conversation is any number of messages sent within a 'session', which is defined as a 24 hour period starting from the time the first message is sent by the business.
- Who initiates a conversation? A conversation can be initiated either by a customer (user-initiated) or business (business-initiated), but in either case the 'session' begins with the first message sent by the business..
- How does Vonage price conversations? The Vonage pricing for WhatsApp messaging is made up of two components:
- A Vonage platform fee - this is priced per conversation
- A WhatsApp fee - Currently, this is also priced per conversation. Starting June 1st, this is priced per conversation and conversation type. There are now four conversation categories, each of which are charged at different rates:
- Utility Conversation - Enable the completion of a particular, agreed-upon request or transaction or provide a customer with an update about an ongoing transaction, including post-purchase notifications and regular billing statements.
- Authentication Conversation - Enables businesses to utilize one-time passcodes to verify users at various login stages, if necessary (e.g. account verification, account recovery, integrity challenges)
- Marketing Conversation - Business-initiated conversations to market a good or service to customers, such sending pertinent offers to customers who have opted in. This would also include any business-related interaction that is not an authentication or utility conversation.
- Service Conversation - User-initiated discussions that assist consumers in getting answers to their questions.
- If a conversation contains more than one category of message, you will be charged for both conversation types:
- Business-initiated conversations must be started with a template message.
- The business-initiated conversation types each map to a specific template category for that type.
- If the business initiates a conversation with one type of template but subsequently (within the current 24 hour conversation window) sends another template message of a different category, then a new conversation window is started and is billed at rate for the type of conversation which maps to that template category.
IMPORTANT: Existing customers will by default remain on their current pricing model by default at the current per message pricing, with the option to move to the new conversation based pricing model.
For more information on Vonage WhatsApp pricing, see the Messages API pricing page. Further information on the Conversation-Based Pricing model can be found in the WhatsApp developer documentation
NOTE: Since WhatsApp pricing is per conversation rather than per message, it is not possible to provide an accurate price per message. Therefore, the value given for the price property in the usage object contained in the body of a Message Status callback will be the default price per conversation rather than the actual price for each message.
Data identifying the conversation to which a message relates is available in Message Status callbacks for messages that have a status of delivered.
WhatsApp Number Hosting
We have two ways of managing WhatsApp numbers. We can either host your number on our servers using WhatsApp’s On-premises solution (Vonage hosting), or handle it directly in WhatsApp’s Cloud solution (WhatsApp hosting).
In the majority of cases, you will receive the same service, as Vonage takes care of the delivery of messages to and from your business. There are, however, some slight differences to be aware of.
| Vonage Hosting | WhatsApp Hosting | |
|---|---|---|
| Message Throughput | Around 20 messages per second by default, and this can be scaled on request | Auto-scales to around 80 messages per second |
| Encryption | Messages are end-to-end encrypted between Vonage and end users using the signal protocol | Messages are sent securely to WhatsApp’s service where they are decrypted before being passed through the WhatsApp networks securely using the Signal protocol to end users |
| Feature differences | Only static third-party outbound stickers are supported in addition to all types of inbound stickers. A static sticker cannot exceed 100 KB. Animated stickers are not supported. | Static and animated third-party outbound stickers are supported in addition to all types of inbound stickers. A static sticker cannot exceed 100 KB. An animated sticker cannot exceed 500 KB. |
NOTE: WhatsApp numbers provisioned on WhatsApp Cloud Hosting are currently unable to send messages to the following destinations:
- Turkey
Which Option Should You Choose?
Unless you specifically need the stickers feature or need to send messages to the destinations listed in the above note, for new customers setting up their WhatsApp account directly through the Vonage dashboard we recommend using WhatsApp’s hosting as we can get your number ready instantly.
How to enable WhatsApp’s number hosting
For a number to be hosted on WhatsApp servers, customers must create a WhatsApp Business Account using Vonage Dashboard External Accounts. When your WhatsApp number is provisioned there will be an option to use WhatsApp hosting.
Transferring existing numbers
Although it isn't currently possible to transfer already provisioned numbers between the two hosting solutions, we will soon provide a service to move numbers hosted on Vonage servers (using WhatsApp's On-premises solution) to WhatsApp’s Cloud hosting, and vice versa.
WhatsApp message types
There are a number of different WhatsApp message types:
| Message Type | Description |
|---|---|
| Text Message | A plain text message. This is the default message type. |
| Media Message | A media message. Types are: image, audio, document and video. |
| Message Template | Message Templates are created in the WhatsApp Manager. Outside of the Customer Care Window messages sent to a customer must be a Message Template type. Only templates created in your own namespace will work. Using an template with a namespace outside of your own results in an error code 1022 being returned. |
| Media Message Templates | Media message templates expand the content you can send to recipients beyond the standard message template type to include media, headers, and footers using a components object. |
| Contacts Message | Send a contact list as a message. |
| Location Message | Send a location as a message. |
| Interactive Message | The Vonage Messages API v1 supports two types of WhatsApp Interactive Messages: List Messages, Reply Buttons, and Product Messages. Read more |
How WhatsApp works
A business can start a conversation with a user and a user can start a conversation with a business.
WhatsApp has a core concept of Messages Templates (MTM). These were previously known as Highly Structured Messages (HSM).
IMPORTANT: WhatsApp requires that a message that is sent to a user for the first time, or that is outside the Customer Care Window, be an MTM message. WhatsApp also requires that you obtain opt-in from your customers prior to sending them a message, this may be obtained on your website, IVR, or other standard means see Facebook's docs for more details.
The MTM allows a business to send only the template identifier along with the appropriate parameters instead of the full message content.
NOTE: New templates need to be approved by WhatsApp. Please contact your Vonage API Account Manager to submit the templates. Only templates created in your own namespace are valid. Using an template with a namespace outside of your own results in an error code 1022 being returned.
NOTE: Templates are subject to a restriction of 60 characters in their header and footer, and 1024 characters in their body.
MTMs are designed to reduce the likelihood of spam to users on WhatsApp.
For the purpose of testing Vonage provides a template, whatsapp:hsm:technology:nexmo:verify, that you can use:
The parameters are an array. The first value being {{1}} in the MTM.
Below is an example API call:
WhatsApp deterministic language policy
NOTE: WhatsApp deprecated the "fallback" locale method when sending template messages on January 1st 2020. As of April 8, 2020, messages bearing the "fallback" policy will fail with a 1020 error in your message status webhook.
When a message template is sent with the deterministic language policy, the receiving device will query its cache for a language pack for the language and locale specified in the message. If not available in the cache, the device will query the server for the required language pack. With the deterministic language policy the target device language and locale settings are ignored. If the language pack specified for the message is not available an error will be logged.
Further information is available in the WhatsApp documentation.
WhatsApp Provisioning API
The WhatsApp Provisioning API enables you to deploy a WhatsApp cluster, perform one time password (OTP) verification, and update profile information for a WhatsApp business account.
The steps you must take to provision your WhatsApp cluster are:
Secure a WhatsApp Business account and phone number. Contact your Account Manager or visit this page to get started.
Use the Vonage API Dashboard to manage your WhatsApp Business profile.
WhatsApp Template Management API
The WhatsApp Template Management API allows you to programmatically list existing WhatsApp templates, create new templates, delete templates, and upload media for use in templates.
You can read more in the WhatsApp Template Management API guide.
Further information
- Custom objects
- Interactive Messages: Overview
- Working with Interactive Messages
- Product Messages: Overview
- WhatsApp Outbound Reply Messages