LinkedIn
Instagram
Telegrama
Gmail
Perspectivas
Google Agenda
Participe da comunidade do Slack Índice
Limites e pontos de extremidade
Construindo com ele
API de Grupo do WhatsApp - 2026
WhatsApp API de Grupo em 2026: O que a Meta apoia e o que não apoia
A API de Grupos do WhatsApp da Meta está ativa na Cloud API, mas ela só funciona para Contas Comerciais Oficiais, limita cada grupo a 8 participantes, e tem não há um endpoint para adicionar alguém diretamente. Eis o que isso significa para um produto real, endpoint por endpoint, além do único caminho que remove todos os três limites.
Configurações do grupo API de nuvem Integração de Clientes da Acme Grupo
JD AS ML RK TN CW PB +1 8 / 8 participantes
Conta Comercial Oficial obrigatória
Grupo cheio: nenhum endpoint para adicionar um 9º participante
API de Grupos
A API do WhatsApp suporta mensagens em grupo?
Sim. A Plataforma do WhatsApp Business agora expõe uma API de Grupos na Cloud API, para que um número comercial possa criar grupos, enviar mensagens neles e gerenciar membros. Três condições a limitam: a empresa deve ser uma Conta Comercial Oficial, cada grupo tem o limite de 8 participantes, e há não há endpoint para adicionar um participante diretamente.
API de Grupo do WhatsApp: suportada vs não suportada Verificado com a documentação da API Cloud da Meta, agosto de 2026
Com suporte
Criar, listar e atualizar grupos em um número comercial da Cloud API
Envie mensagens de texto, mídia e modelos para um grupo
Gerar e redefinir o link de convite do grupo
Aprovar ou rejeitar solicitações de participação pendentes
Remover um participante de um grupo
Assine 4 eventos de webhook específicos de grupo
Não suportado
Adicionando um participante diretamente: apenas link de convite
Chamada de voz ou vídeo em grupo
Mensagens temporárias e mídia de visualização única
Editando ou apagando uma mensagem já enviada para o grupo
Ocultar a lista de participantes como administrador
Análise de desempenho por modelo para mensagens em grupo
Esta divisão segue a própria documentação da API de Grupos da Meta. Fonte: developers.facebook.com, API de Grupo do WhatsApp, verificado em agosto de 2026. O restante deste guia aborda cada endpoint, o que aciona a barreira de 8 participantes e a única lacuna que nenhuma das documentações da própria Meta menciona diretamente: não há como adicionar um participante a um grupo.
Definição
O que é a API de Grupos do WhatsApp?
O API de Grupos do WhatsApp é a camada de mensagens em grupo que a Meta adicionou sobre a API Cloud da plataforma do WhatsApp Business. Ela permite que um número de telefone comercial crie grupos, envie mensagens para eles e gerencie participantes por meio de um conjunto dedicado de endpoints, sem precisar migrar para outro produto.
Continua o mesmo
O mesmo
ID_DO_NUMERO_DE_TELEFONE usado para mensagens 1:1Mesma configuração de token de acesso e permissões em nível de aplicativo
O mesmo
/mensagens endpoint para enviar para um grupo O que há de novo
Um dedicado
/grupos família de endpoints: criar, listar, atualizar, excluirEndpoints de link de convite e solicitação de entrada
4 novos campos de webhook para eventos de ciclo de vida de grupo
Um número que já envia mensagens 1:1 através do Guia da API do WhatsApp não precisa de uma segunda integração para dar suporte a grupos. Ela precisa da permissão extra abordada a seguir e dos endpoints extras abordados mais adiante nesta página.
Elegibilidade
Quem pode usar a API de Grupos do WhatsApp?
Apenas um subconjunto de números da Plataforma do WhatsApp Business se qualifica para a API de Grupos do WhatsApp. Uma empresa deve executar um Conta Comercial Oficial na própria Cloud API antes que um único grupo possa ser criado, e dois tipos de números comuns sejam explicitamente excluídos.
Conta Comercial Oficial (OBA)
O número deve possuir o status de OBA da Meta, o nível verificado da WhatsApp Business Platform.
API Live na Nuvem
O número precisa estar em uso ativo na Cloud API, e não no aplicativo gratuito do WhatsApp Business.
O
mensagens_do_whatsapp_business permissãoO aplicativo conectado deve ter esta permissão aprovada antes que qualquer endpoint de grupo responda.
Inscrito no WABA correto
O aplicativo deve estar vinculado à conta do WhatsApp Business que possui o número.
Números no aplicativo WhatsApp Business
Excluído. A API de Grupos é um recurso da Cloud API, e não algo que o aplicativo Business voltado ao consumidor expõe.
Números em Conversas com Múltiplas Soluções
Excluído. Números compartilhados entre múltiplos provedores de soluções de negócios não podem executar a API de Grupos.
Documentação de introdução à API de Grupos da Meta, verificada em agosto de 2026.
Limites
Quantos participantes um grupo da API do WhatsApp pode ter?
Máximo de 8 participantes por grupo. Um único número comercial pode conter até 10.000 grupos, e apenas um negócio de API em nuvem pode operar dentro de um determinado grupo por vez.
Na API do Grupo do WhatsApp, o número comercial que cria o grupo ocupa uma das oito vagas como participante, o que deixa espaço para clientes reais ou membros da equipe em vez das oito vagas completas. Para um produto que precisa de um grupo de integração, um canal de projeto ou uma célula de suporte com mais do que poucas pessoas, esse limite é atingido rapidamente.
O limite de 8 participantes não é um bug técnico. Ele reflete uma escolha de design deliberada para mensagens de negócios estruturadas, em vez de chat comunitário aberto, o que constitui um caso de uso materialmente diferente de um grupo pessoal do WhatsApp. A questão prática para uma equipe de produto não é se 8 é suficiente em teoria, mas sim se o grupo consegue crescer além das suas primeiras 8 pessoas, o que é respondido nas próximas duas seções.
Referência da API
Quais endpoints a API de Grupos do WhatsApp expõe?
A API de Grupos do WhatsApp adiciona 12 endpoints além da API Cloud padrão: criação de grupos, metadados, o link de convite e solicitações de entrada. Nenhum deles adiciona um participante diretamente.
Método
Caminho
O que ele faz
POST
//groups
Cria um novo grupo e retorna seu primeiro link de convite
OBTER
//groups
Lista todos os grupos ativos vinculados ao número da empresa
OBTER
/?campos=
Lê os metadados de um único grupo: assunto, descrição, contagem de participantes
POST
/
Atualiza o assunto, a descrição ou a foto do grupo
DELETE
/
Exclui o grupo e remove todos os participantes de uma só vez
OBTER
//invite_link
Retorna o link de convite atual do grupo
POST
//invite_link
Redefine o link de convite, o que invalida todos os links compartilhados anteriormente
OBTER
//join_requests
Lista as solicitações de entrada aguardando aprovação
POST
//join_requests
Aprova uma ou mais solicitações de entrada pendentes
DELETE
//join_requests
Rejeita uma ou mais solicitações pendentes de participação
DELETE
//participants
Remove um ou mais participantes do grupo
POST
//messages
Envia uma mensagem de texto, de mídia ou de modelo para o grupo
Observe atentamente o que está faltando: há um
DELETE /participants endpoint, e não POST /participants ponto final. Você pode remover alguém de um grupo da API do WhatsApp. Não é possível adicioná-los da mesma maneira. A próxima seção aborda exatamente o que isso significa e o que fazer a respeito. O abismo
Você pode adicionar alguém a um grupo do WhatsApp com a API Cloud?
Não. A API do Grupo do WhatsApp não possui um endpoint de adicionar participante. Os participantes só podem entrar por meio de um link de convite compartilhado, e a empresa pode então aprovar ou rejeitar a solicitação de entrada.
EXCLUIR //participants remove pessoas, não adiciona nenhuma.O único caminho de entrada, do início ao fim
1
Criar o grupo
POST /groups retorna um group_id e um primeiro link de convite
2
Obter o link de convite
GET ou POST /invite_link, reconfigurável a qualquer momento
3
Envie o link
POST /messages, um modelo 1:1 enviado ao potencial cliente
4
Eles solicitam para entrar
Tocar no link cria uma entrada em join_requests
Você aprova
POST /join_requests os confirma como participante
# Etapa 2: obter ou redefinir o link de convite do grupo
enrolar -X POST \ "https://graph.facebook.com/v21.0//invite_link" \ -H "Autorização: Bearer "
// 200 OK
{
"link_de_convite": "https://chat.whatsapp.com/"
}Esta é a única forma de entrar. Não há importação em massa, nem CSV de números de telefone, nem endpoint que adicione uma lista de pessoas a um grupo em uma única chamada. Cada pessoa precisa tocar em um link e aguardar aprovação, uma de cada vez. Para um punhado de contatos VIP, isso é um pequeno incômodo. Para um fluxo de produtos recorrente, integrar cada novo cliente a um grupo dedicado, lotar um canal de projeto, construir uma célula de suporte por conta, é uma etapa manual que ocorre fora da API para cada pessoa, todas as vezes.
Compare isso a um API de link do WhatsApp usado para contato 1:1, onde o compartilhamento de um link é o ponto de entrada por design. Dentro de um grupo, a mesma mecânica de link de convite se torna a única porta disponível, quer isso se encaixe ou não no fluxo real de integração do produto.
Uma conta do WhatsApp vinculada por meio do Unipile não possui esta restrição: o mesmo tipo de ação que remove um participante tem uma contraparte que adiciona um diretamente, em nome do usuário autenticado. Detalhes completos, endpoints incluídos, mais abaixo nesta página em como acessar grupos do WhatsApp a partir da própria conta de um usuário.
Não suportado
O que não é suportado nos grupos da API do WhatsApp?
Seis tipos de mensagem, três ações administrativas e uma API estão indisponíveis dentro de um grupo criado através da API do WhatsApp, mesmo que cada uma delas funcione perfeitamente em uma conversa normal de 1:1 no mesmo número.
Categoria
Não disponível
Tipos de mensagem
Chamadas, mensagens temporárias, mídia de visualização única, modelos de autenticação, mensagens comerciais e mensagens interativas
Ações do administrador
Ocultar a lista de participantes, editar uma mensagem já enviada para o grupo e excluir uma mensagem já enviada para o grupo
APIs
A API de Chamadas não funciona dentro de uma conversa em grupo
Análises
Não há métricas de desempenho por modelo para modelos usados em um grupo. A Meta recomenda manter os modelos de grupo separados dos modelos de 1:1 por esse motivo.
Como fazer
Como você envia uma mensagem para um grupo do WhatsApp?
Use o mesmo
POST //messages endpoint como mensagens ponto a ponto, definir tipo_de_destinatário para grupo, e coloque o ID do grupo em para. Não há um endpoint separado para mensagens de grupo.Mensagem de texto, curl
enrolar -X POST \ "https://graph.facebook.com/v21.0//messages" \ -H "Autorização: Bearer " \ -H "Content-Type: application/json" \ -d '{
"messaging_product": "whatsapp",
"recipient_type": "group",
"para": "",
"type": "text",
"{ "body": "Bem-vindo ao canal do projeto." }
}'Mensagem de modelo, Node.js
const response = await fetch(
`https://graph.facebook.com/v21.0/${ID_DE_NUMERO_DE_TELEFONE_DA_EMPRESA}/messages`,
{
método: "POST",
cabeçalhos: {
Authorization: `Portador ${TOKEN_DE_ACESSO}`,
"Tipo-de-Conteúdo": "application/json",
},
corpo: JSON.stringify({
messaging_product: "whatsapp",
tipo_de_destinatário: "grupo",
para: ID_DO_GRUPO,
tipo: "modelo",
modelo: {
nome: "boas-vindas ao onboarding",
idioma: { código: "pt_BR" },
},
}),
}
);As mensagens de mídia seguem o padrão idêntico: fazer referência à mídia enviada e, em seguida, enviá-la com
recipient_type: "group" da mesma forma que texto ou um modelo. A entrega, a formatação, as novas tentativas e os códigos de erro seguem as mesmas regras de qualquer outra mensagem da Cloud API, em grupo ou não.O que não muda na API de Grupos do WhatsApp: não há limite de taxa específico para grupos documentado separadamente dos limites padrão de mensagens, nem formato de mensagem específico para grupos. O único campo novo é
tipo_de_destinatário.Webhooks
Quais webhooks são disparados em eventos de grupo do WhatsApp?
A API do Grupo do WhatsApp adiciona quatro campos de webhook para cobrir a atividade do grupo, e todos os quatro exigem uma assinatura separada antes que qualquer evento de grupo chegue ao seu endpoint. Nenhum deles é coberto pelo webhook de mensagem padrão que você talvez já use para chats individuais.
Campo do webhook
Dispara quando
atualização_do_ciclo_de_vida_do_grupo
Um grupo é criado ou excluído no número comercial
atualização_dos_participantes_do_grupo
Alterações de membros: uma solicitação de entrada é aprovada ou um participante é removido
atualização_das_configurações_do_grupo
O assunto, a descrição ou a foto do grupo foi alterada
atualização_do_status_do_grupo
O status geral do grupo muda na plataforma
Nomes dos campos e requisitos de assinatura de acordo com a documentação de introdução da API de Grupos da Meta, verificada em agosto de 2026. Consulte o referência completa do payload do webhook para estruturas de campos exatas.
Preços
Quanto custa o envio de mensagens em grupo no WhatsApp?
Por mensagem, da mesma forma que qualquer outra conversa de API em nuvem. Não há tabela de preços separada e nenhum desconto por grupo.
A Meta migrou toda a Plataforma do WhatsApp Business para a precificação por mensagem em 1º de julho de 2025, substituindo o modelo mais antigo por conversa. As mensagens de grupo enviadas por meio da API de Grupos do WhatsApp são cobradas da mesma forma: cada mensagem enviada para um grupo conta individualmente, com a mesma tarifa por mensagem de uma mensagem individual (1:1) na mesma categoria, no mesmo país.
Não há desconto por volume específico para grupos e, conforme abordado anteriormente nesta página, não há um painel de desempenho separado para os modelos usados em um grupo. Orçar um caso de uso com uso intensivo de grupos significa tratar cada mensagem de grupo exatamente como ela aparece na fatura: mais uma mensagem cobrada pela taxa padrão por mensagem.
Para ver a tabela de preços completa de todas as categorias de conversa e países, consulte nosso Preços da API do WhatsApp Business detalhamento.
Contas vinculadas
Como você acessa grupos do WhatsApp a partir da conta de um próprio usuário?
Uma conta do WhatsApp se conecta através do Unipile da mesma forma que uma pessoa usaria o WhatsApp Web: escaneando Código QR ou código de pareamento, em nome do usuário autenticado, com na verificação do Meta Business necessário. Uma vez vinculados, seus grupos são chats padrão, acessíveis através dos mesmos endpoints de chat e mensagens que qualquer outra conversa.
Unipile atua como um intermediário técnico independente entre um produto e o WhatsApp: cada chamada abaixo é executada em nome do usuário autenticado que vinculou a conta, e não como uma integração permanente com o WhatsApp ou a Meta.
Nota de tratamento de dados
Limitado à sessão autenticada
Os dados de grupos recuperados por meio de uma conta vinculada do WhatsApp não são armazenados em um sistema paralelo nem mantidos como um arquivo independente. O acesso é limitado à sessão do usuário autenticado quem vinculou a conta e todas as ações de requisição em nome de esse usuário.
Limites da plataforma e uso responsável
Limites do próprio WhatsApp, transmitidos
O Unipile repassa os próprios limites de taxa nativos do WhatsApp na conta vinculada, em vez de impor um separado. A frequência com que uma mensagem é enviada a um grupo e a quantidade de grupos que uma conta gerencia continua sendo uma decisão do lado do cliente, feitos dentro dos limites do próprio WhatsApp para aquela conta.
Uma vez que uma conta é vinculada, seus grupos aparecem junto com qualquer outro chat. Filtrar para o WhatsApp e navegar pelas páginas usando a paginação utiliza o mesmo endpoint de lista de chats que qualquer outra conversa:
Listar todos os grupos e chats do WhatsApp em uma conta vinculada, curl
enrolar -X OBTER \ ""https://.unipile.com:/api/v1/chats?account_type=WHATSAPP&account;_id=&limit;=50"" \ -H "X-API-KEY: " \ -H "accept: application/json"Iniciar um novo grupo funciona da mesma maneira que iniciar qualquer chat com vários destinatários: passe mais de uma entrada em
attendees_ids, formatado da mesma forma que o WhatsApp identifica contatos internamente.Iniciar um novo grupo no WhatsApp, curl
enrolar -X POST \ "https://.unipile.com:/api/v1/chats"" \ -H "X-API-KEY: " \ -F "account_id=" \ -F "attendees_ids[]=33600000001@s.whatsapp.net" \ -F "attendees_ids[]=33600000002@s.whatsapp.net" \ -F "attendees_ids[]=33600000003@s.whatsapp.net" \ -F "assunto=Integração de Clientes da Acme" \ -F "Bem-vindo ao grupo"O SDK para Node expõe a mesma interface de chat para ver quem já está em um grupo:
Listar os participantes de um grupo, SDK do Node.js
import { UnipileClient } from "unipile-node-sdk";
const client = new UnipileClient(BASE_URL, TOKEN_DE_ACESSO);
const participantes = await cliente.mensagens.obterTodosOsParticipantesDoChat(chat_id);É aqui que uma conta vinculada diverge da API do Grupo do WhatsApp:
PATCH /chats/{chat_id} suporta um adicionarParticipante ação, junto com removerParticipante e obterLinkDeConvite, nas conversas do WhatsApp e do Telegram. Adicionar alguém exige que o proprietário da conta tenha a permissão "Adicionar outros membros" do grupo no próprio WhatsApp, a mesma permissão que se aplicaria se ele adicionasse essa pessoa manualmente pelo celular.Adicionar, remover ou convidar um participante, SDK do Node.js
// Adicionar um participante (apenas WhatsApp e Telegram)
await cliente.mensagens.executarAcao({
chat_id,
ação: "adicionarParticipante",
valor: "33600000009@s.whatsapp.net",
});
// Remover um participante
await cliente.mensagens.executarAcao({
chat_id,
ação: "removerParticipante",
valor: "33600000009@s.whatsapp.net",
});
// Obter o link de convite do grupo
const { link_de_convite } = await cliente.mensagens.executarAcao({
chat_id,
ação: "obterLinkDeConvite",
});Não há limite publicado sobre quantas pessoas um grupo pode conter quando é gerenciado por uma conta vinculada: o grupo opera sob as mecânicas nativas do WhatsApp na conta conectada, e não o limite de 8 participantes da API do Cloud. A Unipile não documenta ou impõe um limite de participantes próprio além disso.
A referência completa de parâmetros para essas três ações, incluindo o formato exato de ID do provedor por plataforma, está no Unipile endpoint de ação do chat documentação.
Decisão
API de Grupos ou conta vinculada: qual delas se adapta ao seu produto?
Ambos os caminhos, a API de Grupos do WhatsApp e uma conta vinculada, criam e enviam mensagens para grupos do WhatsApp. Eles atendem a diferentes produtos, portanto, a escolha certa depende de o caso de uso poder ou não conviver com um limite de 8 participantes e apenas por convite.
Requisito
API de Grupos da Meta
Conta vinculada
Requisito de conta
Conta comercial oficial, na API do Cloud
Conta do WhatsApp existente, vinculada por QR code ou código de pareamento
Número máximo de participantes
8 por grupo
Mecânica de grupo nativa do WhatsApp, sem limite separado do Unipile
Adicionar um participante diretamente
Indisponível: link de convite e apenas aprovação
Disponível, através da ação addParticipant
Link de convite
Gerar e redefinir via API
Gerar por meio da ação getInviteLink
Ler o histórico do grupo existente
Não faz parte da API: as mensagens chegam por webhook conforme acontecem
Sincronização de histórico completa mais endpoints de lista de mensagens
Listar participantes
Apenas a contagem de participantes, via metadados do grupo
Lista completa de participantes, uma ligação
Tipos de mensagem
Texto, mídia, texto de modelo, mídia de modelo
Texto, mídia e tipos de mensagens nativas do WhatsApp
Webhooks
4 campos de grupo dedicados, cada um sendo uma assinatura separada
Webhooks de mensagens e chat padrão
Modelo de cobrança
Por mensagem, preços de conversação padrão da Cloud API
Assinatura da Unipile, sem cobrança por mensagem de WhatsApp
Quem é o dono da conversa
A empresa, como titular da Conta Comercial Oficial
O usuário final, a Unipile atua em nome deles
API do Grupo do WhatsApp - FAQ
Respostas para as perguntas que a documentação da API de Grupos do WhatsApp da Meta não explica diretamente.
Não. A API de Grupos do WhatsApp está ativa na Cloud API da Plataforma WhatsApp Business a partir de 2026. A confusão vem do lado do ecossistema: várias plataformas de mensagens de terceiros ainda não implementaram suporte a grupos, e algumas centrais de ajuda e solicitações de recursos abertas ainda descrevem os grupos da API do WhatsApp como não suportados, embora a documentação da própria Meta confirme o contrário.
Não, não para a API de Grupos da Meta: um Conta Comercial Oficial na Cloud API é obrigatório, e números no aplicativo WhatsApp Business ou em Conversas de Múltiplas Soluções são excluídos. Conta do WhatsApp vinculada através do Unipile é um caminho diferente: ele se conecta por código QR ou código de pareamento, em nome do usuário autenticado, sem nenhuma verificação do Meta Business.
Máximo de 8 participantes por grupo na API de Grupos da Cloud API, e até 10.000 grupos por número comercial. Uma conta do WhatsApp vinculada por meio do Unipile segue a mecânica de grupos nativa do WhatsApp na conta vinculada, em vez desse limite.
A Meta retorna o ID do grupo quando o grupo é criado, através
POST //groups. Os IDs de grupo existentes são listados com GET //groups. Em uma conta vinculada, o mesmo ID aparece como chat_id retornado ao listar chats ou iniciar um novo grupo.Isso depende do caminho. A API de Grupos da Cloud API é acionada por webhooks: as mensagens chegam à medida que acontecem, e não há um endpoint para puxar o histórico passado de um grupo. Uma conta do WhatsApp vinculada via Unipile pode recuperar mensagens existentes e ressynchronizar o histórico completo de uma conversa em nome do usuário autenticado.
Não. O Unipile é um intermediário técnico independente e é não afiliado, endossado ou patrocinado pelo WhatsApp ou Meta. Ele conecta a própria conta do WhatsApp do usuário em nome dele e não opera como um Provedor de Soluções do WhatsApp Business para a API em Nuvem descrita anteriormente nesta página.
Ainda tem dúvidas? Nossa equipe está aqui para ajudar.
BR 
EN 
FR 
ES 
DE 
IT 
NL 
PL 
TR