Resumo
Use a API de Grupos do WhatsApp para criar e gerenciar grupos do WhatsApp programaticamente. Você pode criar grupos, enviar convites para contatos pendentes, remover participantes, excluir grupos e recuperar uma lista de grupos ativos.
Observação: A API de Grupos do WhatsApp está disponível no plano Business.
Instruções
Antes de começar
Antes de usar a API de Grupos do WhatsApp:
Certifique-se de que sua conta Wati esteja no plano Business.
Gere um token de API da Wati e mantenha-o seguro.
Use a URL base da API fornecida na documentação da API da Wati.
Para mais informações, consulte Autenticação. As APIs da Wati usam autenticação via Bearer Token, e as solicitações devem incluir o token da API no cabeçalho Authorization.
Autenticação
Inclua os seguintes cabeçalhos em suas solicitações de API:
Authorization: Bearer <seu_token_de_api>
Content-Type: application/json
Por exemplo:
curl --location 'https://live-mt-server.wati.io/xxxxxx/api/ext/v3/conversations/groups' \
--header 'Authorization: Bearer <seu_token_de_api>' \
--header 'Content-Type: application/json'
Observação: Use a URL base da API exibida em sua conta Wati (Connectors > API Docs > API Endpoint) em vez da URL de exemplo acima.
Segurança: Nunca compartilhe seu token de API nem o envie para códigos públicos. A Wati recomenda armazenar as credenciais da API em variáveis de ambiente ou em um gerenciador de segredos.
Endpoints disponíveis
Método | Endpoint | Descrição |
|
| Criar um grupo do WhatsApp |
|
| Excluir um grupo do WhatsApp |
|
| Enviar convites para contatos pendentes |
|
| Remover participantes de um grupo |
|
| Listar grupos do WhatsApp ativos |
1. Criar um grupo do WhatsApp
POST /api/ext/v3/conversations/groups
Cria um novo grupo do WhatsApp.
Você pode opcionalmente especificar um canal. Se não especificar um canal, o canal padrão será usado. Os operadores são identificados pelo endereço de e-mail, enquanto os contatos são identificados pelo número de telefone ou destino de contato suportado.
Corpo da solicitação
{
"channel": "MeuCanal",
"name": "Grupo de Suporte VIP",
"description": "Grupo para clientes VIP",
"owner_email": "[email protected]",
"operator_emails": [
"[email protected]"
],
"contact_targets": [
"14155551234",
"14155555678"
],
"join_approval_mode": "auto_approve"
}Parâmetros do corpo da solicitação
Campo | Tipo | Descrição |
| string | O canal a ser usado. Se omitido, o canal padrão é usado. |
| string | O nome do grupo do WhatsApp. |
| string | A descrição do grupo do WhatsApp. |
| string | Endereço de e-mail do proprietário do grupo. |
| array | Endereços de e-mail dos operadores a serem adicionados ao grupo. |
| array | Número de telefone, BSUID ou ContactId dos contatos a serem adicionados ao grupo. Máximo de 7 contatos por grupo. |
| string | Especifica o modo de aprovação para ingressar no grupo. |
Resposta
Uma solicitação bem-sucedida retorna 201 Created e os detalhes do grupo recém-criado.
{
"group": {
"id": "6828abc123def456789012ab",
"name": "Grupo de Suporte VIP",
"description": "Grupo para clientes VIP",
"invite_link": "",
"channel_id": "ch_123",
"conversation_id": "conv_456",
"operators": [
{
"id": "682800000000000000000001",
"operator_id": "op_id",
"name": "Nome do Proprietário",
"role": "owner",
"added_at": "2026-08-13T08:27:00.8447035Z"
}
],
"contacts": [
{
"id": "682800000000000000000003",
"contact_id": "contact_id",
"wa_id": "+14155551234",
"name": "Nome do Contato",
"join_status": "pending"
}
],
"created_at": "2026-08-13T08:27:00.8448051Z"
}
}Códigos de resposta
Código | Descrição |
| O grupo foi criado com sucesso. |
| A solicitação é inválida. |
| A solicitação não está autorizada. |
| A solicitação é proibida. |
| Muitas solicitações. |
| Ocorreu um erro inesperado. |
2. Excluir um grupo do WhatsApp
DELETE /api/ext/v3/conversations/groups/{groupId}
Exclui o grupo do WhatsApp especificado.
Se o grupo já tiver sido excluído, o endpoint ainda retornará 200 OK.
Parâmetros de caminho
Parâmetro | Tipo | Obrigatório | Descrição |
| string | Sim | O ID do grupo a ser excluído. |
Resposta
Uma solicitação bem-sucedida retorna 200 OK.
{
"result": true
}Códigos de resposta
Código | Descrição |
| O grupo foi excluído com sucesso. |
| A solicitação é inválida. |
| A solicitação não está autorizada. |
| A solicitação é proibida. |
| Muitas solicitações. |
| Ocorreu um erro inesperado. |
3. Enviar convites de grupo
POST /api/ext/v3/conversations/groups/{groupId}/invites
Envia um convite de grupo para todos os contatos que ainda estão pendentes.
A API verifica os contatos no grupo, identifica aqueles com status de entrada pendente e envia o modelo de convite de grupo para a conversa 1:1 de cada contato.
Parâmetros de caminho
Parâmetro | Tipo | Obrigatório | Descrição |
| string | Sim | O ID do grupo para o qual enviar os convites. |
Resposta
Uma solicitação bem-sucedida retorna o resultado do convite para cada contato pendente.
{
"total_pending": 3,
"sent": 2,
"failed": 1,
"results": [
{
"contact_name": "Alice",
"phone": "14155551234",
"success": true
},
{
"contact_name": "Bob",
"phone": "14155555678",
"success": true
},
{
"contact_name": "Charlie",
"phone": "",
"success": false,
"error": "Contato apenas por BSUID, sem número de telefone"
}
]
}A resposta inclui:
total_pending: Número de contatos com um status de entrada pendente.sent: Número de convites enviados com sucesso.failed: Número de convites que não puderam ser enviados.results: Resultado do convite para cada contato pendente.
Códigos de resposta
Código | Descrição |
| Os resultados dos convites foram retornados com sucesso. |
| A solicitação é inválida. |
| A solicitação não está autorizada. |
| A solicitação é proibida. |
| Muitas solicitações. |
| Ocorreu um erro inesperado. |
4. Remover participantes de um grupo do WhatsApp
DELETE /api/ext/v3/conversations/groups/{groupId}/participants
Remove operadores e/ou contatos de um grupo do WhatsApp.
Você deve fornecer pelo menos um e-mail de operador ou destino de contato.
Parâmetros de caminho
Parâmetro | Tipo | Obrigatório | Descrição |
| string | Sim | O ID do grupo do qual remover participantes. |
Corpo da solicitação
{
"operator_emails": [
"[email protected]"
],
"contact_targets": [
"14155551234"
]
}Parâmetros do corpo da solicitação
Campo | Tipo | Descrição |
| array | Endereços de e-mail dos operadores a serem removidos do grupo. |
| array | Número de telefone, BSUID ou ContactId dos contatos a serem adicionados ao grupo. Máximo de 7 contatos por grupo. |
Você pode fornecer operator_emails, contact_targets, ou ambos. Pelo menos um deve ser fornecido.
Resposta
Uma solicitação bem-sucedida retorna 200 OK.
{
"result": true
}Códigos de resposta
Código | Descrição |
| Os participantes foram removidos com sucesso. |
| A solicitação é inválida. |
| A solicitação não está autorizada. |
| A solicitação é proibida. |
| Muitas solicitações. |
| Ocorreu um erro inesperado. |
5. Listar grupos do WhatsApp ativos
POST /api/ext/v3/conversations/groups/list
Retorna uma lista paginada por cursor de grupos ativos do WhatsApp.
Você pode filtrar opcionalmente os resultados por canal ou por IDs de grupo específicos. Se não especificar um canal, o canal padrão será usado.
Corpo da solicitação
{
"channel": "MeuCanal",
"limit": 20
}Parâmetros do corpo da solicitação
Campo | Tipo | Descrição |
| string | O canal a ser usado. Se omitido, o canal padrão é usado. |
| integer | O número de grupos a retornar na resposta. |
Resposta
Uma solicitação bem-sucedida retorna 200 OK com os grupos ativos e informações de paginação.
{
"groups": [
{
"id": "6828abc123def456789012ab",
"name": "Grupo de Suporte VIP",
"description": "Grupo para clientes VIP",
"invite_link": "https://chat.whatsapp.com/abc123",
"channel_id": "ch_123",
"conversation_id": "conv_456",
"operators": [
{
"id": "682800000000000000000001",
"operator_id": "op_id",
"name": "Proprietário",
"role": "owner",
"added_at": "2026-08-13T08:27:00.8595387Z"
}
],
"contacts": [
{
"id": "682800000000000000000003",
"contact_id": "contact_id",
"wa_id": "+14155551234",
"name": "Alice",
"join_status": "joined",
"joined_at": "2026-08-13T08:27:00.8595402Z"
}
],
"created_at": "2026-08-13T08:27:00.8595404Z"
}
],
"continuous_token": "eyJsIjoiNjgyOGFiYzEyM2RlZjQ1Njc4OTAxMmFiIn0=",
"total": 5
}Paginação
O endpoint Listar Grupos retorna resultados em páginas.
Se mais grupos estiverem disponíveis, a resposta inclui um continuous_token. Use este token para recuperar as páginas subsequentes.
Quando continuous_token estiver ausente ou for null, não há mais resultados.
Códigos de resposta
Código | Descrição |
| A lista de grupos ativos foi retornada com sucesso. |
| A solicitação é inválida. |
| A solicitação não está autorizada. |
| A solicitação é proibida. |
| Muitas solicitações. |
| Ocorreu um erro inesperado. |
Respostas de erro
Os seguintes códigos de status HTTP podem ser retornados pelos endpoints da API de Grupos do WhatsApp:
Código | Descrição |
| A solicitação é inválida. |
| A solicitação não está autorizada. |
| A solicitação é proibida. |
| Muitas solicitações. |
| Ocorreu um erro inesperado. |
Para respostas 400, 403 e 500, a API pode retornar detalhes adicionais, como código de erro, mensagem e carimbo de data/hora.
Exemplo de resposta de erro
{
"details": "string",
"code": 0,
"message": "string",
"timestamp": "2026-08-13T09:01:03.204Z"
}Para erros relacionados à autenticação, verifique se sua solicitação inclui um token de API válido no cabeçalho Authorization. Consulte Autenticação para obter mais informações.