> ## Documentation Index > Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt > Use this file to discover all available pages before exploring further. # Grupos > Avisar turmas e times no WhatsApp pela conexão não oficial: listar, enviar, convidar e gerenciar participantes. Grupos no WhatsApp são onde **turmas, equipes e comunidades** conversam juntos. Pelo Notifique você envia aviso para o grupo inteiro, gerencia participantes e manda link de convite, **só na conexão não oficial** (número pareado por QR ou link). ## Em poucas palavras * **Só conexão não oficial**, instância oficial (Meta) **não** envia nem gerencia grupos pela API. * Use a **mesma instância** que você já pareou para envios 1 a 1. * Chave com escopo **`whatsapp:groups`** na integração que precisa. * Envio para grupo = mesma rota de mensagem; só muda o `to` (`...@g.us`). **Linha oficial:** grupos, participantes e convites **não estão disponíveis**. Use [conexão não oficial](/whatsapp-api/como-funciona/modos-de-conexao) ou atendimento 1 a 1 na oficial. *** ## Quando usar | Situação | Usar grupos pela API? | | -------------------------------------------------------- | -------------------------------------------------------------------- | | Avisos para **várias turmas/equipes** (não oficial) | **Sim** | | Automatizar **convites** e **participantes** via ERP/CRM | **Sim** | | Instância **oficial** (Meta) | **Não**, use 1 a 1 ou mude para não oficial | | Só atendimento **1 a 1** | Não. Use o [WhatsApp normal](/whatsapp-api/como-funciona/introducao) | Comparação completa: [Modos de conexão](/whatsapp-api/como-funciona/modos-de-conexao). *** ## O que você pode fazer `POST /v1/whatsapp/messages` com JID do grupo em `to` (`120363...@g.us`). `GET /v1/whatsapp/instances/{id}/groups` com paginação. Listar, adicionar e remover pessoas nos grupos permitidos. Enviar link no privado, revogar ou consultar código de convite. Rotas e campos: **referência da API** do WhatsApp (seção Grupos). *** ## Antes de começar | Item | Obrigatório | | ----------------------------------------- | ----------- | | Instância **não oficial** e **ACTIVE** | Sim | | Escopo **`whatsapp:groups`** na chave | Sim | | Número **admin** nos grupos que vai mexer | Recomendado | Ainda não pareou? [Quick Start WhatsApp](/whatsapp-api/como-funciona/quick-start) (aba **não oficial**). Escopos: [Escopos da API Key](/whatsapp-api/como-funciona/escopos-api-key). Substitua `sk_live_xxxxx` pela sua chave e `{instanceId}` pelo id da instância. Base URL: `https://api.notifique.dev`. A API Key pertence a **um** workspace. Na v1 **não envie** `x-workspace-id`. *** ## 1. Listar grupos Retorna a lista **paginada** de grupos da instância. ```http theme={null} GET /v1/whatsapp/instances/{instanceId}/groups?page=1&limit=20 Authorization: Bearer sk_live_xxxxx ``` Parâmetros opcionais: `page` (padrão 1), `limit` (padrão 20, máximo 100). **Com grupos carregados** ```json theme={null} { "success": true, "data": [ { "id": "120363295648424210@g.us", "name": "Meu Grupo", "participantsCount": 5, "owner": "5511999999999@s.whatsapp.net", "creation": 1699000000 } ], "pagination": { "page": 1, "limit": 20, "total": 5 } } ``` **Ainda sincronizando** ```json theme={null} { "success": true, "loading": true, "message": "Lista de grupos está sendo carregada. Tente novamente em alguns segundos.", "data": [], "pagination": { "page": 1, "limit": 20, "total": 0 } } ``` Guarde o **`id`** (ex.: `120363295648424210@g.us`) para os próximos passos. ### Participantes do grupo ```http theme={null} GET /v1/whatsapp/instances/{instanceId}/groups/120363295648424210@g.us/participants Authorization: Bearer sk_live_xxxxx ``` Na URL, codifique `@` como `%40` se o cliente exigir. ```json theme={null} { "success": true, "data": { "participants": [ { "id": "5511999999999@s.whatsapp.net", "admin": "superadmin" }, { "id": "5511888888888@s.whatsapp.net", "admin": "admin" } ] } } ``` *** ## 2. Enviar mensagem no grupo Mesma rota do WhatsApp individual. Coloque o **JID do grupo** em `to`. ```http theme={null} POST /v1/whatsapp/messages Content-Type: application/json Authorization: Bearer sk_live_xxxxx ``` ```json theme={null} { "instanceId": "clxx...", "to": ["120363295648424210@g.us"], "type": "text", "payload": { "message": "Olá, grupo! Aviso enviado pela API." } } ``` **Resposta (202)** ```json theme={null} { "messageIds": ["clxx1..."], "status": "QUEUED", "scheduledAt": null } ``` **Vários grupos de uma vez** ```json theme={null} { "instanceId": "clxx...", "to": ["120363295648424210@g.us", "120363295648424211@g.us"], "type": "text", "payload": { "message": "Aviso para vários grupos." } } ``` *** ## 3. Adicionar ou remover participantes ```http theme={null} POST /v1/whatsapp/instances/{instanceId}/groups/participants Content-Type: application/json Authorization: Bearer sk_live_xxxxx ``` **Adicionar** ```json theme={null} { "to": ["120363295648424210@g.us"], "action": "add", "participants": ["5511888888888", "5511777777777"] } ``` **Remover** ```json theme={null} { "to": ["120363295648424210@g.us"], "action": "remove", "participants": ["5511888888888"] } ``` **Resposta (200), exemplo** ```json theme={null} { "success": true, "data": { "results": [ { "groupJid": "120363295648424210@g.us", "success": true, "action": "add", "participantsCount": 2 } ] } } ``` Seu número precisa ser **admin** do grupo no WhatsApp. Caso contrário, a operação falha. *** ## 4. Enviar convite no privado Manda o link de convite para um ou mais números individuais. ```http theme={null} POST /v1/whatsapp/instances/{instanceId}/groups/invite Content-Type: application/json Authorization: Bearer sk_live_xxxxx ``` ```json theme={null} { "groups": ["120363295648424210@g.us"], "to": ["5511999999999"], "description": "Convite para o grupo da equipe" } ``` ```json theme={null} { "success": true, "data": { "results": [ { "groupJid": "120363130091228687@g.us", "success": true, "data": { "send": true, "inviteUrl": "https://chat.whatsapp.com/EYkW0HWQLJ7CS82xdLIu4i" } } ] } } ``` *** ## 5. Revogar ou consultar link de convite **Revogar link atual** ```http theme={null} POST /v1/whatsapp/instances/{instanceId}/groups/invite/revoke Content-Type: application/json Authorization: Bearer sk_live_xxxxx ``` ```json theme={null} { "groupJid": "120363295648424210@g.us" } ``` **Consultar link ou código atuais** ```http theme={null} GET /v1/whatsapp/instances/{instanceId}/groups/invite-code?groupJid=120363295648424210@g.us Authorization: Bearer sk_live_xxxxx ``` ```json theme={null} { "success": true, "data": { "inviteUrl": "https://chat.whatsapp.com/Gst4H0uNCjMFEwddWjWpm9", "inviteCode": "Gst4H0uNCjMFEwddWjWpm9" } } ``` *** ## Limitações importantes * **Só não oficial**, instância oficial retorna `WHATSAPP_GROUPS_UNOFFICIAL_ONLY`. * Não cria grupo do zero via API (use grupo existente ou crie no celular antes). * Adicionar pessoas exige **admin** com permissão no WhatsApp. * Lista pode retornar `loading: true` na primeira consulta, tente de novo em alguns segundos. * As regras do **próprio WhatsApp** continuam valendo; a API não substitui permissões do app. *** ## Erros comuns | `code` | O que fazer | | --------------------------------- | ------------------------------------- | | `SCOPE_GROUPS_REQUIRED` | Inclua **`whatsapp:groups`** na chave | | `WHATSAPP_GROUPS_UNOFFICIAL_ONLY` | Use instância **não oficial** | | `loading: true` na listagem | Aguarde e chame de novo | Catálogo completo: [Respostas de erro](/guides/conceitos/resposta-de-erros). Confira se a instância é **não oficial** e se a chave tem escopo **`whatsapp:groups`**. Verifique se o número da instância é **admin** do grupo no app WhatsApp. *** ## Próximos passos * [Modos de conexão](/whatsapp-api/como-funciona/modos-de-conexao): oficial × não oficial * [WhatsApp, Introdução](/whatsapp-api/como-funciona/introducao): instância, mensagens e webhooks * [Escopos da API Key](/whatsapp-api/como-funciona/escopos-api-key)