MODULO 3.1

๐Ÿงฉ BSUID na pratica

Como tirar o BSUID do papel โ€” modelagem, migracao, vinculacao com CRM e roadmap de 90 dias.

1

๐Ÿ—‚๏ธ 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.

2

๐Ÿ”„ Migrar do wa_id

Estrategia dupla-chave em fases. Sem big bang.

1

Adicionar coluna bsuid

ALTER TABLE adicionando bsuid NULLABLE. Codigo continua usando wa_id.

2

Backfill incremental

Cada webhook que chega popula bsuid no registro existente. Em paralelo, batch reprocessa historico.

3

Leitura preferencial

Codigo procura por bsuid primeiro, cai pra wa_id se NULL.

4

Deprecar wa_id

Quando bsuid coverage atinge ~99%, wa_id vira coluna informativa.

3

๐Ÿชช 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.

4

โš ๏ธ 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
5

๐Ÿ› ๏ธ 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?
6

๐Ÿ“‹ 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

โœ“
PK composta (business_id, bsuid) e foreign keys consistentes.
โœ“
Migracao em 4 fases โ€” sem big bang.
โœ“
Vinculacao explicita ao CRM โ€” BSUID sozinho e anonimo.
โœ“
90 dias e o prazo razoavel para estar 100% em BSUID.

Proximo Modulo:

3.2 โ€” Integracao Cloud API