# Oratrix API - Gerenciamento de Grupos

## Status

Documentacao parcial baseada na parte enviada para o projeto Wezapp Shots.

Este grupo trata recursos de administracao de grupos WhatsApp via Oratrix. Para a primeira versao do Wezapp Shots, e um recurso auxiliar/futuro. O fluxo principal do Shots permanece focado em campanhas, bases, shots, chipeira digital e disparos.

## Base URL

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}
```

## Autenticacao

```http
Authorization: Bearer {token}
```

## Endpoints do grupo

Total documentado nesta parte: 13 endpoints.

---

## 1. Listar grupos da sessao

```http
POST /group/list
```

Nome na documentacao Oratrix:

```text
GroupList
```

Descricao:

Listar grupos do WhatsApp da sessao.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/group/list
```

Body JSON:

```json
{
  "whatsappId": 1
}
```

---

## 2. Buscar grupo por ID

```http
POST /group/showById
```

Nome na documentacao Oratrix:

```text
GroupShowById
```

Descricao:

Buscar informacoes de um grupo pelo ID.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/group/showById
```

Body JSON:

```json
{
  "whatsappId": 1,
  "groupId": "12345678901@g.us"
}
```

---

## 3. Criar grupo

```http
POST /group/create
```

Nome na documentacao Oratrix:

```text
GroupCreate
```

Descricao:

Criar um novo grupo no WhatsApp.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/group/create
```

Body JSON:

```json
{
  "whatsappId": 1,
  "name": "Grupo de Suporte",
  "participants": [
    "5511999999999",
    "5511888888888"
  ]
}
```

---

## 4. Listar participantes de grupo

```http
POST /group/listParticipants
```

Nome na documentacao Oratrix:

```text
GroupListParticipants
```

Descricao:

Listar participantes de um grupo.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/group/listParticipants
```

Body JSON:

```json
{
  "whatsappId": 1,
  "groupId": "12345678901@g.us"
}
```

---

## 5. Adicionar participantes

```http
POST /group/addParticipant
```

Nome na documentacao Oratrix:

```text
GroupAddParticipant
```

Descricao:

Adicionar participante(s) a um grupo.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/group/addParticipant
```

Body JSON:

```json
{
  "whatsappId": 1,
  "groupId": "12345678901@g.us",
  "participants": [
    "5511777777777"
  ]
}
```

---

## 6. Remover participantes

```http
POST /group/removeParticipant
```

Nome na documentacao Oratrix:

```text
GroupRemoveParticipant
```

Descricao:

Remover participante(s) de um grupo.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/group/removeParticipant
```

Body JSON:

```json
{
  "whatsappId": 1,
  "groupId": "12345678901@g.us",
  "participants": [
    "5511777777777"
  ]
}
```

---

## 7. Promover participantes a administrador

```http
POST /group/promote
```

Nome na documentacao Oratrix:

```text
GroupPromote
```

Descricao:

Promover participante(s) a administrador do grupo.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/group/promote
```

Body JSON:

```json
{
  "whatsappId": 1,
  "groupId": "12345678901@g.us",
  "participants": [
    "5511777777777"
  ]
}
```

---

## 8. Rebaixar administradores

```http
POST /group/demote
```

Nome na documentacao Oratrix:

```text
GroupDemote
```

Descricao:

Rebaixar administrador(es) a participante comum.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/group/demote
```

Body JSON:

```json
{
  "whatsappId": 1,
  "groupId": "12345678901@g.us",
  "participants": [
    "5511777777777"
  ]
}
```

---

## 9. Alterar titulo do grupo

```http
POST /group/changeTitle
```

Nome na documentacao Oratrix:

```text
GroupChangeTitle
```

Descricao:

Alterar o nome/titulo de um grupo.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/group/changeTitle
```

Body JSON:

```json
{
  "whatsappId": 1,
  "groupId": "12345678901@g.us",
  "title": "Novo Nome do Grupo"
}
```

---

## 10. Alterar descricao do grupo

```http
POST /group/changeDescription
```

Nome na documentacao Oratrix:

```text
GroupChangeDescription
```

Descricao:

Alterar a descricao de um grupo.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/group/changeDescription
```

Body JSON:

```json
{
  "whatsappId": 1,
  "groupId": "12345678901@g.us",
  "description": "Nova descricao do grupo"
}
```

---

## 11. Configurar envio apenas por admins

```http
POST /group/setAdminsOnly
```

Nome na documentacao Oratrix:

```text
GroupSetAdminsOnly
```

Descricao:

Configurar se apenas administradores podem enviar mensagens.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/group/setAdminsOnly
```

Body JSON:

```json
{
  "whatsappId": 1,
  "groupId": "12345678901@g.us",
  "adminsOnly": true
}
```

---

## 12. Obter link de convite

```http
POST /group/getInviteLink
```

Nome na documentacao Oratrix:

```text
GroupGetInviteLink
```

Descricao:

Obter o link de convite de um grupo.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/group/getInviteLink
```

Body JSON:

```json
{
  "whatsappId": 1,
  "groupId": "12345678901@g.us"
}
```

Observacao para Wezapp Shots:

Link de convite deve ser tratado como informacao sensivel, pois pode permitir entrada no grupo.

---

## 13. Alterar foto do grupo

```http
POST /group/changePicture
```

Nome na documentacao Oratrix:

```text
GroupChangePicture
```

Descricao:

Alterar a foto de perfil de um grupo.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/group/changePicture
```

Body:

```text
multipart/form-data
```

Campos:

| Campo | Tipo | Obrigatorio | Descricao |
|---|---|---:|---|
| picture | file | Sim | Arquivo de imagem |
| whatsappId | ID | Sim | ID da sessao |
| groupId | string | Sim | ID do grupo, exemplo `12345678901@g.us` |

## Mapeamento sugerido com Wezapp Shots

| Wezapp Shots | Oratrix |
|---|---|
| Chipeira digital / canal | `whatsappId` |
| Grupo externo futuro | `groupId` |
| Campanha futura para grupos | Participantes e link de convite |
| Auditoria interna | Acoes administrativas em grupo |

## Pendencias tecnicas para validar

- Confirmar formato de retorno de `/group/list`.
- Confirmar se `groupId` sempre usa sufixo `@g.us`.
- Confirmar limite de participantes ao criar grupo.
- Confirmar limite de participantes por chamada em adicionar/remover/promover/rebaixar.
- Confirmar permissoes necessarias na sessao WhatsApp para alterar grupo.
- Confirmar comportamento quando o numero da sessao nao e administrador do grupo.
- Confirmar formato e validade do link de convite retornado.
- Confirmar formatos aceitos em `picture`.

## Regras recomendadas para o Wezapp Shots

1. Nao usar estes endpoints no fluxo inicial de disparo individual em massa.
2. Proteger acoes administrativas de grupo por permissao alta.
3. Registrar auditoria em criar grupo, adicionar/remover participante, promover/rebaixar admin, alterar titulo, alterar descricao, alterar foto e obter link.
4. Tratar link de convite como dado sensivel.
5. Nao misturar membros de grupos com base principal de contatos sem importacao e consentimento operacional definidos.