> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whatix.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Números de telefone

> Formato E.164 sem +, o nono dígito e a validação opcional no WhatsApp.

Todo campo `number` da API — em mensagens, contatos e flows — espera o mesmo formato: **E.164 sem o `+`**, ou seja DDI + DDD + número, só dígitos.

```
5534999990000
```

`55` (Brasil) + `34` (DDD) + `999990000` (número com o nono dígito).

## Escreveu → interpretado

| Você escreveu | Recomendado? | Por quê |
| - | - | - |
| `5534999990000` | Sim | DDI + DDD + número, só dígitos — o formato esperado |
| `+55 34 99999-0000` | Sim | O envio remove tudo que não é dígito antes de processar, então isso vira `5534999990000` — mas evite depender disso, envie já normalizado |
| `34999990000` | Não | Sem DDI. **Não é rejeitado** — a API tenta enviar assim mesmo, e o número pode acabar indo pra um destino errado |
| `(34) 99999-0000` | Não | Sem DDI (mesmo problema do anterior) além dos caracteres não-numéricos |

Se depois de remover tudo que não é dígito não sobrar nenhum caractere (`number` vazio, só espaços, ou só símbolos), a API responde `400` com `code: ERR_NUMBER_INVALID`. Mas um número sem DDI passa nessa checagem — o único jeito de garantir o envio certo é sempre mandar o formato completo.

## O nono dígito

Números de celular brasileiros têm 9 dígitos depois do DDD desde a unificação nacional. A API aceita e normaliza variantes com e sem o nono dígito em campos de busca (como `number` em `GET /v1/contacts`), mas ao **enviar** mensagem ou criar contato, use sempre o formato completo com 9 dígitos — é o que garante a entrega correta pelo WhatsApp.

## Validar no WhatsApp antes de salvar

No upsert de contato (`POST /v1/contacts`), o parâmetro opcional `validateNumber` confere se o número existe no WhatsApp antes de gravar:

```bash theme={null}
curl -X POST https://sua-instancia.whatix.cloud/wapi/v1/contacts \
  -H "Authorization: Bearer wtx_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "number": "5534999990000", "name": "Maria", "validateNumber": true }'
```

Se o número não existir no WhatsApp, a resposta é `422` com `code: ERR_NUMBER_NOT_ON_WHATSAPP`.

<Note>`validateNumber` só se aplica a conexões Baileys. Em conexões WABA a checagem não bloqueia o upsert — a Meta não expõe essa validação pela Cloud API.</Note>

<Warning>`validateNumber` faz uma checagem ativa no WhatsApp e pode ser mais lento que um upsert comum. Não use em importações em massa; reserve para fluxos onde você precisa ter certeza antes de prosseguir (ex.: cadastro de um lead único).</Warning>