๐๏ธ Modelagem do banco
Use BSUID como chave estrangeira em conversas, mensagens, atendimentos. Numero vira coluna opcional.
CREATE TABLE contatos_whatsapp ( business_id UUID NOT NULL, bsuid TEXT NOT NULL, phone_e164 TEXT, -- opcional display_name TEXT, username TEXT, -- @ se conhecido first_seen_at TIMESTAMPTZ, last_seen_at TIMESTAMPTZ, PRIMARY KEY (business_id, bsuid) ); CREATE TABLE mensagens_wa ( id UUID PRIMARY KEY, business_id UUID NOT NULL, bsuid TEXT NOT NULL, message_id TEXT NOT NULL, direction TEXT NOT NULL, -- 'in' | 'out' body JSONB, created_at TIMESTAMPTZ, FOREIGN KEY (business_id, bsuid) REFERENCES contatos_whatsapp(business_id, bsuid), UNIQUE (business_id, message_id) );
๐ Por que PK composta
Mesmo BSUID pode existir em business_ids diferentes (cada empresa tem seu escopo). Sem business_id na chave, joins viram bagunca.
๐ Migrar do wa_id
Estrategia dupla-chave em fases. Sem big bang.
Adicionar coluna bsuid
ALTER TABLE adicionando bsuid NULLABLE. Codigo continua usando wa_id.
Backfill incremental
Cada webhook que chega popula bsuid no registro existente. Em paralelo, batch reprocessa historico.
Leitura preferencial
Codigo procura por bsuid primeiro, cai pra wa_id se NULL.
Deprecar wa_id
Quando bsuid coverage atinge ~99%, wa_id vira coluna informativa.
๐ชช Vincular ao CRM
BSUID por si so e anonimo. Voce precisa de algum ato pra saber QUEM e o cliente.
OTP/Login link
Cliente clica em link no app/web que ja sabe quem ele e. Magic link redireciona pro WA.
Codigo curto
Cliente comeca com "CADASTRO 4f2a" e voce associa BSUID ao usuario que gerou esse codigo.
Dados validados
Pedir CPF/email e cruzar com o CRM. Cuidado com privacidade.
โ ๏ธ Riscos de NAO adotar
Continuar 100% baseado em wa_id e divida tecnica acumulando juros.
๐จ Sintomas que voce vai ver
- Cliente "novo" sempre que muda visibilidade do numero
- Atendentes perdem historico no meio da conversa
- Analytics conta cada visita como cliente diferente
- Marketing manda template duplicado
- Suporte nao consegue achar conversa antiga
๐ ๏ธ Ferramentas e BSPs
Cada Business Solution Provider (Twilio, Zenvia, 360dialog, Gupshup, MessageBird) tem seu cronograma. Cheque release notes.
๐ Pergunte ao seu BSP
- Voce expoe BSUID no webhook?
- Tem campo separado ou junto com wa_id?
- Suporta envio com BSUID como destinatario?
- Como lida com usuarios sem numero exposto?
๐ Roadmap de 90 dias
Plano claro e executavel para sair do wa_id-only.
Dias 1-30
- Modelagem do schema
- Migration adicionando bsuid
- Adapter no webhook handler
- Coverage report
Dias 31-60
- Backfill batch do historico
- Indices e performance
- Leitura preferencial por bsuid
- Dashboards de adocao
Dias 61-90
- Escrita preferencial por bsuid
- Plano de deprecacao do wa_id
- Treinamento de atendentes
- Comunicacao a stakeholders
Pos-90
- Wa_id como coluna info
- Atendimento e CRM 100% por bsuid
- Politica de retencao revisada
- Auditoria LGPD do tratamento
๐ Resumo
Proximo Modulo:
3.2 โ Integracao Cloud API