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

# Grupos

> Crie, gerencie e interaja com grupos do WhatsApp programaticamente.

# Grupos

Gerencie grupos do WhatsApp através da API da Wappfy. Você pode criar grupos, gerenciar participantes, lidar com links de convite e mais.

Todos os endpoints de grupo são vinculados a uma instância específica:

```
/api/instances/{instanceId}/groups/...
```

***

## Criar um Grupo

Crie um novo grupo do WhatsApp com participantes iniciais.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances/inst_abc123/groups \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Projeto Alpha",
      "participants": [
        "5511999998888@s.whatsapp.net",
        "5511888887777@s.whatsapp.net"
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/groups",
    {
      method: "POST",
      headers: {
        "X-Api-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Projeto Alpha",
        participants: [
          "5511999998888@s.whatsapp.net",
          "5511888887777@s.whatsapp.net",
        ],
      }),
    }
  );

  const group = await response.json();
  console.log(group.data.group_id);
  ```
</CodeGroup>

**Resposta:**

```json theme={null}
{
  "data": {
    "group_id": "120363012345678901@g.us",
    "name": "Projeto Alpha",
    "participants": [
      {
        "id": "5511999998888@s.whatsapp.net",
        "is_admin": false
      },
      {
        "id": "5511888887777@s.whatsapp.net",
        "is_admin": false
      }
    ]
  }
}
```

***

## Listar Grupos

Recupere todos os grupos dos quais a instância é membro.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.wappfy.io/api/instances/inst_abc123/groups \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/groups",
    {
      headers: { "X-Api-Key": "YOUR_API_KEY" },
    }
  );

  const { data } = await response.json();
  console.log(`Encontrados ${data.length} grupos`);
  ```
</CodeGroup>

***

## Informações do Grupo

Busque informações detalhadas sobre um grupo específico.

```bash theme={null}
curl https://api.wappfy.io/api/instances/inst_abc123/groups/120363012345678901@g.us \
  -H "X-Api-Key: YOUR_API_KEY"
```

***

## Atualizar um Grupo

Atualize o nome ou descrição do grupo. Você deve ser admin do grupo.

```bash theme={null}
curl -X PATCH https://api.wappfy.io/api/instances/inst_abc123/groups/120363012345678901@g.us \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Projeto Alpha v2",
    "description": "Workspace atualizado do Projeto Alpha"
  }'
```

<Note>
  Apenas admins do grupo podem atualizar o nome e descrição. Se a instância não for admin, retornará erro `403`.
</Note>

***

## Sair de um Grupo

Remova a instância de um grupo.

```bash theme={null}
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/groups/120363012345678901@g.us/leave \
  -H "X-Api-Key: YOUR_API_KEY"
```

<Warning>
  Após sair de um grupo, você precisará de um link de convite ou que outro admin te adicione novamente.
</Warning>

***

## Participantes

### Listar Participantes

Obtenha todos os participantes de um grupo.

```bash theme={null}
curl https://api.wappfy.io/api/instances/inst_abc123/groups/120363012345678901@g.us/participants \
  -H "X-Api-Key: YOUR_API_KEY"
```

### Adicionar Participantes

Adicione um ou mais participantes a um grupo. Você deve ser admin do grupo.

```bash theme={null}
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/groups/120363012345678901@g.us/participants \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participants": [
      "5511666665555@s.whatsapp.net",
      "5511555554444@s.whatsapp.net"
    ]
  }'
```

### Remover Participantes

Remova um ou mais participantes de um grupo. Você deve ser admin do grupo.

```bash theme={null}
curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123/groups/120363012345678901@g.us/participants \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participants": [
      "5511666665555@s.whatsapp.net"
    ]
  }'
```

***

## Códigos de Convite

### Obter Código de Convite

Gere ou recupere o link de convite do grupo. Você deve ser admin do grupo.

```bash theme={null}
curl https://api.wappfy.io/api/instances/inst_abc123/groups/120363012345678901@g.us/invite-code \
  -H "X-Api-Key: YOUR_API_KEY"
```

**Resposta:**

```json theme={null}
{
  "data": {
    "invite_code": "https://chat.whatsapp.com/AbCdEfGhIjKlMn"
  }
}
```

### Entrar via Código de Convite

Entre em um grupo usando um código de convite.

```bash theme={null}
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/groups/join \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invite_code": "AbCdEfGhIjKlMn"
  }'
```

<Note>
  Passe apenas o código, não a URL completa. Para `https://chat.whatsapp.com/AbCdEfGhIjKlMn`, passe `AbCdEfGhIjKlMn`.
</Note>

***

## Enviando Mensagens para Grupos

Para enviar uma mensagem a um grupo, use o endpoint padrão de [envio de mensagens](/pt-BR/guides/sending-messages) com o chat ID do grupo:

```bash theme={null}
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "120363012345678901@g.us",
    "type": "text",
    "text": "Olá equipe!"
  }'
```

IDs de chat de grupo sempre terminam com `@g.us`.

***

## Referência de Endpoints

| Método   | Endpoint                                            | Descrição                    |
| -------- | --------------------------------------------------- | ---------------------------- |
| `POST`   | `/api/instances/{id}/groups`                        | Criar um novo grupo          |
| `GET`    | `/api/instances/{id}/groups`                        | Listar todos os grupos       |
| `GET`    | `/api/instances/{id}/groups/{groupId}`              | Informações do grupo         |
| `PATCH`  | `/api/instances/{id}/groups/{groupId}`              | Atualizar nome/descrição     |
| `POST`   | `/api/instances/{id}/groups/{groupId}/leave`        | Sair de um grupo             |
| `GET`    | `/api/instances/{id}/groups/{groupId}/participants` | Listar participantes         |
| `POST`   | `/api/instances/{id}/groups/{groupId}/participants` | Adicionar participantes      |
| `DELETE` | `/api/instances/{id}/groups/{groupId}/participants` | Remover participantes        |
| `GET`    | `/api/instances/{id}/groups/{groupId}/invite-code`  | Obter código de convite      |
| `POST`   | `/api/instances/{id}/groups/join`                   | Entrar via código de convite |

***

## Tratamento de Erros

| Código | Descrição                                                                       |
| ------ | ------------------------------------------------------------------------------- |
| `403`  | Você não é admin deste grupo.                                                   |
| `404`  | Grupo não encontrado ou instância não é membro.                                 |
| `409`  | Participante já está no grupo (ao adicionar) ou não está no grupo (ao remover). |
| `422`  | Formato de participante inválido. Use `{telefone}@s.whatsapp.net`.              |