Specifics of sending messages to numbers of different countries
Handling WhatsApp Number Format Discrepancies and Country-Specific Rules
Quick Summary: How to Avoid Message Delivery Issues
If you're experiencing issues where messages aren’t delivered or you notice that a customer’s number appears differently in webhook logs than what you see in your CRM or phone contacts — you're likely facing a number formatting mismatch.
WhatsApp requires phone numbers to follow country-specific formatting rules, and using the "visually correct" number (what the user gave you, or what's stored in your system) is often not sufficient.
To ensure proper delivery and tracking of messages:
✅ Always use the WhatsApp Chat ID (e.g. [email protected]
) returned in the webhook or retrieved using the checkPhones
method.
Here are the most common formatting rules to be aware of:
Brazil
For area codes 11–19, 21, 22, 24, 27, 28, add a 9
after the area code; otherwise, remove it
+55 92 98172 3241
→ +55 92 8172 3241
If you're sending messages based on the phone number you received from the client (manually or from CRM) without adjusting formatting, there's a high chance the message won't be delivered or matched correctly.
Use this table and checkPhones
to verify and normalize numbers before sending.
Where the Problem Happens
This issue usually becomes visible in one of the following situations:
You know the customer’s phone number (e.g. collected manually or stored in a CRM), but your message is never delivered.
You receive incoming messages in the webhook, but the sender's number looks slightly different — for example, it may be missing a digit (such as a leading
9
), or include one that doesn’t match your records.
In all of these cases, the underlying cause is the same: you're using a number in the wrong format — one that looks correct to a human, but isn't recognized by WhatsApp internally.
📍 This problem is most commonly seen in Latin American countries like Mexico, Argentina, and Brazil, where mobile numbering rules are more complex and non-standardized.
Country-Specific Formatting Rules
Some countries require additional adjustments to mobile numbers before they can be used with WhatsApp. These rules are not obvious and can lead to delivery failures if not handled properly. Below are the most commonly affected regions:
Mexico
Common issue: Messages fail to deliver if the number is missing a required 1
after the country code. This applies to all Mexican mobile numbers (including Nextel).
Rule:
Insert a 1
after the country code 52
and remove any prefix like 11
. This ensures the number is 13 digits long.
Incorrect format (as seen in CRM):
+52 56 3969 1841
Correct Chat ID format for sending messages:
[email protected]
Argentina
Common issue: If the number includes a 15
prefix or lacks the required 9
, WhatsApp won’t recognize it.
Rule:
Insert a 9
after the country code 54
and remove any 15
from the start of the local number. The result should also be a 13-digit number.
Incorrect format (as given by users):
+54 11 5874 9895
or +54 15 5874 9895
Correct Chat ID format for sending messages:
[email protected]
Brazil
Common issue: WhatsApp may ignore messages if the 9
digit is either wrongly included or omitted. Whether to keep or remove it depends on the area code.
Rule:
For area codes 11–19, 21, 22, 24, 27, and 28, a 9
must be added after the area code.
For all other area codes, the 9
must be removed if it’s present.
Incorrect format (based on phone contact):
+55 92 98172 3241
(area code 92 does not require the 9)
Correct Chat ID format for sending messages:
[email protected]
🔎 Tip: If you're unsure how to format a number, use the
checkPhones
method to validate and retrieve the correct WhatsApp ID before sending.
How to Solve the Issue
To avoid delivery issues and mismatched numbers in your system, it's essential to rely on WhatsApp's actual internal identifier — the Chat ID
(e.g. [email protected]
).
Here’s how to handle it properly in your integration:
1. Use checkPhones
endpoint to Validate Numbers
checkPhones
endpoint to Validate NumbersBefore sending any message, especially to users in Mexico, Argentina, or Brazil, use the checkPhones
method to retrieve the correct, WhatsApp-validated Chat ID.
This method checks whether a number is registered on WhatsApp and returns the exact identifier you should use when sending messages.
Example:
Request:
curl --request POST \
--url https://gate.whapi.cloud/contacts \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR_TOKEN' \
--header 'content-type: application/json' \
--data '
{
"blocking": "wait",
"force_check": false,
"contacts": [
"5592981723245",
"5592981723243"
]
}
'
Response:
{
"contacts": [
{
"input": "5592981723246",
"status": "valid",
"wa_id": "[email protected]" // Correct Chat ID
},
{
"input": "5592981723243",
"status": "invalid" // This number does not have WhatsApp at all
}
]
}
The format is [email protected] and is the chat identifier. You should now send all messages only to this Chat ID.
2. Use the Chat ID from Incoming Webhooks
When a customer sends you a message, the webhook includes their Chat ID. That ID is already normalized and confirmed by WhatsApp — it’s the most reliable reference for future communication.
Last updated
Was this helpful?