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.

⚠️ Note: This issue typically affects specific countries with special number formatting rules — namely Mexico, Argentina, and Brazil.

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:

Country	Formatting Rule	Example Input	Required Chat ID Format
Mexico	Insert 1 after country code 52, and remove any 11 prefix	[phone]	[email protected]
Argentina	Insert 9 after 54, and remove 15 from the local number	[phone]	[email protected]
Brazil	For area codes 11–19, 21, 22, 24, 27, 28, add a 9 after the area code; otherwise, remove it	[phone] → [phone]	[email protected]

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): [phone]

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): [phone] or [phone]

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): [phone] (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

Before 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.