# Listar grupos sincronizados

`GET /group/list`

Contrato implementado; homologação real de grupos pendente. force=true consulta WhatsApp; noparticipants=true omite Participants.

## Autenticação

Header obrigatório: `token`. Use o token da instância.

Base URL: a API do servidor selecionado, como `https://1.atendro.cloud`. O domínio `wpp.atendro.cloud` hospeda a documentação e o console.

## Parâmetros de consulta

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `force` | `boolean` | opcional | Padrão: `false` |
| `noparticipants` | `boolean` | opcional | Padrão: `false` |

## Headers adicionais

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `X-Request-Id` | `string` | opcional | ASCII visível sem espaços, 1–128 caracteres. Inválido/ausente é substituído por UUID. Ecoado na resposta. Comprimento máximo: `128` |

## Corpo da requisição

Não há corpo de requisição definido para esta operação.

## Resposta 200

Listar grupos sincronizados

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `groups` | `array<object>` | obrigatório | — |
| `groups[].JID` | `string` | obrigatório | — |
| `groups[].Name` | `string` | obrigatório | — |
| `groups[].Topic` | `string` | opcional | — |
| `groups[].OwnerJID` | `string` | opcional | — |
| `groups[].OwnerPN` | `string` | opcional | — |
| `groups[].IsLocked` | `boolean` | opcional | — |
| `groups[].IsAnnounce` | `boolean` | opcional | — |
| `groups[].AddressingMode` | `string` | opcional | — |
| `groups[].ParticipantCount` | `integer` | obrigatório | — |
| `groups[].Participants` | `array<object>` | opcional | — |
| `groups[].Participants[].JID` | `string` | obrigatório | — |
| `groups[].Participants[].PhoneNumber` | `string` | opcional | — |
| `groups[].Participants[].LID` | `string` | opcional | — |
| `groups[].Participants[].IsAdmin` | `boolean` | obrigatório | — |
| `groups[].Participants[].IsSuperAdmin` | `boolean` | obrigatório | — |
| `groups[].Participants[].DisplayName` | `string` | obrigatório | — |
| `groups[].Participants[].Error` | `integer` | obrigatório | Código por participante; 0 indica ausência de erro registrado. |
| `groups[].invite_link` | `string` | obrigatório | Vazio se não solicitado ou sem permissão de admin. |
| `groups[].PictureID` | `string` | opcional | — |
| `groups[].lastMessageAt` | `integer` | opcional | Unix em segundos. Formato: `int64` |
| `groups[].syncedAt` | `integer` | opcional | Unix em segundos. Formato: `int64` |
| `groups[].left` | `boolean` | opcional | — |
| `groups[].GroupCreated` | `string` | opcional | RFC 3339. Formato: `date-time` |

Exemplo ilustrativo, com valores sintéticos:

```json
{
  "groups": []
}
```

## Resposta 400

Grupo, participantes, nome ou imagem inválidos.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

## Resposta 401

unauthorized: header ausente, inválido ou duplicado. Bearer/query/instancekey não substituem admintoken/token.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

Exemplo ilustrativo, com valores sintéticos:

```json
{
  "error": "unauthorized"
}
```

## Resposta 403

not_in_group ou not_admin.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

## Resposta 404

group_not_found.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

## Resposta 409

Sessão desconectada/ocupada.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

## Resposta 429

rate_limited, Retry-After=30.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

## Resposta 502

storage_unavailable (Retry-After=5). Algumas rotas também retornam 502 por falha da conexão/mídia; consultar error.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

Exemplo ilustrativo, com valores sintéticos:

```json
{
  "error": "storage_unavailable"
}
```

## Resposta default

Falha; usar HTTP status e error. 404 rota inexistente; 405 método inválido com Allow. Ver catálogo no guia de integração.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

## Exemplos de requisição

Defina as variáveis no ambiente privado e substitua os dados sintéticos antes de usar. Os exemplos não executam operações nesta página.

### cURL

```sh
curl --request GET "$ATENDROZAP_URL/group/list" \
  --header "token: $ATENDROZAP_INSTANCE_TOKEN"
```

### JavaScript

```javascript
const baseUrl = process.env.ATENDROZAP_URL;
let path = "/group/list";
const url = new URL(path, baseUrl);

const response = await fetch(url, {
  method: "GET",
  headers: {
    "token": process.env.ATENDROZAP_INSTANCE_TOKEN
  },
});

if (!response.ok) {
  throw new Error(`AtendroZAP: HTTP ${response.status}`);
}
const result = await response.json();
```

## Relacionados

- [Grupos](https://wpp.atendro.cloud/docs/api/grupos.md)
- [Autenticação](https://wpp.atendro.cloud/docs/guias/autenticacao.md)
- [Erros e idempotência](https://wpp.atendro.cloud/docs/guias/erros-e-idempotencia.md)