Sign inGet Started
Começar
Guias
Referência de API
SDKs
CLI
Base de conhecimento
Changelog

Recebendo mensagens de grupo WhatsApp

Tudo que um participante escreve em um grupo chega da mesma forma que qualquer outra mensagem WhatsApp de entrada: o mesmo evento whatsapp.received, os mesmos braços de conteúdo, a mesma busca de mídia. Duas coisas são específicas de um grupo. A mensagem identifica tanto o participante que a escreveu quanto o grupo pelo qual ela chegou, e a sua resposta vai para o grupo em vez de para aquela pessoa.

Recebendo mensagens WhatsApp cobre as partes que não são específicas de grupo: cada braço de conteúdo, busca de mídia de entrada e respostas citadas.

O que uma mensagem de grupo carrega

Uma mensagem de grupo de entrada é lida de volta com dois endereços em vez de um:

  • from é o participante que a escreveu, nunca o grupo. Carrega o bsuid dele (ID de usuário com escopo de negócio), o phone_number quando a sua empresa o conhece, e o username e display_name quando ele publica um perfil. Um participante que não compartilhou o número com você é identificado apenas pelo bsuid, o que é suficiente para endereçá-lo.
  • to carrega o número da sua empresa e o grupo. phone_number é o número que recebeu a mensagem, e group_id é o grupo pelo qual ela chegou.

group_id aparece em to e em nenhum outro lugar, então a presença dele ali é o que distingue uma mensagem de grupo de uma individual, em qualquer direção. Uma mensagem de grupo não carrega contadores: recipient_count, delivered_count e read_count reportam um fan-out de saída, e uma mensagem de entrada não tem nenhum.

Para ler a thread de um grupo, nas duas direções ao mesmo tempo, filtre a lista de mensagens por group_id como Enviando para um grupo WhatsApp mostra.

Respondendo ao grupo

Um participante que escreve no grupo abre uma única janela de atendimento ao cliente de 24 horas para o grupo inteiro, não uma por pessoa. Enquanto ela está aberta, conteúdo livre chega ao grupo; quando ela expira, um template é necessário. Endereçe a resposta ao grupo, com o ID do grupo em to e sem from. Veja Enviando para um grupo WhatsApp.

Escrever para esse participante de forma privada é uma conversa separada com sua própria janela, e a mensagem de grupo não a abre. Uma mensagem livre endereçada ao número de telefone ou ao bsuid dele é recusada com um 422 E15044, a menos que ele tenha enviado uma mensagem separada para a sua empresa nas últimas 24 horas. Um template o alcança de qualquer forma.

Confirmando e reagindo

As duas confirmações funcionam em uma mensagem de grupo e usam as mesmas chamadas que em qualquer outra mensagem de entrada:

  • Marcar como lida com o ID da própria mensagem. Nada na chamada muda para um grupo.
  • Reagir a ela com um emoji. A reação vai para o grupo, então todos os participantes a veem. Um grupo que não está ativo recusa a alteração com um 409 E15047, que é a única recusa que uma reação em mensagem de grupo tem e uma reação individual não tem.

O webhook

whatsapp.received carrega uma mensagem de grupo no mesmo envelope que qualquer outra, com o grupo em to:

Exemplo de código
{
  "type": "whatsapp.received",
  "timestamp": "2026-09-15T14:05:41.204Z",
  "data": {
    "whatsapp_id": "wam_01kya1b3xdq7fe8m2v5t9rncgs",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+15550002222", "bsuid": "US.AbC1", "display_name": "Dana Reyes" },
    "to": { "phone_number": "+15550001111", "group_id": "wag_01krdgeqcxet5s7t44vh8rt9mg" },
    "text": { "body": "Got it, thanks." },
    "tags": null,
    "metadata": null
  }
}

Leia data.to.group_id para rotear a mensagem para a thread do grupo, e data.from para atribuí-la a um participante. Um assinante que indexa conversas apenas por from coloca cada participante de um grupo em uma thread separada e perde o grupo.

Não existe evento para o próprio grupo. Alguém entrar ou sair, uma mudança de nome ou um pin não produz nenhum webhook, então a composição do grupo é lida, não enviada por push: abra o grupo na página Groups, ou consulte-o como Gerenciando grupos WhatsApp mostra.

Próximos passos

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico.

Experimente na prática e obtenha um resumo de implementação