Conceitos

Broker: Meta ou 360Dialog

Todo número é operado por um dos dois brokers, e o campo broker aparece nos webhooks de mensagem com exatamente estes valores:

`broker`	Quem opera
`meta`	Meta (Cloud API)
`360`	360Dialog

O que muda para você:

Ativação. Número 360 nasce em PENDING e vira ACTIVE quando o canal fica ativo no broker. Número meta já nasce ACTIVE.

O que não muda: a URL para onde entregamos, os payloads e a assinatura são os mesmos nos dois brokers. O formato da mensagem recebida depende da versão de webhook do número (v1 ou v2), não do broker.

Status do número

Campo status do número — começa em PENDING:

Status	Significado
`PENDING`	aguardando o canal ficar ativo no broker (fluxo 360)
`ACTIVE`	operando
`INACTIVE`	fora do ar segundo a saúde reportada pelo broker
`BANNED`	banido pela Meta

BANNED é pegajoso: a sincronização periódica de saúde nunca tira um número desse estado — ele sai apenas por ação explícita.

BSUID — quando o cliente não tem telefone

O WhatsApp passou a permitir nomes de usuário. Quando alguém usa um, o telefone dele pode simplesmente não vir para você. Para que a conversa não quebre, a Meta identifica essa pessoa por um BSUID (Business-Scoped User ID): um identificador com o qual você consegue mandar mensagem para um usuário sem conhecer o número dele.

O formato é o código do país (duas letras, ISO 3166) + ponto + até 128 caracteres alfanuméricos:

BR.1729384756102938

Três propriedades que mudam o seu código:

O BSUID é a identidade estável. O telefone pode faltar; o BSUID, não. Nos webhooks ele chega em user_id (o contato) e from_user_id (quem enviou) — veja webhooks.
Ele é escopado ao portfólio de negócio. O mesmo usuário tem BSUIDs diferentes em empresas diferentes, e um BSUID só funciona com números do portfólio para o qual ele foi emitido.
Você envia para ele como envia para um telefone: é só pôr o BSUID no campo to. Veja enviar para um BSUID.

Guarde o BSUID, não só o telefone

Se a sua aplicação indexa contatos apenas por telefone, ela perde o vínculo quando o número não vem. Guarde o user_id como chave do contato e trate o telefone como um dado que pode estar ausente.

Quando você precisa do telefone mesmo assim (para uma entrega, por exemplo), peça-o ao usuário com a mensagem interativa request_contact_info.

Qualidade e limite

Os dois campos aparecem em GET /phones/info e descrevem como a Meta enxerga o seu número. Quem decide os dois é a Meta; o Bandmaster espelha o que ela informa e guarda cada transição em GET /phones/info/history.

`current_quality_rating`

Qualidade do número segundo a Meta, calculada a partir do que os destinatários fazem com as suas mensagens — bloqueios e denúncias derrubam; conversas normais sustentam. Padrão: GREEN.

Valor	Leitura
`GREEN`	saudável
`YELLOW`	em observação
`RED`	qualidade ruim — a Meta pode restringir o número

`current_limit`

O tier de mensagens: quantas conversas o número pode iniciar por dia (as respostas dentro de uma conversa já aberta não contam). Padrão: TIER_1K.

Valor	Conversas iniciadas por dia
`TIER_50`	50
`TIER_250`	250
`TIER_1K`	1.000
`TIER_10K`	10.000
`TIER_100K`	100.000
`TIER_UNLIMITED`	sem limite

Como o tier cresce

Quem promove e rebaixa é a Meta, olhando dois sinais juntos: a qualidade do número e o volume que ele já sustentou. Na prática: mantenha a qualidade fora do vermelho e use de forma consistente a capacidade do tier atual — a Meta promove quando o número mostra volume com qualidade, e rebaixa quando a qualidade cai. Um número em RED tende a perder tier em vez de ganhar.

O Bandmaster não decide nada disso: quando a Meta muda a qualidade ou o tier, o novo valor aparece em GET /phones/info e a transição (de → para) fica no histórico.

Estes dois campos são informativos aqui

O Bandmaster não usa current_limit nem current_quality_rating para barrar ou afunilar o seu envio: o endpoint de envio aceita e enfileira do mesmo jeito, e não existe 429. Quem aplica o limite de conversas iniciadas é a Meta, do lado dela — estourar o tier aparece para você como falha de envio, não como erro na chamada.

Templates

Categoria

Escolhida na criação e obrigatória:

Categoria	Uso
`MARKETING`	promoções e novidades
`AUTHENTICATION`	códigos de verificação
`UTILITY`	avisos transacionais (pedido, entrega, agendamento)

Status

O template nasce pending e só pode ser usado quando fica approved:

Status	Significado
`pending`	em análise
`approved`	aprovado, pronto para uso
`rejected`	recusado — veja `rejected_reason`
`disabled`	desativado

Quando um template é recusado, rejected_reason diz por quê: ABUSIVE_CONTENT, INVALID_FORMAT, PROMOTIONAL, TAG_CONTENT_MISMATCH, SCAM ou NONE.

Um template é único pela combinação identifier + nome + idioma: o mesmo nome pode existir em vários idiomas.

Versão do webhook de mensagem

O formato da mensagem recebida tem duas versões. Sem configuração explícita, o número usa a v1.

Versão	Formato
v1	objeto plano, sem o número do negócio
v2	envelope `{ version, broker, identifier, is_echo, contact, business_phone, message }`

Os dois formatos estão lado a lado em webhooks. A versão afeta apenas o webhook de mensagem recebida — status e falha de envio têm formato único.

Nesta página