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

# Visão Geral

> Criação e gestão de grupos do WhatsApp

**Auth:** `TokenAccount` ou `TokenInstance` em todas as rotas. Cada chamada valida a ownership da instância.

Esta seção cobre todas as rotas `/api/group/*`, criação, listagem, detalhes, gerenciamento de participantes, atualização de metadados, reset de link de convite, entrada e saída. Para comunidades (grupos pais), veja [Comunidades](/pt/api/communities/overview).

## Endpoints

| Método | Path                                | Função                                                                            |
| ------ | ----------------------------------- | --------------------------------------------------------------------------------- |
| POST   | `/api/group/create/:instance`       | [Criar grupo](/pt/api/groups/create)                                              |
| GET    | `/api/group/list/:instance`         | [Listar grupos](/pt/api/groups/list)                                              |
| GET    | `/api/group/info/:instance`         | [Detalhes de um grupo](/pt/api/groups/info)                                       |
| PUT    | `/api/group/update/:instance`       | [Atualizar nome / descrição / foto / permissões](/pt/api/groups/update)           |
| POST   | `/api/group/participants/:instance` | [Add / remove / promote / demote / approve / reject](/pt/api/groups/participants) |
| POST   | `/api/group/join/:instance`         | [Entrar via código / link](/pt/api/groups/join)                                   |
| POST   | `/api/group/resetLink/:instance`    | [Revogar e gerar novo invite link](/pt/api/groups/reset-link)                     |
| GET    | `/api/group/requests/:instance`     | [Listar solicitações pendentes](/pt/api/groups/requests)                          |
| DELETE | `/api/group/leave/:instance`        | [Sair do grupo](/pt/api/groups/leave)                                             |

## Identifiers aceitos

A maioria dos endpoints aceita um campo `identifier` que pode ser:

| Forma             | Exemplo                               |
| ----------------- | ------------------------------------- |
| JID do grupo      | `120363406289005073@g.us`             |
| Código de convite | `ABC123XYZ`                           |
| Link completo     | `https://chat.whatsapp.com/ABC123XYZ` |

<Warning>
  **Exceções:**

  * `POST /api/group/join` aceita **apenas** código ou link (não aceita JID).
  * `GET /api/community/listSubGroups` exige JID em query `?communityJid=`.
</Warning>

## Estruturas de dados

### `GroupInfo`

Resposta padrão das rotas de criação e atualização.

```json theme={null}
{
  "name": "Time de Dev",
  "jid": "120363406289005073@g.us",
  "description": "Discussões técnicas",
  "inviteCode": "ABC123XYZ",
  "inviteLink": "https://chat.whatsapp.com/ABC123XYZ",
  "createdBy": "5511999999999@s.whatsapp.net",
  "participantCount": 3,
  "participants": [
    { "jid": "5511999999999@s.whatsapp.net", "isAdmin": true, "isSuperAdmin": false }
  ],
  "groupSettings": {
    "membersCanEditInfo": true,
    "membersCanSendMessages": true,
    "membersCanAddOthers": false,
    "requireAdminApproval": false
  },
  "isCommunity": false,
  "isParent": false,
  "linkedParentJid": null
}
```

### `GroupDetail`

Resposta de [`GET /info`](/pt/api/groups/info). Inclui campos extras além do `GroupInfo`: `image`, `createdAt`, `metadata` (autor da última alteração de nome / descrição), `isEphemeral`, `isIncognito`, `isSuspended`, `isDefaultSubGroup`.

### `GroupPermissions`

| Campo                    | Tipo | Significado WhatsApp         |
| ------------------------ | ---- | ---------------------------- |
| `membersCanEditInfo`     | bool | Inverso de `IsLocked`        |
| `membersCanSendMessages` | bool | Inverso de `IsAnnounce`      |
| `membersCanAddOthers`    | bool | `MemberAddMode == AllMember` |
| `requireAdminApproval`   | bool | `IsJoinApprovalRequired`     |

## Envelope de erro

Todas as rotas usam o envelope padrão da API:

```json theme={null}
{
  "success": false,
  "error": { "message": "Identifier is required" }
}
```

## Quadro de erros (resumo)

| Categoria  | Mensagem                                                                        |
| ---------- | ------------------------------------------------------------------------------- |
| Auth       | `Not authorized to view group requests (must be admin)`                         |
| Auth       | `Not authorized to perform this action (must be admin)`                         |
| Auth       | `Not authorized to update this group (must be admin)`                           |
| Auth       | `Not authorized to reset group invite link (must be admin)`                     |
| Auth       | `Not allowed to join this group`                                                |
| Auth       | `Not allowed to leave this group`                                               |
| Validação  | `Identifier is required`                                                        |
| Validação  | `At least one participant is required`                                          |
| Validação  | `Invalid action. Must be one of: add, remove, promote, demote, approve, reject` |
| Identifier | `failed to resolve group from identifier (not a valid JID, code, or link)`      |
| Identifier | `invalid group JID <jid>: <reason>`                                             |
| Identifier | `not a group JID`                                                               |
| Estado     | `Instance is not connected to WhatsApp`                                         |
| Estado     | `Group not found or you are not a member of this group`                         |
| Convite    | `Invite link has been revoked or expired`                                       |
| Convite    | `Invalid invite link or code`                                                   |
| Throttle   | `rate limit exceeded (429): wait before creating again`                         |

## Próximo

<CardGroup cols={2}>
  <Card title="Criar grupo" icon="users-rectangle" href="/pt/api/groups/create">
    Cria um grupo novo com participantes iniciais.
  </Card>

  <Card title="Listar grupos" icon="list" href="/pt/api/groups/list">
    Retorna todos os grupos da instância.
  </Card>
</CardGroup>