General

Quick Guide on CBP implementation at Gupshup Self-Serve

As most of you might be aware, starting February 1st, 2022, WhatsApp will switch from a notification-based pricing model to a conversation-based pricing (CBP) model. Instead of being charged for notifications sent, businesses will be charged per conversation, which includes all messages delivered within a 24-hour period.

How does CBP work

Old way of charging WhatsApp fee – Message based pricing
In the Message based pricing model, WhatsApp fee is decided basis ACTIVE WINDOW

Active window is a 24 hour window that starts from “last message” of user and is a moving window. Free text / session messages can be sent in this window WHATSAPP FEE : FREE
Inactive window is when the business can only send pre-approved template messages to opted in users WHATSAPP FEE : Per template message fee basis recipient country
GUPSHUP FEE - is per message for session or template.

New way of charging WhatsApp fee – Conversation based pricing (CBP) (1/2)

In the conversation based pricing model, WhatsApp fee is decided basis combination of - ACTIVE WINDOW + CONVERSATION WINDOW

Active window
Starts from user’s last reply, is a 24 hour moving window with which WhatsApp decides HOW MUCH TO CHARGE and WHAT MESSAGE CAN BIZ SEND (e.g. if user last replies at Day 1, 3pm, Active window ends at Day 2, 3pm, But if user again replies at Day 1, 4pm, Active window extends till Day 2, 4pm)

HOW MUCH TO CHARGE

FOR BIC (Business initiated conversation) OR UIC (user initiated conversation)?

BIC and UIC are decided basis active window.
User initiated DOES NOT mean conversation session starts by user’s message, It starts on reply by biz.
WHATSAPP FEE : Different rates for BIC and UIC for different countries, Applicable in all countries.
GUPSHUP FEE still applies to every message in a conversation session – 0.001 USD pm whether template or session.

WHAT MESSAGE CAN BUSINESS SEND

Same rules of opt-in and preapproved template apply for Biz initiated conversations.
Same rules of active user apply for any message within BIC and UIC (biz can only send free text if user is active).
New way of charging WhatsApp fee – Conversation based pricing (CBP) (2/2)
Conversation window
Starts from biz’s first message, is a 24 hour static window with which WhatsApp decides WHEN DOES THE CHARGE START AND END (e.g. Day 1, 3pm to Day 2, 3pm fixed)

WHEN DOES THE CHARGE START AND END

24-hour conversation session starts from first reply by business
First message is charged by WhatsApp, No further charge on messages in this 24 conversation window
Session initiates on delivery of first message

Examples of WhatsApp fee & Gupshup fee

Other concepts of CBP

Free tier

• The first 1,000 conversations are free in every WABA within each calendar month
• could be UIC or BIC
• Gupshup fee per message will still be charged in this case.

📘

Note: Effective March 01, 2022, the first 1000 conversations in your app will be considered as ‘Free Tier’ and the fee for it will not be deducted. Based on WhatsApp’s final reports received at the end of the month, the amount for these conversations will be adjusted (less or more) in your wallet. Note: Adjustment will be minimal but might be required mainly when one WABA has multiple phone numbers / Gupshup app linkages.

Free entry points (FEP)

• Gupshup fee per message will still be charged in this case Free entry points (FEP)
• Conversations that start from Ads that Click to WhatsApp or Facebook Page CTAs will be free (first UIC by user free)

What changes can you expect in Gupshup self serve with CBP coming in?

Changes in wallet statement
You will soon notice that the wallet statement usage section will be updated in the below format, to accommodate the CBP changes -

Payload changes
To know the payload changes please check - Gupshup API documentation for CBP

📘

Tips: Make sure your Gupshup wallet is recharged enough, to avoid any stoppage due to low balance. (This is likely, since WhatsApp fee component will increase for users doing more of session messaging / UIC)

Why do we see differences between the actual dial numbers and the one registered on WhatsApp, for region: Brazil & Mexico?

What is a WhatsApp ID?

Every number registered on the WhatsApp consumer app(IOS/Android) is associated with a WhatsApp ID. WhatsApp IDs are needed to send messages. Usually, the WhatsApp ID of a number is the dialable format of the number itself. For example, the WhatsApp ID of the number "+1-631-555-1002" will be "+16315551002".

Why do we see differences between the actual dial numbers and the one registered on WhatsApp, for region: Brazil & Mexico?

The Brazilian telephone numbering plan uses a two-digit area code plus eight-digit local phone numbers for landlines and nine digits for mobile lines.

Brazilian mobile phone numbers customarily have nine digits now, but seven digits were usual in the first years, then eight digits became the standard for several years.

With the increasing use of mobile lines, a shortage of available mobile numbers was evident. To overcome this, on December 10, 2010, ANATEL announced the inclusion of a ninth digit (in the format 9NNNN-NNNN) to mobile phone numbers.

The digit '9' was gradually added to the left of all existing mobile numbers in different regions of Brazil, regardless of their former initial digits. So, for example, mobile number +55 (11) 8765-4321 became +55 (11) 98765-4321.

Despite this fact, mobile phones registered outside the 11-19 (São Paulo), 21, 22, 24 (Rio de Janeiro), and 27-28 (Espírito Santo) areas are usually displayed on WhatsApp with the old 8-digit number, since WhatsApp IDs were already present for those numbers before the inclusion of the digit '9'.

Similarly, Mexico has also implemented the following changes in its dialing rules that affect WhatsApp users. When calling a Mexican cell phone from outside Mexico, the additional digit "1" after the country code is no longer required. Essentially, causing inconsistencies between phone numbers registered on WhatsApp and their actual WhatsApp IDs.

What is the impact of dial code and WhatsApp registered phone number while using WhatsApp's Business APIs?

Business initiated conversations

• Consider business initiated first ever conversation with a user with phone number +55 (35) 98765-4321 who has opted-in to receive messages on WhatsApp.
• Using Gupshup's send message API, the business sends messages to the user and creates a conversation C1 with +5535987654321.
• Gupshup provides a message id in return to the business to track the status of the message.
  Gupshup uses WhatsApp’s check contact API to check if the phone number is present on WhatsApp before sending the message. This API provides WhatsApp ID (wa_id) in return if the phone number is present on WhatsApp. In this case, it is +553587654321.
• Gupshup uses WhatsApp ID (wa_id) +553587654321 to send out the message to the user, but the business is unaware of the fact that message was sent to the number without the prefix 9.
• The delivery event has message id, so it is easier for businesses to know if the message was delivered.
• When the user responds to the message, Gupshup sends an inbound message with the phone number as +553587654321 (which is the same as WhatsApp Id).
• Since the business doesn't know that this is the same user +5535987654321, it creates a new conversation C2 with +553587654321

User initiated a conversation
Now, let us say the user initiates the conversation. Gupshup sends the inbound message with the phone number which is the same as WhatsApp Id. Using this, they can opt-in to that number as well and continue the conversation with the user.

Solution
We will send a mismatch event whenever wa_id is different than the phone number mentioned in the API request, below is the sample payload for the same:

This event will help Businesses to manage conversations more effectively and it will be received on the Business’s webhook whenever the destination in the API request doesn’t match the WhatsApp id - which is the actual phone number registered on WhatsApp.

Gupshup will also proactively add the WhatsApp id (phone number without prefix) to the opt-in list of the business.

Refer to following sequence diagram for clarity.

WhatsApp Interactive - Single & Multi-Product Messages

What is a Product Message?

The Product Messages enable businesses to showcase their products and services to their customers without leaving the WhatsApp app.

Let us understand the types of product messages in detail:

• Multi-Product Messages: Messages containing a selection of up to 30 items from a business’ inventory.
• Single Product Messages: Messages with a single product item from the business’ inventory. The product is displayed in a Product Detail Page (PDP) format.

Both Multi-Product Messages and Single Product Messages are types of session interactive messages meaning you are not required to get it approved from WhatsApp, unlike template messages - they cannot be sent as notifications but can only be sent as part of existing conversations.

Users that receive Multi and Single Product Messages can perform 3 main actions.

• View products: Customers can see a list of products or just one product. Whenever a user clicks on a specific item, WhatsApp fetches the product's latest info and displays the product in a Product Detail Page (PDP) format. Currently, PDPs only support product images —any videos and/or GIFs added to the product won’t be displayed in the PDP.
• Add products to a cart: Whenever a user adds a product to the shopping cart, WhatsApp fetches the item’s latest info. If there has been a state change on any of the items, WhatsApp displays a dialog saying “One or more items in your cart have been updated” — See Product Updates given below for more information. A cart persists in a chat thread between business and customer until the cart is sent to the business —See Shopping Cart Experience given below for details.
• Send a shopping cart to the business: After adding all needed items, customers can send their cart to the business they’re messaging with. After that, businesses can define the next steps, such as requesting delivery info or giving payment options.

If a customer has multiple devices linked to the same WhatsApp account, the Multi-Product and Single Product Messages will be synced between devices. However, the shopping cart is local to each specific device. See the Shopping Cart Experience given below for details.

Currently, these types of messages can be received on the following platforms:

• iOS: 2.21.100 (Multi-Product Messages) and 2.21.210 (Single Product Messages).
• Android: 2.21.9.15 (Multi-Product Messages) and 2.21.19 (Single Product Messages).
• Web: The web client that supports these features has been launched.

If the recipient’s app version does not support Multi or Single Product Messages, the business receives a webhook notification throwing an error that describes why the message was unable to be sent.

Product Updates
Businesses may need to update the properties of items in their catalog. Depending on the updated property, this is how we handle any messages mentioning that product:

Shopping Cart Experience
After viewing products, a customer can add them to their shopping cart and send that cart to a business. For the purposes of commerce on WhatsApp, a shopping cart:
Is unique to a person/business chat thread in a specific device: Only one cart is created per chat thread between customer and business and carts do not persist across multiple devices. Once a cart is sent, the customer can open another cart with the business and start the process again.
Has no expiration date: The cart persists in the chat thread until it is sent to the business. Once sent, the cart is cleared. Customers can add up to 99 units of each single catalog item to a shopping cart, but there is no limit on the number of distinct items that can be added to a cart.

Once a cart has been sent, no edits can be made. Customers can send a new cart if they need new items or would like to change their order. Businesses cannot send carts to customers.

Prerequisites to send a product message

1. Create Catalog and add items to catalog :Follow this guide if you have not created any catalog yet, else move to step 2.
2. Assign a partner business to your catalog
   1. Since the WABA are created by the BSP, and Catalog by Merchants / ISV / Businesses - they have to assign BSP as partner business to their catalog, to do so follow the below steps:
      1. Go to your Business Settings and select your business.
      2. Select Data Sources.
      3. Select Catalogs and select the name of your catalog.
      4. Select Assign Partner.
      5. Once you choose to assign a partner at step 4, you will get 2 options for doing so; -> Select Business ID(Refer step 6) OR Generate a link(Refer step 7).
      6. If you select the option "Select Business ID" -
      7. Enter Business ID as 1900820339959633 and under the Full control permission section select Manage catalogue option. Once done, select Next, and then Close.
      8. Once the request is submitted, write to [email protected] with the Subject line: Approve Catalog request: APP NAME and the mail body should have the Catalogue Name and ID. We will approve the partner request and also connect the Catalog to the Live app mentioned in the subject line.
   2. If you select the option "Generate a link" -
      1. Select Get link to share to generate a link.
      2. Select the Manage catalogue task.
      3. You can then send the link to us at [email protected] along with the Subject line: Approve Catalog request: APP NAME. You can use each link only once and it expires in 30 days.

Note: Only 1 Catalogue can be associated with a WABA.

If the WABA is Indian (+91 phone number), business’s e-commerce compliance is necessary: Share the below details with Gupshup on the same email to register your WABA:

Entity/Business details

Customer care details

Grievance officer details

Note: For more info refer here i.e. How to comply with the laws for selling online in India using WhatsApp Business API.

API specification to send product messages
API Endpoint

POST https://api.gupshup.io/sm/api/v1/msg

Headers

Common request payload

Message payload object

Sample single product message

Sample Multi-product message
CURL

Inbound message
The query for a product

Order placed

Inbound message payload object

Facebook Business verification guidance

Completing Facebook business verification ensures us that your entity is authentic. We have compiled targeted guidance to help you get through this process smoothly. Learn more about business verification here.

Before you begin

Your business must need access to certain products and features to begin business verification.
You won't be able to click Start Verification unless your business needs to be verified.
You must be an admin of the Business Manager account to verify your business.
This guidance is complementary to the guidance found here.

Step 1: Go to Business Settings

Step 2: Go to the Security Center

Step 3: In the Business verification section click on Start Verification

Step 4: Enter Business Details

Ensure that your entity's legal name, legal address, and legal website are accurate. Double-check for any typos or other errors: you will not be able to edit this information upon submission.

Step 5: Select Your Business

Select the correct entity from the list that matches your entity (you need to receive a verification code at the phone number listed).

📘

Note: Select ‘None of these match’ if your entity is not displayed (or if you’re unable to receive a verification code at the phone number listed). If you select ‘None of these match,’ skip to the Upload the Official Documents section below for the next steps.

Step 6: If you found a match, then confirm your entity details

Step 7: To receive a verification code, select either the phone number or email.

Email Option: Ensure that the email domain you’ve submitted matches the website domain (provided in step 4).

Matching Example

email: [email protected]

website: www.ministryofhealth.gov.us

NOT Matching Example

email: contactmoh@ gmail.com

website: www.ministryofhealth.gov.us

Phone Option: If you have opted to receive a verification code over the phone, you will need to use the phone number listed. You cannot edit the phone number selection.

Step 8: Once you receive the code, enter it here

If you did NOT find a match for your entity in Step 5, then follow these steps below:

During steps 6 and 7 you will be asked to submit legal documents. Legal documents are supported in the languages listed in this article. Documents submitted in other, unsupported languages must be accompanied by a certified English translation, as explained in the article.

Step 9: Verify your legal entity name

The legal entity name in the submitted document must match the legal entity name you provided in step 4.

Acceptable legal documents for legal entity name:

• Bank statements
• Entity permit from any level of government
• Utility bill, e.g.: water, electricity, phone bill (this should include the phone number where you’ll receive the verification code in step 6 if this is the option you choose)
• Certificate of formation
• Tax registration certificate (or exemption certificate).

Step 10: Verify your legal entity address or phone number

The legal entity address in the submitted document must match the legal entity address you provided in step 4.

Acceptable legal documents for legal entity address:

• Bank statements
• Entity permit from any level of government
• Utility bill
• Certificate of formation
• Tax registration certificate (or exemption certificate).

Step 11: Get a Verification Code

Email Option: Ensure that the email domain you’ve submitted matches the website domain

(provided in step 4).

Phone Option: If you have opted to receive a verification code over the phone, make sure that this is a phone number provisioned by the entity requesting Facebook business verification. It should NOT be a private phone number.

Step 12: Enter Verification Code

Enter the verification code sent to your entity email address or phone number (depending on the option you chose.

This completes the business verification process.

To cancel and resubmit: You can go back to the Security Center and select Cancel.

A brief note on the inconsistencies for mobile numbers and their WhatsApp IDs in Brazil(digit '9') & Mexico(digit '1')

What is a WhatsApp ID

Every number registered on the WhatsApp consumer app(IOS/Android) is associated with a WhatsApp ID. WhatsApp IDs are needed to send messages and user notifications. Usually, the WhatsApp ID of a number is the dialable format of the number itself. For example, the WhatsApp ID of the number "+1-631-555-1002" will be "+16315551002".

Why do Brazil & Mexico phone numbers have differences between the actual dialable number provided by the operator and their WhatsApp IDs?

The Brazilian telephone numbering plan uses a two-digit area code plus eight-digit local phone numbers for landlines and nine digits for mobile lines.

Brazilian mobile phone numbers customarily have nine digits now, but seven digits were usual in the first years, then eight digits became the standard for several years.

With the increasing use of mobile lines, a shortage of available mobile numbers was evident. To overcome this, on December 10, 2010, ANATEL announced the inclusion of a ninth digit (in the format 9NNNN-NNNN) to mobile phone numbers.

The digit '9' was gradually added to the left of all existing mobile numbers in different regions of Brazil, regardless of their former initial digits. So, for example, mobile number +55 (11) 8765-4321 became +55 (11) 98765-4321.

Despite this fact, mobile phones registered outside the 11-19 (São Paulo), 21, 22, 24 (Rio de Janeiro), and 27-28 (Espírito Santo) areas are usually displayed on WhatsApp with the old 8-digit number, since WhatsApp IDs were already present for those numbers before the inclusion of the digit '9'.

Similarly, Mexico has also implemented the following changes in its dialing rules that affect WhatsApp users. When calling a Mexican cell phone from outside Mexico, the additional digit "1" after the country code is no longer required. Essentially, causing inconsistencies between phone numbers registered on WhatsApp and their actual WhatsApp IDs.

Impact on WhatsApp's Business APIs solution

Outbound message
Consider a user with phone number +55 (35) 98765-4321 who has opted-in to receive messages on WhatsApp. Using Gupshup's send message API, the business sends messages to the user. And, with the help of inbound events, they determine that the message has failed to deliver, with "Number does not exist on WhatsApp" as the reason. However, the actual reason for this is because the WhatsApp ID of that number is +55 (35) 8765-4321, meaning without the digit '9'. It is unavoidable as the events are asynchronous.

Inbound message
Now, let us say the user initiates the conversation. From the inbound event, the business can determine the WhatsApp ID of the user. Using this, they can opt-in to that number as well and continue the conversation with the user.

Go-Live process
The Go-Live process for an app is where a business submits their Phone Number, Display Name, and Facebook Business Manager ID for registering a WhatsApp Business API.
Now, consider that a business has submitted the number +55 (11) 98765-4321. However, while registering the number, WhatsApp will consider the WhatsApp ID of the number instead of the number that the business submits. Since the WhatsApp ID may or may not be the same as the number, i.e. with or without the digit '9', they must first verify which number has eventually registered for their WhatsApp Business API before sharing it with their users/customers.

Solution

As a best practice, we highly recommend that businesses track messages based on message IDs. Gupshup and WhatsApp IDs are provided for every outbound and inbound message, respectively.

What does Gupshup's WhatsApp self-serve portal offer? How can I use Gupshup for my business?

Gupshup, being one of the trusted partners of WhatsApp, has created a self-serve portal that enables medium and large enterprises to use WhatsApp Business APIs for their respective businesses, through which they can communicate with their customers vice-versa.

What kind of tools does Gupshup offer? What is the difference?

Gupshup provides two kinds of tools for WhatsApp business API messaging - Customer Support and Access API; here are the differences -

1. Customer Support

The Customer support tool is a user interface used by businesses to answer customer support queries seamlessly over WhatsApp with the help of multiple support agents.

Capabilities provided by Gupshup customer support tool dashboard -

• Enable support team to respond instantly to customer queries
• Receive and Share rich media like documents, images, audio, and video with customers
• You can create pre-trained responses to frequently asked customer queries to help in quicker resolution
• Keep customers engaged with automated responses for Away or BRB modes
• Set a display name, a display picture, and greeting messages customized as per your business needs
• Easily switch from automated responses to live chat conversation
• Support for web as well as mobile

2. Access API

You can use an Access API app to send transactional notifications and receive messages from customers by integrating it with your service or application.

Capabilities provided by Gupshup Access API-

• Flexible REST API that you can integrate with your CRM or Customer Support platform or existing chatbot application
• Send messages to customers using REST API
• It supports rich media like documents, images, audio, and video in response to user queries, as a notification or a session message.
• Upload business-managed opt-ins
• Support to send your custom template notifications to customers who have opted in.
• Receive messages and events sent by customers and WhatsApp via a webhook/callback URL.
  Receive rich media like documents, images, audio, and video from customers.
• Freedom to design your application as per your business requirement

What is $5 free wallet credit for?

Once you become a Gupshup user we credit $5 USD in your account's wallet for testing. If you need more credits, you can recharge and add balance into your WhatsApp wallet.

Once you create an app on our platform, it is initially in the sandbox environment. An app stays in a sandbox environment unless you register your WhatsApp Business API number using the traditional Go-Live or Facebook's embed process.

An app of sandbox environment allows you to test WhatsApp Business APIs, Gupshup features, and other end-user behaviors before you determine to Go-Live. Gupshup also provides free credits worth $5 for testing purposes.

Please note that a sandbox Access API app is limited and only supports sending media messages given here.

What is Gupshup's pricing model? What is Gupshup fee and WhatsApp fee in pricing?

The pricing model is: Pay as you go and the per-message deduction will be made from your wallet.

As shown on the pricing page: the WhatsApp fee is a per-message country-specific fee based on the destination number. WhatsApp only charges for Template messages, and not session messages. Gupshup fee, on the other hand, is a per-message fee applicable for both session and template messages, including the setup & maintenance cost for the service provided.

For example: (if you send messages to India) :

1. For 200 session messages, the applicable deduction from wallet will be :

(gupshup fee + whatsapp fee) * message count

i.e (0.0010 + 0.0000) * 200 = $0.20

2. For 200 template messages, the applicable deduction from wallet will be :

(gupshup fee + whatsapp fee) * message count:

i.e (0.0010 + 0.0042) * 200 = $1.04

The above calculation doesn't include an additional fee which is the media fee (for outgoing media above 64KB). This is applicable for outbound messages only. Let take an example of this:

1. If you are sending 200 session messages with a media file of size in between size larger than 64KB, up to 5MB, the applicable deduction from the wallet will be :
   (Gupshup fee + WhatsApp fee + additional fee) message count
   i.e (0.0010 + 0.0000 + 0.0010) 200 = $0.40
2. If you are sending 200 template messages with a media file of size in between size larger than 64KB, up to 5MB, the applicable deduction from the wallet will be :
   (Gupshup fee + WhatsApp fee + additional fee) message count
   i.e (0.0010 + 0.0042+ 0.0010) 200 = $1.24

Please note: WhatsApp is working to re-align its business model to support the continued growth of conversations on its business APIs. This is why, starting February 1, 2021, they have started testing a new pricing model in Mexico that charges per conversation rather than the current per message model.

How does Proxy work?

The proxy mechanism lets you test WhatsApp Business APIs and end-user behaviors using Gupshup's WhatsApp Business API number(+917834811114). You can use the proxy mechanism when your Access API app is still in the sandbox environment.

To invoke the proxy for your app, you will need to send the WhatsApp message (proxy app_name) to (+917834811114). The rest of the behavior remains the same for the end-user even when you Go-Live with your app.

What use cases are allowed for WhatsApp business API? Can I send promotional messages?

You can refer to WhatsApp's business and commerce policies to determine whether your use case is allowed or not for WhatsApp Business API.

WhatsApp now allows promotional or non-transactional template messages. Regardless, please ensure that you maintain the quality of your template messages as WhatsApp manages your WhatsApp Business APIs quality rating and capacity limits.