Brazil WhatsApp Number Format: E.164 and the Ninth Digit in APIs

Brazil WhatsApp Number Format: E.164 and the Ninth Digit in APIs

For WhatsApp in Brazil, store every number in E.164 with the ninth digit on mobile lines (plus sign, 55, area code and nine digits starting with 9), and keep your own comparison key, because the identifier the API returns may come back without the ninth digit. With one normalization function at the point of entry and one deduplication rule, the same customer stops appearing twice in your CRM, your conversation history and your support queues.

Key takeaways

• E.164 is the international numbering format: plus sign, country code and number, with no spaces, parentheses or hyphens. A Brazilian mobile number becomes +55, a two-digit area code (DDD) and nine digits.
• The same mobile number can arrive with or without the ninth digit, depending on the source: manual typing, a web form, an imported spreadsheet or an API response.
• Normalization should happen at the edge of your system, in deterministic code, before anything is saved or sent. Do not let an AI model decide this.
• Store three separate values: the canonical number, the identifier the API returned, and a comparison key for detecting duplicates.
• Log every normalization and every contact merge, and test with real test numbers before connecting the agent to production.

What does a Brazilian number look like in E.164?

E.164 is the ITU international recommendation for telephone numbering. In practice, it defines a number as a plus sign, the country code and the national number, with a maximum of fifteen digits in total. There are no separators and no dialing zeros.

In Brazil, the country code is 55. After it comes the area code (DDD), always two digits. Then comes the subscriber number: nine digits for a mobile line, starting with 9, or eight digits for a landline, starting with a digit from 2 to 5.

Examples with fictional data:

• Canonical mobile number: +5511987654321
• Same mobile number without the ninth digit: +551187654321
• Landline: +551132654321

The second example is the one that causes trouble. It represents a subscriber that the current format knows with nine digits, but who still circulates with eight in old address books, customer records and, in some cases, identifiers returned by platforms.

Why does the ninth digit break integrations and duplicate contacts?

The problem is not the ninth digit itself. It is the lack of a single rule. A support system built on the WhatsApp API usually receives numbers from several places at once:

• The website form, where customers type however they like: with parentheses, with a leading zero, with or without 55.
• An old spreadsheet or CRM, where many mobile numbers still have eight digits.
• The API webhook, which reports the identifier of whoever wrote in.
• Agent typing, where people copy and paste from wherever they are.

If each source saves what it received, the database ends up with two records for the same person. The agent sees one conversation split across two contacts, the history is lost, and a campaign can go out twice to the same customer. If an AI agent is replying, it also loses context, because the conversation memory is tied to one record and the person reappears under another.

One point needs care: how the identifier returned by the API handles the ninth digit depends on the provider and the account, and it can change. Check your provider's official documentation, and treat anything it does not describe as a hypothesis to verify on your own test number. The design rule that holds in every case is not to assume that the number you sent will match the one that comes back.

Which form should I store as the contact identifier?

We recommend storing three fields, each with a clear job:

• Canonical number: E.164 with the ninth digit for mobile lines. This is what the team sees, exports and uses to match against the CRM.
• API identifier: the exact value the provider returned on the last interaction. Use it to reply if sending to the canonical number does not work with your provider.
• Comparison key: 55, the area code and the last eight digits of the number. It ignores whether the ninth digit is present and is used only to find duplicates.

The comparison key is not a person identifier. It only signals that two records are probably the same mobile line. Within one area code, the last eight digits of a mobile number identify the line, so a collision between different people is unlikely, but the merge should be logged and reversible.

How to normalize step by step

The normalization function should be small, tested and used by every entry point. The sequence below is a starting point. Confirm the current numbering rules with Anatel, Brazil's telecom regulator, before fixing the digit ranges in code.

• Step 1: remove everything that is not a digit, including spaces, parentheses, hyphens and the plus sign. Keep the original text in a separate field for auditing.
• Step 2: if the number came with a plus sign and another country's code, stop. Do not apply Brazilian rules to foreign numbers.
• Step 3: remove leading zeros, which come from the habit of dialing the long-distance prefix. If your database has records with a carrier code, handle that case separately and validate it with real samples.
• Step 4: decide whether the country code is already present by length. With 10 or 11 digits, the 55 is missing. With 12 or 13 digits, it is already there. Do not decide by checking whether the number starts with 55, because area code 55 exists.
• Step 5: validate the area code. It must have two digits and the first cannot be zero.
• Step 6: look at the subscriber number. If it has eight digits and starts with 6 to 9, it is a mobile number in the old format: insert a 9 at the front. If it has eight digits and starts with 2 to 5, it is a landline: flag it as a landline and insert nothing.
• Step 7: build the canonical number as +55, area code and subscriber number.
• Step 8: build the comparison key from 55, the area code and the last eight digits.
• Step 9: if anything does not fit, reject it and send it to human review. Guessing a digit is worse than asking for confirmation.

This logic should be ordinary code with automated tests. A language model can get a digit wrong without warning, and a deterministic function cannot. If your flow runs in an automation tool, concentrate the rule in a single reusable step. The article on n8n with the WhatsApp Cloud API shows where this step usually sits in a support flow.

How to avoid duplicate contacts in the CRM and in support

Normalizing at entry solves new cases. For the existing database and for edge cases, use a simple decision guide whenever the comparison key finds an existing record:

• If the canonical number is identical, it is the same contact. Update the record and do not create another.
• If the comparison key matches but the canonical number differs only by the ninth digit, treat it as the same contact, update the canonical number to the nine-digit version and keep the old value as an alias.
• If the key matches but the name is very different, do not merge automatically. Send it to human review, because it may be a reassigned number or a data entry error.
• If the area code is different, they are different contacts, even if the last eight digits coincide.
• If the contact is already flagged as not permitted to receive outbound messages, preserve that flag in the merge. Losing that record because of a duplicate is a real risk. The article on WhatsApp opt-in covers how to collect and store that permission.

For the old database, run normalization in dry-run mode first. Generate a report of candidate merge pairs, have someone from operations review a sample, and only then apply the changes. Keep a log of each merge with the source record, the target record and the date, so you can undo it if needed.

Another source of duplication, separate from numbering, is the webhook itself. Messaging platforms can resend the same event when they do not receive an acknowledgment. For that reason, in addition to the number, use the message identifier as an idempotency key. Payment APIs document this pattern of repeated delivery and safe processing well (idempotent requests and webhook retries), and it applies here even though it is not specific to WhatsApp. To handle failures and resends in your flow, see also error handling and retries in n8n.

Illustrative scenario: the same customer in two contacts

Illustrative scenario: a building materials store receives quote requests through its website and serves customers on WhatsApp. A customer named Marina filled in the form months ago with her mobile number in eight digits, and that record stayed in the CRM. Today she writes in on WhatsApp, and the system receives her identifier without the ninth digit from one source and with it from another.

Without normalization, the agent opens two contacts named Marina. One holds the quote, the other holds today's conversation. The AI agent, with no access to the quote, asks again what she needs.

With the rule above, the form would have saved the canonical nine-digit number and the comparison key from the start. When the message arrives, the system calculates the key, finds the existing contact, attaches the conversation to it and stores the identifier returned by the API in its own field. The agent sees a single history, and the AI agent looks up the correct quote.

How to test and monitor normalization

Treat the normalization function like any critical business rule: with a table of test cases. Include at least numbers with and without 55, with a leading zero, with and without the ninth digit, landlines, area code 55, numbers with a plus sign from other countries, and junk input. The simulated environment approach in the article on testing AI agents with mocks helps you validate the flow without sending real messages to customers.

Then watch the system run. For each message, record the original value, the canonical number, the key and the decision taken (new contact, same contact, sent to review). These logs let you investigate an error later and measure how many cases fall into manual review. The logic of logs, metrics and traces from standard observability practice supports this kind of monitoring.

There is also a privacy dimension. A phone number is personal data under LGPD, Brazil's data protection law. In logs, mask part of the digits when the log does not need the full number, limit who can access the merge table, and define how long you keep the original text that was typed in. Brazil's data protection authority (ANPD) publishes official guidance on the topic.

How to apply this with a method: map, limit, pilot, hand over

A simple working method fits this problem well. In the map step, list every source of numbers (website, spreadsheets, CRM, API, typing) and count how many contacts currently have possible duplicates, without changing anything. In the limit step, centralize the rule in a single point in the code, forbid the AI agent from altering numbers, and require human review for ambiguous merges. In the pilot step, turn on normalization in one real flow, with logs and an agreed success criterion, for example the number of new duplicates per week. In the hand-over step, deliver the documentation of the rules, the test table and the procedure for undoing merges, and decide with the team whether to expand, adjust or stop.

If your operation is just starting to connect AI to WhatsApp, also read the guide on how to integrate AI into your company's WhatsApp, because the quality of your contact records is a prerequisite for any agent to work well.

Frequently asked questions

Should a WhatsApp number in Brazil always have the ninth digit?

For mobile lines, the canonical form we recommend storing is with the ninth digit, in E.164 format. That does not mean every API returns the identifier that way, so also keep the value returned by the provider and use the comparison key to link the two.

Can I ask the AI agent to fix the numbers?

We do not recommend it. Normalization is a task with clear rules and should be done by deterministic, tested code. At most, the agent can ask the customer for confirmation when the rule rejects a number, and the answer should still pass through the same function.

How do I clean an old database that already has duplicates?

Run normalization in dry-run mode, generate a report of pairs with the same comparison key, review a sample with the team, and only then apply the merges. Keep a log of each merge and preserve contact permission flags, so you can undo changes and avoid losing opt-out records.

Does the same rule work for numbers from other countries?

No. The ninth digit and area code rules apply to Brazilian numbering. For numbers that arrive with a plus sign and another country's code, validate only the general E.164 format and do not apply the Brazilian adjustment, unless you have a specific rule for that country.

Sources

• ITU: Recomendação E.164, plano internacional de numeração
• Stripe: requisições idempotentes (exemplo de padrão de idempotência)
• Stripe: entrega e verificação de webhooks (exemplo de padrão)
• ANPD: Autoridade Nacional de Proteção de Dados