BSUIDs e Usernames do WhatsApp: guia completo para integrações

{
  "contacts": [{
    "wa_id": "5511999887766",
    "profile": { "name": "João" }
  }],
  "messages": [{
    "from": "5511999887766",
    "type": "text",
    "text": { "body": "Olá" }
    // Sem user_id, from_user_id ou username
  }]
}

{
  "contacts": [{
    "user_id": "BR.99887766554433221100",    // ← NOVO: BSUID
    "wa_id": "5511999887766",                // presente (interação < 30d)
    "profile": {
      "name": "João",
      "username": "joao.silva"               // ← NOVO: se adotou username
    }
  }],
  "messages": [{
    "from": "5511999887766",                 // presente
    "from_user_id": "BR.99887766554433221100", // ← NOVO: BSUID
    "type": "text",
    "text": { "body": "Olá" }
  }]
}

{
  "contacts": [{
    "user_id": "BR.99887766554433221100",    // ← BSUID: sempre presente
    // wa_id: OMITIDO (username + sem interação 30d)
    "profile": {
      "name": "João",
      "username": "joao.silva"
    }
  }],
  "messages": [{
    // from: OMITIDO
    "from_user_id": "BR.99887766554433221100", // ← único identificador
    "type": "text",
    "text": { "body": "Olá" }
  }]
}

function buildSendPayload(phone, bsuid) {
  if (phone) {
    return { to: phone };            // Sempre funciona
  } else if (bsuid && isAfterMay2026()) {
    return { recipient: bsuid };     // Só a partir de maio/2026
  } else {
    logWarning("Sem identificador válido para envio");
    return null;
  }
}

{
  "field": "user_id_update",
  "value": {
    "contacts": [{
      "profile": { "name": "João" },
      "wa_id": "5511999887766",        // se disponível
      "user_id": "BR.NOVO_BSUID..."    // BSUID atual
    }],
    "user_id_update": [{
      "wa_id": "5511999887766",
      "detail": "User id for João has been updated.",
      "user_id": {
        "previous": "BR.ANTIGO_BSUID...",
        "current": "BR.NOVO_BSUID..."
      },
      "timestamp": "1711756800"
    }]
  }
}

{
  "type": "buttons",
  "buttons": [{ "type": "REQUEST_CONTACT_INFO" }]
}
// Botão não é customizável e não requer parâmetros no envio

-- 1. Colunas BSUID e username
ALTER TABLE contacts ADD COLUMN IF NOT EXISTS bsuid TEXT;
ALTER TABLE contacts ADD COLUMN IF NOT EXISTS username TEXT;
ALTER TABLE chats ADD COLUMN IF NOT EXISTS bsuid TEXT;

-- 2. phone_id aceita NULL (CRÍTICO)
ALTER TABLE contacts ALTER COLUMN phone_id DROP NOT NULL;

-- 3. Tabela de mapeamento (auditoria)
CREATE TABLE IF NOT EXISTS bsuid_phone_mappings (
  id BIGSERIAL PRIMARY KEY,
  bsuid TEXT NOT NULL,
  phone_id TEXT,
  instance_id UUID NOT NULL,
  first_seen TIMESTAMPTZ DEFAULT NOW(),
  last_seen TIMESTAMPTZ DEFAULT NOW()
);

-- 4. Indexes únicos
CREATE UNIQUE INDEX IF NOT EXISTS idx_contacts_bsuid_instance
  ON contacts (bsuid, instance_id) WHERE bsuid IS NOT NULL;
CREATE UNIQUE INDEX IF NOT EXISTS idx_chats_bsuid_instance
  ON chats (bsuid, instance_id) WHERE bsuid IS NOT NULL;

// Webhook de MENSAGEM (payload.messages existe)
function parseIncomingMessage(payload) {
  const contact = payload.contacts[0];
  const message = payload.messages[0];

  // Campos NOVOS (sempre presentes a partir de 31/março)
  const bsuid    = contact.user_id;           // ← BSUID: sempre
  const username = contact.profile?.username;  // ← se adotou
  const fromBsuid = message.from_user_id;     // ← BSUID: sempre

  // Campos que PODEM ser omitidos (username + sem interação 30d)
  const phone = contact.wa_id || null;         // ← pode ser undefined!
  const from  = message.from || null;          // ← pode ser undefined!

  return { bsuid, username, phone, from, fromBsuid };
}

// Webhook de STATUS (payload.statuses existe — nunca junto com messages)
function parseStatus(payload) {
  // contacts[] é NOVO em status webhooks, omitido em status "failed"
  const contact = payload.contacts?.[0];
  const status  = payload.statuses[0];

  const bsuid = contact?.user_id || null;
  const recipientBsuid = status.recipient_user_id;  // ← BSUID destino

  return { bsuid, recipientBsuid };
}

function resolveContact(phone, bsuid, username) {
  let contact = null;

  // 1. Tentar por phone (backward compatible)
  if (phone) {
    contact = findByPhone(phone);
    if (contact && bsuid && !contact.bsuid) {
      contact.bsuid = bsuid;          // Backfill BSUID
      contact.username = username;
      save(contact);
      logMapping(bsuid, phone);        // Auditoria
    }
  }

  // 2. Fallback: tentar por BSUID
  if (!contact && bsuid) {
    contact = findByBsuid(bsuid);
    if (contact && phone && !contact.phone) {
      contact.phone = phone;           // Backfill phone
      save(contact);
      logMapping(bsuid, phone);
    }
  }

  // 3. Nenhum encontrado: criar novo
  if (!contact) {
    contact = createContact({ phone, bsuid, username });
    if (phone && bsuid) logMapping(bsuid, phone);
  }

  return contact;
}

function handleUserIdUpdate(payload) {
  for (const update of payload.user_id_update) {
    const oldBsuid = update.user_id.previous;
    const newBsuid = update.user_id.current;
    const phone    = update.wa_id || null;

    const contact = findByBsuid(oldBsuid);
    if (contact) {
      contact.bsuid = newBsuid;
      save(contact);
      logMapping(newBsuid, phone);
    }
  }
}