> ## 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 comunidades (parent groups) via /api/community/*

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

Comunidades são "parent groups" do WhatsApp que agrupam outros grupos como subgrupos. Esta seção cobre as rotas `/api/community/*` para criar, vincular, desvincular e listar subgrupos. Para grupos comuns, veja [Grupos](/pt/api/groups/overview).

## Endpoints

| Método | Path                                     | Função                                                   |
| ------ | ---------------------------------------- | -------------------------------------------------------- |
| POST   | `/api/community/create/:instance`        | [Criar comunidade](/pt/api/communities/create)           |
| POST   | `/api/community/link/:instance`          | [Vincular grupos a comunidade](/pt/api/communities/link) |
| POST   | `/api/community/unlink/:instance`        | [Desvincular grupos](/pt/api/communities/unlink)         |
| GET    | `/api/community/listSubGroups/:instance` | [Listar subgrupos](/pt/api/communities/list-subgroups)   |

## Como funciona

Uma comunidade no WhatsApp é composta por:

* **Grupo-pai** (a comunidade em si), onde você gerencia tudo
* **Grupo de Anúncios**, criado automaticamente. Apenas admins postam, mas todos os membros de subgrupos recebem
* **Subgrupos**, grupos comuns vinculados à comunidade

<Note>
  Cada grupo pertence a **no máximo uma comunidade** por vez. Para mover um grupo de uma comunidade para outra, desvincule primeiro e depois vincule no destino.
</Note>

## Identifiers

* A maioria das rotas espera **JIDs `@g.us`** em `communityJid` e `groupJid`.
* `GET /listSubGroups` exige `?communityJid=` na query string.

## Modelos de resposta

### Resposta de `/create`

```json theme={null}
{
  "success": true,
  "message": "Community created successfully",
  "linkedGroups": ["120363406289005074@g.us"],
  "failedGroups": [],
  "imageError": null,
  "group": {
    "name": "Comunidade Alpha",
    "jid": "120363406289005073@g.us",
    "isCommunity": true,
    "isParent": true,
    "linkedParentJid": null
  }
}
```

### Resposta de `/link` e `/unlink`

```json theme={null}
{
  "success": true,
  "message": "Linked 2 of 2 groups to community",
  "linked": ["120363406289005074@g.us", "120363406289005075@g.us"],
  "failed": []
}
```

<Warning>
  No endpoint de `/unlink`, o campo se chama `linked` mas contém os JIDs **desvinculados** com sucesso (DTO compartilhado). Use a `message` (`"Unlinked N of M ..."`) para desambiguar.
</Warning>

### Resposta de `/listSubGroups`

```json theme={null}
{
  "success": true,
  "message": "2 subgroup(s) found",
  "communityJid": "120363406289005073@g.us",
  "subgroups": [
    { "jid": "120363406289005074@g.us", "name": "Anúncios", "isDefaultSubGroup": true },
    { "jid": "120363406289005075@g.us", "name": "Geral", "isDefaultSubGroup": false }
  ]
}
```

`isDefaultSubGroup=true` indica o **Grupo de Anúncios** padrão da comunidade.

## Envelope de erro

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

## Próximo

<CardGroup cols={2}>
  <Card title="Criar comunidade" icon="building" href="/pt/api/communities/create">
    Cria o grupo-pai e vincula subgrupos iniciais.
  </Card>

  <Card title="Listar subgrupos" icon="list" href="/pt/api/communities/list-subgroups">
    Retorna os grupos vinculados.
  </Card>
</CardGroup>