> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wapizap.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Gerenciando Grupos

> Aprenda a criar, configurar e gerenciar grupos WhatsApp via API

# Gerenciando Grupos

Este guia mostra como criar e gerenciar grupos WhatsApp usando a Wapizap API.

## Pré-requisitos

* Instância conectada
* API Key configurada
* Permissões de administrador (para algumas operações)

***

## Criar um Grupo

Crie um novo grupo com participantes iniciais.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wapizap.com/api/v2/groups \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer SEU_TOKEN" \
    -d '{
      "instanceId": "sua-instancia",
      "subject": "Equipe de Vendas",
      "participants": [
        "5511999999999",
        "5511888888888"
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.wapizap.com/api/v2/groups', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer SEU_TOKEN'
    },
    body: JSON.stringify({
      instanceId: 'sua-instancia',
      subject: 'Equipe de Vendas',
      participants: [
        '5511999999999',
        '5511888888888'
      ]
    })
  });

  const group = await response.json();
  console.log('Grupo criado:', group.data.id);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.wapizap.com/api/v2/groups',
      headers={
          'Content-Type': 'application/json',
          'Authorization': 'Bearer SEU_TOKEN'
      },
      json={
          'instanceId': 'sua-instancia',
          'subject': 'Equipe de Vendas',
          'participants': [
              '5511999999999',
              '5511888888888'
          ]
      }
  )

  group = response.json()
  print('Grupo criado:', group['data']['id'])
  ```
</CodeGroup>

### Resposta

```json theme={null}
{
  "success": true,
  "data": {
    "id": "120363123456789012@g.us",
    "subject": "Equipe de Vendas",
    "owner": "5511777777777@s.whatsapp.net",
    "creation": 1705233000,
    "participants": [
      {
        "id": "5511999999999@s.whatsapp.net",
        "isAdmin": false
      },
      {
        "id": "5511888888888@s.whatsapp.net",
        "isAdmin": false
      }
    ]
  }
}
```

<Info>
  O ID do grupo sempre termina com `@g.us`. Guarde este ID para operações futuras.
</Info>

***

## Listar Grupos

Obtenha todos os grupos da instância.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.wapizap.com/api/v2/groups?instanceId=sua-instancia" \
    -H "Authorization: Bearer SEU_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.wapizap.com/api/v2/groups?instanceId=sua-instancia',
    {
      headers: {
        'Authorization': 'Bearer SEU_TOKEN'
      }
    }
  );

  const groups = await response.json();
  console.log('Total de grupos:', groups.data.length);
  ```
</CodeGroup>

***

## Obter Informações do Grupo

Detalhes completos de um grupo específico.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.wapizap.com/api/v2/groups/120363123456789012@g.us?instanceId=sua-instancia" \
    -H "Authorization: Bearer SEU_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const groupId = '120363123456789012@g.us';
  const response = await fetch(
    `https://api.wapizap.com/api/v2/groups/${groupId}?instanceId=sua-instancia`,
    {
      headers: {
        'Authorization': 'Bearer SEU_TOKEN'
      }
    }
  );

  const group = await response.json();
  console.log('Participantes:', group.data.participants.length);
  ```
</CodeGroup>

***

## Atualizar Grupo

### Alterar Nome do Grupo

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.wapizap.com/api/v2/groups/120363123456789012@g.us" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer SEU_TOKEN" \
    -d '{
      "instanceId": "sua-instancia",
      "subject": "Equipe de Vendas 2026"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.wapizap.com/api/v2/groups/120363123456789012@g.us',
    {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN'
      },
      body: JSON.stringify({
        instanceId: 'sua-instancia',
        subject: 'Equipe de Vendas 2026'
      })
    }
  );
  ```
</CodeGroup>

### Alterar Descrição

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.wapizap.com/api/v2/groups/120363123456789012@g.us" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer SEU_TOKEN" \
    -d '{
      "instanceId": "sua-instancia",
      "description": "Grupo oficial da equipe de vendas. Regras: respeito mútuo."
    }'
  ```
</CodeGroup>

***

## Gerenciar Participantes

### Adicionar Participantes

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.wapizap.com/api/v2/groups/120363123456789012@g.us/participants" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer SEU_TOKEN" \
    -d '{
      "instanceId": "sua-instancia",
      "action": "add",
      "participants": ["5511777777777"]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.wapizap.com/api/v2/groups/120363123456789012@g.us/participants',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN'
      },
      body: JSON.stringify({
        instanceId: 'sua-instancia',
        action: 'add',
        participants: ['5511777777777']
      })
    }
  );
  ```
</CodeGroup>

### Remover Participantes

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.wapizap.com/api/v2/groups/120363123456789012@g.us/participants" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer SEU_TOKEN" \
    -d '{
      "instanceId": "sua-instancia",
      "action": "remove",
      "participants": ["5511777777777"]
    }'
  ```
</CodeGroup>

### Promover a Administrador

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.wapizap.com/api/v2/groups/120363123456789012@g.us/participants" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer SEU_TOKEN" \
    -d '{
      "instanceId": "sua-instancia",
      "action": "promote",
      "participants": ["5511999999999"]
    }'
  ```
</CodeGroup>

### Rebaixar de Administrador

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.wapizap.com/api/v2/groups/120363123456789012@g.us/participants" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer SEU_TOKEN" \
    -d '{
      "instanceId": "sua-instancia",
      "action": "demote",
      "participants": ["5511999999999"]
    }'
  ```
</CodeGroup>

***

## Configurações do Grupo

### Restringir Mensagens (Somente Admins)

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.wapizap.com/api/v2/groups/120363123456789012@g.us/settings" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer SEU_TOKEN" \
    -d '{
      "instanceId": "sua-instancia",
      "announce": true
    }'
  ```

  ```javascript JavaScript theme={null}
  // announce: true = somente admins podem enviar mensagens
  // announce: false = todos podem enviar mensagens

  const response = await fetch(
    'https://api.wapizap.com/api/v2/groups/120363123456789012@g.us/settings',
    {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN'
      },
      body: JSON.stringify({
        instanceId: 'sua-instancia',
        announce: true
      })
    }
  );
  ```
</CodeGroup>

### Restringir Edição de Info (Somente Admins)

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.wapizap.com/api/v2/groups/120363123456789012@g.us/settings" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer SEU_TOKEN" \
    -d '{
      "instanceId": "sua-instancia",
      "locked": true
    }'
  ```
</CodeGroup>

### Mensagens Temporárias

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.wapizap.com/api/v2/groups/120363123456789012@g.us/settings" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer SEU_TOKEN" \
    -d '{
      "instanceId": "sua-instancia",
      "ephemeral": 86400
    }'
  ```
</CodeGroup>

| Valor `ephemeral` | Duração    |
| ----------------- | ---------- |
| `0`               | Desativado |
| `86400`           | 24 horas   |
| `604800`          | 7 dias     |
| `7776000`         | 90 dias    |

***

## Link de Convite

### Obter Link de Convite

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.wapizap.com/api/v2/groups/120363123456789012@g.us/invite-info?instanceId=sua-instancia" \
    -H "Authorization: Bearer SEU_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.wapizap.com/api/v2/groups/120363123456789012@g.us/invite-info?instanceId=sua-instancia',
    {
      headers: {
        'Authorization': 'Bearer SEU_TOKEN'
      }
    }
  );

  const invite = await response.json();
  console.log('Link:', invite.data.inviteUrl);
  // https://chat.whatsapp.com/AbCdEfGhIjK
  ```
</CodeGroup>

### Entrar via Link de Convite

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.wapizap.com/api/v2/groups/join" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer SEU_TOKEN" \
    -d '{
      "instanceId": "sua-instancia",
      "inviteCode": "AbCdEfGhIjK"
    }'
  ```
</CodeGroup>

<Warning>
  O `inviteCode` é apenas a parte final do link, não a URL completa.
</Warning>

***

## Sair do Grupo

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.wapizap.com/api/v2/groups/120363123456789012@g.us?instanceId=sua-instancia" \
    -H "Authorization: Bearer SEU_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.wapizap.com/api/v2/groups/120363123456789012@g.us?instanceId=sua-instancia',
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'Bearer SEU_TOKEN'
      }
    }
  );
  ```
</CodeGroup>

<Warning>
  Essa ação é irreversível. Você só poderá voltar ao grupo se for convidado novamente.
</Warning>

***

## Enviar Mensagem para o Grupo

Use o ID do grupo no campo `to`:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wapizap.com/api/v2/messages \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer SEU_TOKEN" \
    -d '{
      "instanceId": "sua-instancia",
      "to": "120363123456789012@g.us",
      "type": "text",
      "text": "Olá equipe! Reunião às 15h."
    }'
  ```
</CodeGroup>

***

## Melhores Práticas

<CardGroup cols={2}>
  <Card title="Permissões" icon="shield">
    Você precisa ser admin do grupo para adicionar/remover participantes e alterar configurações.
  </Card>

  <Card title="Rate Limits" icon="gauge">
    Adicione no máximo 5 participantes por requisição para evitar bloqueios.
  </Card>

  <Card title="Validação" icon="check">
    Valide os números antes de adicionar ao grupo usando `/contacts/check`.
  </Card>

  <Card title="ID do Grupo" icon="fingerprint">
    Sempre use o ID completo com `@g.us` (ex: `120363123456789012@g.us`).
  </Card>
</CardGroup>

***

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Enviar Mensagens" icon="message" href="/guides/sending-messages">
    Envie diferentes tipos de mensagens
  </Card>

  <Card title="Configurar Webhooks" icon="webhook" href="/guides/webhooks-setup">
    Receba notificações de eventos do grupo
  </Card>
</CardGroup>