NOTE: The mismatch event described below may or may not be delivered to your callback URL because of the deprecation of the check contact API. To manage the actual wa_ids and dialable of phone numbers mismatch cases at your end, we recommend the following -
- Create a new field in the database, called wa_id, it will be empty by default.
- While sending the very first message to the end user, trigger it to the number informed in your database in the phone_number field.
- Submit the message and register the messageId in a temporary variable like {{firstMessage}}.
- Monitor the webhook for receiving the SENT event for the {{firstMessage}}.
- Look at the {{destination}} field in the JSON and save it as the wa_id.
- From now on, trigger the messages with {{wa_id}} on {{destination}}, instead of phone_number.
- Use {{wa_id}} to find the customer and fit the conversation into the correct window.
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:
{
"app": "DemoApp",
"timestamp": 1638607221146,
"version": 2,
"type": "message-event",
"payload": {
"id": "499a3642-5d41-477f-8bdc-58985e9c6996",
"type": "mismatch",
"destination": "5535987654321",
"payload": {
"phone": "553587654321",
"wa_id": "5593587654321"
}
}
}
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:
Comments
0 comments
Please sign in to leave a comment.