Index

Ação necessária: nomes de usuário do WhatsApp e BSUIDs – o que você precisa saber

Raquel Atualizado por Raquel

O WhatsApp está implementando uma grande mudança em 2026: os usuários finais poderão ocultar seu número de telefone ao enviar mensagens para empresas, identificando-se com um nome de usuário (por exemplo, @alice_smith).

Isso significa que o número de telefone do usuário deixará de ser seu identificador principal. A Meta está introduzindo um novo identificador chamado BSUID (Business-Scoped User ID). Nos próximos meses, os BSUIDs começarão a aparecer junto com os números de telefone na API do WhatsApp Business.

Este artigo fornece informações antecipadas sobre: o que está mudando, o que permanece igual e como se preparar para essa mudança, já que isso pode exigir que você faça alterações em seus sistemas.

O lançamento do Meta está em andamento e algumas partes ainda estão sendo habilitadas (docs). Manteremos este artigo atualizado à medida que as coisas evoluem.

O que é um BSUID?

Um BSUID é um identificador que representa exclusivamente um usuário em seu portfólio de negócios. É assim:

US.13491208655302741918
IN.26329079733414951

O formato é um código de país (ISO 3166 alfa-2) seguido por uma string alfanumérica.

Algumas propriedades importantes:

  • Escopo do portfólio: o mesmo usuário final terá um BSUID diferente para cada portfólio de negócios para o qual ele envia mensagens.
  • Estável em alterações de nome de usuário: mesmo se um usuário alterar seu @nomedeusuário, seu BSUID permanecerá o mesmo.
  • Regerado na alteração do número de telefone: se um usuário trocar de número de telefone, seu BSUID será reemitido.
  • Sempre presente: BSUIDs são incluídos em todos os webhooks, independentemente de o usuário ter escolhido usar um nome de usuário ou não.

O que permanece o mesmo

Nada é interrompido para seus contatos existentes. Você ainda terá os números de telefone das pessoas que já enviaram mensagens para você. Cada contato que você tem hoje continuará funcionando exatamente como antes.

Você também continuará recebendo o número de telefone do usuário em webhooks em muitos cenários comuns, mesmo depois que ele adotar um nome de usuário.

O que está mudando

  • Você não terá acesso ao número de telefone de novos usuários que optaram por ocultá-lo.
  • O identificador principal dos usuários será o deles. BSUID, e não o whatsapp_id (seu número de telefone).

No Turn.io, essas mudanças serão implementadas progressivamente:

  • Os contatos terão novos campos
  • Envio de mensagens por BSUID
  • Novas expressões de jornada
  • Mudança de comportamento para @contact.whatsapp_id
  • Importações e exportações de CSV
  • Modelos de autenticação
  • Clientes do BigQuery/data warehouse

Preparação

Ao longo dos anos, todos construíram seus serviços presumindo que o identificador principal de um usuário seria seu número de telefone. Isso significa que, em todo o sistema, você pode depender do número de telefone. Aqui está uma lista completa de itens que você deve revisar e como fazer a transição para o uso de BSUIDs.

1. Alterações na API

1.1 Endpoints de contato — BSUID como identificador

Todos os endpoints de contato agora aceitam um BSUID como parâmetro de caminho contact_id, além de números de telefone.

Antes: somente números de telefone eram aceitos.

GET /v1/contacts/918609840467/profile

Depois: Número de telefone ou BSUID aceito. O formato é detectado automaticamente.

GET /v1/contacts/918609840467/profile          # por telefone


GET /v1/contacts/IN.26329079733414951/profile  # por BSUID

Afetado endpoints:

  • GET /v1/contacts/<contact_id> — obtenha ou crie um contato
  • POST /v1/contacts/<contact_id> — crie um contato por identificador
  • PUT /v1/contacts/<contact_id> — atualize um contato
  • GET /v1/contacts/<contact_id>/profile — obter perfil de contato
  • PUT /v1/contacts/<contact_id>/profile — substituir perfil de contato
  • PATCH /v1/contacts/<contact_id>/profile — atualização parcial do perfil de contato
  • DELETE /v1/contacts/<contact_id>/profile — excluir perfil de contato
  • GET /v1/contacts/<contact_id>/messages — listar mensagens para um contato
  • GET/POST/PUT/DELETE /v1/contacts/<contact_id>/claim — gerenciar atribuição de bate-papo

1.2 Resposta do contato — Novos campos

GET /v1/contacts/<contact_id> agora inclui o BSUID e o nome de usuário do contato quando conhecido:

{

  "id": "uuid",

  "type": "DEFAULT",

  "is_fallback_active": falso,

  "failure_count": 0,

  "bsuid": "IN.26329079733414951",

  "nome de usuário": "alice_smith"

}

Campo

Tipo

Descrição

bsuid

string, omitido quando não set

O ID de usuário com escopo comercial do usuário

nome de usuário

string, omitido quando não definido

O nome de usuário do WhatsApp do usuário (por exemplo, alice_smith)

1.3 Webhooks que você recebe do Turn

Se você consumir os webhooks do Turn, os campos BSUID agora aparecerão nas cargas e os campos baseados em telefone poderão estar ausentes para usuários que ocultaram seu número de telefone. Qualquer código que assume que de, para ou wa_id está sempre presente deve lidar com a falta deles.

1.3.1  Mensagem de entrada webhooks

Campo

Alterar

de

Omitido quando o telefone do remetente está indisponível (era sempre presente)

from_bsuid

Novo — o BSUID do remetente. Não presente em mensagens recebidas antes do suporte ao BSUID

entrada de contatos[]

Espelha o formato do Meta: wa_id (telefone) quando disponível, user_id (BSUID) quando disponível, ou ambos

Exemplo de fragmento de mensagem para um somente BSUID usuário:

{

  "id": "wamid.xxx",

  "type": "text",

  "from_bsuid": "IN.26329079733414951",

  "texto": { "corpo": "Olá" }

}

com a entrada de contato: { "perfil": { "nome": "Alice" }, "id_usuário": "IN.26329079733414951" }

1.3.2  Webhooks de mensagens de saída

Campo

Alterar

para

nulo quando o destinatário não tem número de telefone (sempre foi o telefone)

destinatário

Novo - o BSUID do destinatário, incluído sempre que a conversa tiver um (pode aparecer ao lado de)

1.4 Envio de mensagens — novo campo destinatário

POST /v1/messages agora aceita um campo de destinatário para envio baseado em BSUID, como uma alternativa ao campo para.

Antes:

{

  "to": "918609840467",

  "type": "texto",

  "texto": { "corpo": "Olá" }

}

Depois — enviar por BSUID:

{

  "destinatário": "IN.26329079733414951",

  "tipo": "texto",

  "texto": { "corpo": "Olá" }

}

Depois — enviar com ambos (o telefone tem precedência):

{

  "para": "918609840467",

  "destinatário": "IN.26329079733414951",

  "tipo": "texto",

  "texto": { "corpo": "Olá" 
  • destinatário aceita BSUIDs apenas
    • 1.5 Exportação CSV de contato — Novas colunas
    As exportações CSV agora incluem duas colunas adicionais ao lado de whatsapp_phone_number:
    Nova coluna
    Descrição
    Exemplo
    bsuid
    Usuário com escopo comercial ID
    IN.26329079733414951
    nome de usuário
    nome de usuário do WhatsApp
    alice_smith
    1.6 Bloquear/Desbloquear — Suporte BSUID
    Bloquear e desbloquear contatos agora funciona com identificadores BSUID. A API detecta automaticamente se o identificador é um número de telefone ou BSUID. Ao enviar a solicitação de bloqueio para Meta, o sistema usa user_id (BSUID) quando o telefone não está disponível.
    1.7 Chamadas de saída — novo campo destinatário
    As chamadas de saída iniciadas pela empresa agora incluem um campo destinatário para início de chamada baseado em BSUID, juntamente com o campo para existente.
    2. Alterações na jornada
    2.1 Novos campos de contato
    Duas novas expressões estão disponíveis nas jornadas:
    Expressão
    Tipo
    Descrição
    Exemplo valor
    @contact.bsuid
    string
    O valor do usuário BSUID
    IN.26329079733414951
    @contact.username
    string
    O WhatsApp do usuário nome de usuário
    @alice_smith
    Eles estão disponíveis no construtor Journey no menu Variáveis de contato.
    2.2 Novo bate-papo Campo
    Expressão
    Tipo
    Descrição
    @chat.owner_bsuid
    string
    O BSUID do chat proprietário
    Disponível no menu de variáveis do bate-papo.
    2.3 Mudança de comportamento para @contact.whatsapp_id
    @contact.whatsapp_id permanece apenas por telefone. Para contatos somente BSUID (usuários que ocultaram seu número de telefone), esta expressão retorna nulo.
    Ação necessária: 
    As jornadas que dependem de @contact.whatsapp_id devem ser atualizadas para usar @contact.bsuid quando apropriado, ou adicionar verificações de nulo. Veja abaixo como.
    Aqui está um exemplo de expressão para verificar se o whatsapp_id de alguém é nulo:
    is_nil_or_empty(@contact.whatsapp_id)
    Aqui está um exemplo em uso em um cartão de código:
    card CodeBlock_1 do
     user_id = if(is_nil_or_empty(@contact.whatsapp_id), @contact.bsuid, @contact.whatsapp_id)
     text("ID do usuário: @user_id")
    end
    3. Solicitar o número de telefone do usuário (em breve)
    Para coletar números de telefone de usuários com apenas nome de usuário, o Meta fornece um novo tipo de mensagem chamado Solicitar contato Informações.
    Você pode solicitar o número de telefone do usuário em vários locais do produto:
    Local
    Como modelo
    Da caixa de entrada
    Das jornadas
    O resultado é sempre o mesmo: você obtém acesso ao número de telefone do usuário.
    4. Modelos de autenticação (OTP)
    Os modelos de autenticação não podem usar BSUIDs. A tentativa de enviar um modelo de autenticação para um contato somente BSUID retorna o código de erro Meta 131062. É necessário um número de telefone.
    Isso se aplica a todos os tipos de modelo de autenticação:
    • Senhas de uso único (OTP)
    • Autenticação com um toque
    • Autenticação com toque zero
    • Autenticação de código de cópia
    Esses erros aparecerão nos registros de jornada ou na caixa de entrada ao tentar enviar um modelo de autenticação para um contato sem um número de telefone:
    Para enviar modelos de autenticação, você precisa primeiro coletar o número de telefone do usuário usando a mensagem Solicitar informações de contato mencionada anteriormente neste artigo.
    5. Alterações no BigQuery/Data Warehouse
    5.1 Novas colunas
    As novas colunas a seguir são exportadas automaticamente para o BigQuery:
    Tabela
    Novo Coluna
    Tipo
    Descrição
    contatos
    bsuid
    STRING
    Usuário com escopo comercial ID
    contatos
    nome de usuário
    STRING
    WhatsApp nome de usuário
    mensagens
    from_bsuid
    STRING
    BSUID do remetente da mensagem — somente mensagens de entrada, NULL em mensagens de saída
    mensagens
    urn_bsuid
    STRING
    BSUID do cliente em ambos os lados da mensagem (remetente para entrada, destinatário para saída) — a contraparte BSUID do urn_phone_number existente; use-o para consultas de junção
    bate-papos
    owner_bsuid
    STRING
    BSUID do proprietário da conversa
    5.2 Campos de telefone anuláveis
    Somente para BSUID contatos (usuários que ocultaram seu número de telefone), as colunas baseadas em telefone serão NULL:
    Column
    Comportamento para contatos somente BSUID
    contacts.urn
    NULL (era +telefone)
    messages.from_addr
    NULL (era o número de telefone)
    messages.urn_phone_number
    NULL para ambas as direções (entrada: nenhum from_addr para derivar; saída: nenhum destinatário de telefone para derivar from)
    chats.owner
    NULL (era número de telefone)
    5.3 Impacto em consultas existentes
    Consultas que JOIN em campos baseados em telefone não retornarão silenciosamente nenhuma linha para contatos somente BSUID. Você também deve atualizar JOINs para usar os campos BSUID.
    (Observação: urn_phone_number e urn_bsuid são colunas desnormalizadas na tabela de mensagens que normalizam os identificadores do cliente nas direções. urn_phone_number: from_addr para entrada, addressees[0] para saída — NULL quando o telefone não está disponível. urn_bsuid: BSUID do remetente para entrada, o BSUID da conversa para saída.)
    Antes (apenas telefone JOIN — pausas para contatos somente BSUID):
    -- Buscar todas as mensagens de um contato (apenas contas para número de telefone)

    SELECT m.*, c.details

    FROM mensagens m

    JOIN contatos c ON m.urn_phone_number = c.urn
    Depois (telefone + BSUID JOIN):
    -- Buscar todas as mensagens de um contato (contas para número de telefone e bsuid)

    SELECT m.*, COALESCE(cp.details, cb.details) Detalhes AS

    FROM mensagens m

    -- As mensagens podem ser vinculadas ao contato por qualquer um telefone OU bsuid OU ambos

    LEFT JOIN contatos cp ON m.urn_phone_number = cp.urn

    LEFT JOIN contatos cb ON m.urn_bsuid = cb.bsuid

    -- Opcional: mantenha apenas mensagens que correspondam a um contato 

    ONDE cp.urn NÃO É NULO OU cb.bsuid NÃO É NULL
    Novos recursos de filtragem:
    -- Encontre todos os contatos somente BSUID (sem número de telefone)

    ONDE contatos.bsuid NÃO É NULO E contatos.urn É NULO

    -- Filtrar por BSUID específico

    WHERE contatos.bsuid = 'US.13491208655302741918'

    -- Todas as mensagens trocadas com um usuário BSUID específico (ambas as direções) 

    WHERE messages.urn_bsuid = 'US.13491208655302741918'

    -- Filtrar por username

    WHERE contact.username = 'alice_smith'
    Sugerimos que você comece o mais rápido possível a fazer com que seus sistemas utilizem o novo BSUID e sejam resilientes para usuários que optaram por ocultar seus números de telefone.
    Enquanto isso, se você tiver dúvidas, entre em contato conosco. Estamos aqui para ajudar.

    Esse artigo foi útil?

    15 de julho de 2026: nova caixa de resposta

    Contato