Enviando para um grupo WhatsApp

Um envio para grupo é um POST /v1/whatsapp/messages comum cujo to nomeia um grupo em vez de uma pessoa: uma solicitação, uma mensagem, e cada participante daquele chat de grupo a recebe e pode responder onde os demais veem. O que muda é o relatório. A mensagem carrega contadores de quantos participantes ela alcançou, e a entrega é confirmada um participante por vez.

Criar e administrar um grupo é algo separado de enviar mensagens para ele. Gerenciando grupos WhatsApp cobre a criação de um grupo pela API e a distribuição do link de convite, e Grupos WhatsApp cobre para que serve um grupo e os limites que WhatsApp impõe a ele.

Pré-requisitos

Você precisa de uma chave API com permissão de escrita em WhatsApp e o ID de um grupo Active (wag_…). Copie-o na aba Details do grupo na página Groups, leia-o em to.group_id de uma mensagem que chegou pelo grupo ou liste seus grupos.

Substitua o ID de grupo do exemplo pelo seu. Inicialize o client para a sua linguagem usando o guia de SDK para TypeScript, Python, Go ou PHP. Para exemplos em CLI, instale e autentique o CLI com acesso de escrita em WhatsApp. Use o host API para a sua região do espaço de trabalho nas solicitações cURL.

1. Envie a mensagem

Coloque o ID do grupo em to e omita from. Um grupo está vinculado ao número comercial com o qual foi criado, então esse número é o único pelo qual a mensagem pode sair; informar um remetente retorna uma 422 E15018.

const msg = await bird.whatsapp.send({
  to: "wag_01krdgeqcxet5s7t44vh8rt9mg",
  text: { body: "The route sheet for Tuesday is up." },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="wag_01krdgeqcxet5s7t44vh8rt9mg",
    text={"body": "The route sheet for Tuesday is up."},
)
print(msg.id, msg.status)

msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
	To:   "wag_01krdgeqcxet5s7t44vh8rt9mg",
	Text: &bird.WhatsAppTextSend{Body: "The route sheet for Tuesday is up."},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$text = (new WhatsAppMessageSendRequestText())
    ->setBody("The route sheet for Tuesday is up.");
$message = $bird->whatsapp->send(
    to: 'wag_01krdgeqcxet5s7t44vh8rt9mg',
    text: $text,
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --text 'The route sheet for Tuesday is up.' \
  --to wag_01krdgeqcxet5s7t44vh8rt9mg

curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "to": "wag_01krdgeqcxet5s7t44vh8rt9mg",
      "text": { "body": "The route sheet for Tuesday is up." }
    }'

A API retorna 202 com o grupo ecoado em to.group_id, status: accepted e recipient_count: quantas pessoas estavam no grupo quando o envio foi aceito. Essa contagem é o denominador para tudo na etapa 3 e é fixada naquele momento. Alguém que entre pelo link de convite enquanto a mensagem está em trânsito não a recebe e não altera a contagem.

2. O que um grupo aceita

Um grupo aceita texto, imagens, vídeo, áudio, stickers, documentos, uma localização, cartões de contato e um template que o seu espaço de trabalho criou em qualquer categoria exceto autenticação. Dois tipos de conteúdo são recusados com uma 422 E15052, antes de a mensagem ser criada ou cobrada, porque WhatsApp não entrega nenhum dos dois a um chat de grupo:

• Qualquer conteúdo interativo: botões de resposta, menus de lista, botões de link, carrosséis e as solicitações de localização e informações de contato.
• Um template de autenticação. Envie o código de verificação de uso único diretamente ao participante.

Um template gerenciado por Bird é enviado de um número pertencente a Bird, que nunca é o número ao qual o grupo está vinculado, então endereçar um ao grupo retorna uma 422 E15001.

Conteúdo livre ainda precisa de uma janela de atendimento ao cliente aberta, e um grupo tem a sua própria: qualquer participante que envie uma mensagem ao grupo abre uma única janela de 24 horas para todo o grupo, e essa pessoa enviando uma mensagem a você fora do grupo não a abre. Quando a janela expira, um template é o que alcança o grupo.

3. Acompanhe a distribuição

Recupere a mensagem para ver até onde ela chegou. Três contadores reportam a distribuição:

Em uma mensagem de grupo, status reporta o ponto mais avançado que todos os destinatários alcançaram: ele muda para delivered somente quando delivered_count é igual a recipient_count, e permanece sent enquanto alguns confirmaram e outros não. Nenhuma mensagem WhatsApp tem status read, então a leitura é read_count e read_at. delivered_at e read_at são do primeiro destinatário, não do último. failed e rejected nunca são por participante, porque há uma única entrega a WhatsApp e uma única forma de ela ser recusada.

Um envio para um grupo ao qual ninguém havia entrado ainda não carrega nenhum contador, já que não há denominador a reportar, então trate to.group_id em vez dos contadores como o que distingue uma mensagem de grupo de uma individual.

Para ver a qual participante uma confirmação se refere, liste os eventos da mensagem. Um envio em grupo se desdobra em no máximo um whatsapp.delivered e no máximo um whatsapp.read por participante, cada um com recipient contendo o número de telefone dessa pessoa, seu ID de usuário com escopo de negócio, ou ambos. Nenhum dos dois é garantido para qualquer pessoa: WhatsApp pula o recibo de entrega para um participante que já está olhando o chat, e uma leitura chega apenas se ele abrir a mensagem. Conte o que chegar em vez de esperar um de cada por participante, e leia os contadores para os totais. O único evento whatsapp.sent não traz recipient: essa é a única entrega ao WhatsApp, que não nomeia ninguém. Os webhooks whatsapp.delivered e whatsapp.read trazem o mesmo campo, que é como você diferencia callbacks idênticos entre si.

4. Leia a conversa de um grupo

Passe group_id para listar mensagens da thread de um grupo, nas duas direções:

for await (const msg of bird.whatsapp.list({ group_id: "wag_01krdgeqcxet5s7t44vh8rt9mg" })) {
  console.log(msg.id, msg.direction, msg.status);
}

for msg in client.whatsapp.list(group_id="wag_01krdgeqcxet5s7t44vh8rt9mg"):
    print(msg.id, msg.direction, msg.status)

for msg, err := range client.Whatsapp.List(context.Background(), bird.WhatsappListParams{
	GroupID: "wag_01krdgeqcxet5s7t44vh8rt9mg",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Direction, *msg.Status)
}

foreach ($bird->whatsapp->list(['group_id' => 'wag_01krdgeqcxet5s7t44vh8rt9mg']) as $message) {
    echo $message->getId(), ' ', $message->getDirection(), "\n";
}

bird whatsapp list --group-id wag_01krdgeqcxet5s7t44vh8rt9mg

curl "https://us1.platform.bird.com/v1/whatsapp/messages?group_id=wag_01krdgeqcxet5s7t44vh8rt9mg" \
  -H "Authorization: Bearer $BIRD_API_KEY"

Uma mensagem de grupo recebida é lida de volta com o participante que a escreveu em from, e um to que carrega tanto o seu número comercial quanto group_id: o número que a recebeu, qualificado pelo grupo pelo qual ela chegou. Nem to nem from corresponde a um grupo, então group_id é o único filtro que restringe a lista a um grupo. As mesmas mensagens estão no log de WhatsApp no dashboard.

Custo

Um envio de grupo é cobrado nos dois componentes que Enviando mensagens WhatsApp descreve, com uma diferença na precificação de cada um. A taxa de Bird é cobrada uma vez pelo envio e precificada pelo país do número comercial pelo qual saiu, porque um grupo pode abranger vários países e não tem um único país destinatário. A parcela da Meta acumula por participante que a mensagem alcançou, cada uma precificada pela tarifa individual comum do país daquele participante, então passthrough_amount cresce à medida que os recibos chegam. A partir de 1º de outubro de 2026, essa parcela também cobre conteúdo livre enviado ao grupo, que a Meta cobra por participante alcançado e desconta das 1.000 mensagens de serviço gratuitas por mês do número remetente: Mudanças de preço de outubro de 2026.

Solução de problemas

• 404 (E15046): O ID de grupo não corresponde a nenhum grupo deste espaço de trabalho. Um grupo pertence ao espaço de trabalho que o criou, então um ID de outro espaço de trabalho não é encontrado aqui.
• 409 (E15047): O grupo está pendente, suspenso, excluído ou falhou. Apenas um grupo Active pode receber mensagens, e um grupo permanece pendente até WhatsApp confirmá-lo.
• 422 (E15018): Remova from. O grupo envia pelo número com o qual foi criado.
• 422 (E15052): Conteúdo interativo ou um template de autenticação. Veja o que um grupo aceita.
• 422 (E15044): A janela de atendimento do grupo está fechada. Envie um template ou espere um participante escrever no grupo.
• status parado em sent: Menos de recipient_count participantes confirmaram a entrega. Leia os eventos da mensagem para ver quem está pendente.

Próximos passos

• Recebendo mensagens de grupo WhatsApp: identifique o remetente e responda ao grupo
• Gerenciando grupos WhatsApp: gerencie participantes, links de convite e solicitações de entrada
• Webhooks de status de mensagem: receba atualizações de entrega das suas mensagens
• IDs de usuário com escopo de negócio: identifique um participante cujo número de telefone você não tem