--- title: "Enviando para um grupo WhatsApp" description: "Envie uma mensagem de grupo WhatsApp com um ID de grupo em to, depois acompanhe a distribuição pelos três contadores de destinatários e um evento por participante." canonical: "https://bird.com/pt-br/documentacao/guides/whatsapp/groups/sending" --- # 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](/docs/guides/whatsapp/groups/management) cobre a criação de um grupo pela API e a distribuição do link de convite, e [Grupos WhatsApp](/docs/guides/whatsapp/groups) 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**](https://bird.com/dashboard/w/whatsapp/groups), leia-o em `to.group_id` de uma mensagem que chegou pelo grupo ou [liste seus grupos](/docs/guides/whatsapp/groups/management#list-your-groups). Substitua o ID de grupo do exemplo pelo seu. Inicialize o client para a sua linguagem usando o guia de SDK para [TypeScript](/docs/sdks/typescript), [Python](/docs/sdks/python), [Go](/docs/sdks/go) ou [PHP](/docs/sdks/php). Para exemplos em CLI, [instale e autentique o CLI](/docs/cli#authenticate) com acesso de escrita em WhatsApp. Use o host API para a sua [região do espaço de trabalho](/docs/api/regions) 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`](/docs/api/errors/E15018). **TypeScript** ```typescript const msg = await bird.whatsapp.send({ to: "wag_01krdgeqcxet5s7t44vh8rt9mg", text: { body: "The route sheet for Tuesday is up." }, }); console.log(msg.id, msg.status); ``` Examples: [TypeScript](/pt-br/documentacao/guides/whatsapp/groups/sending.ts.md) · [Python](/pt-br/documentacao/guides/whatsapp/groups/sending.py.md) · [Go](/pt-br/documentacao/guides/whatsapp/groups/sending.go.md) · [PHP](/pt-br/documentacao/guides/whatsapp/groups/sending.php.md) · [CLI](/pt-br/documentacao/guides/whatsapp/groups/sending.cli.md) · [MCP](/pt-br/documentacao/guides/whatsapp/groups/sending.mcp.md) · [cURL](/pt-br/documentacao/guides/whatsapp/groups/sending.curl.md) 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`](/docs/api/errors/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](/docs/guides/whatsapp/templates) é 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`](/docs/api/errors/E15001). Conteúdo livre ainda precisa de uma [janela de atendimento ao cliente](/docs/knowledge-base/whatsapp/customer-service-window) 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](/docs/api/reference/get-whatsapp-message) para ver até onde ela chegou. Três contadores reportam a distribuição: | Campo | O que reporta | | ----------------- | ---------------------------------------------------------------------------------------------- | | `recipient_count` | Participantes no momento da aceitação, o denominador para os outros dois | | `delivered_count` | Quantos WhatsApp confirmou que a mensagem alcançou, incluindo quem reportou apenas uma leitura | | `read_count` | Quantos a abriram | 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](/docs/api/reference/list-whatsapp-message-events). 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](/docs/guides/whatsapp/business-scoped-user-ids), 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](/docs/guides/whatsapp/webhooks/message-status) `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](/docs/api/reference/list-whatsapp-messages) da thread de um grupo, nas duas direções: **TypeScript** ```typescript for await (const msg of bird.whatsapp.list({ group_id: "wag_01krdgeqcxet5s7t44vh8rt9mg" })) { console.log(msg.id, msg.direction, msg.status); } ``` Examples: [TypeScript](/pt-br/documentacao/guides/whatsapp/groups/sending.ts.md) · [Python](/pt-br/documentacao/guides/whatsapp/groups/sending.py.md) · [Go](/pt-br/documentacao/guides/whatsapp/groups/sending.go.md) · [PHP](/pt-br/documentacao/guides/whatsapp/groups/sending.php.md) · [CLI](/pt-br/documentacao/guides/whatsapp/groups/sending.cli.md) · [cURL](/pt-br/documentacao/guides/whatsapp/groups/sending.curl.md) 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](/docs/guides/whatsapp/message-log) no dashboard. ## Custo Um envio de grupo é cobrado nos dois componentes que [Enviando mensagens WhatsApp](/docs/guides/whatsapp/sending-whatsapp#cost-and-billing) 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](/docs/knowledge-base/whatsapp/october-2026-pricing-changes). ## Solução de problemas - **`404` ([E15046](/docs/api/errors/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](/docs/api/errors/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](/docs/api/errors/E15018))**: Remova `from`. O grupo envia pelo número com o qual foi criado. - **`422` ([E15052](/docs/api/errors/E15052))**: Conteúdo interativo ou um template de autenticação. Veja [o que um grupo aceita](#2-o-que-um-grupo-aceita). - **`422` ([E15044](/docs/api/errors/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](/docs/guides/whatsapp/groups/receiving): identifique o remetente e responda ao grupo - [Gerenciando grupos WhatsApp](/docs/guides/whatsapp/groups/management): gerencie participantes, links de convite e solicitações de entrada - [Webhooks de status de mensagem](/docs/guides/whatsapp/webhooks/message-status): receba atualizações de entrega das suas mensagens - [IDs de usuário com escopo de negócio](/docs/guides/whatsapp/business-scoped-user-ids): identifique um participante cujo número de telefone você não tem ## Related resources - [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video) - [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer) - [WhatsApp message builder](/tools/whatsapp-message-builder) (tool) - [WhatsApp](/whatsapp-api) (product) [Get an implementation brief](/learn/workspace?topic=whatsapp)