# Zapini API — Chat API

**Versão:** 1.2.0
**Base URL:** `https://zapini.app/api/v1`

---

## Autenticação

Todos os endpoints requerem um Bearer Token:

```
Authorization: Bearer {your_token}
Accept: application/json
Content-Type: application/json
```

Gere tokens de API no painel admin em **API Docs → Gerenciar Tokens**.

---

## Chat API (Otimizada para UI)

A Chat API fornece endpoints otimizados para construir interfaces de chat semelhantes ao WhatsApp. Retorna dados pré-formatados com @menções resolvidas, reações agrupadas e auxiliares de alinhamento.

**Base URL:** `/api/v1/chat`

### Principais Recursos

| Campo | Descrição |
|-------|-----------|
| `formatted_body` | Texto da mensagem com @menções resolvidas para nomes (HTML) |
| `is_from_me` | Booleano para fácil alinhamento de mensagens |
| `grouped_reactions` | Reações agrupadas por emoji com contagens |
| `mentioned_jids` | Array de JIDs mencionados no WhatsApp |
| `tags` | Tags da conversa incluídas |

---

### GET /chat/conversations

Listar conversas otimizadas para interface de chat.

**Parâmetros de Consulta:**

| Campo | Tipo | Descrição |
|-------|------|-----------|
| instance_id | string | Filtrar por UUID da instância |
| search | string | Pesquisar por nome ou número |
| unread | boolean | Apenas conversas não lidas |
| per_page | integer | Itens por página |

**Resposta:**

```json
{
  "success": true,
  "data": {
    "data": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440045",
        "contact_number": "5521999999999",
        "display_name": "John Doe",
        "profile_picture_url": "https://...",
        "last_message": "Hello!",
        "unread_count": 3,
        "tags": [{"id": "550e8400-e29b-41d4-a716-446655440001", "name": "VIP", "color": "#f59e0b"}],
        "instance": {"uuid": "abc-123", "status": "connected"}
      }
    ]
  }
}
```

---

### GET /chat/conversations/{uuid}/messages

Obter mensagens com corpo formatado e reações agrupadas.

**Parâmetros de Consulta:**

| Campo | Tipo | Descrição |
|-------|------|-----------|
| before_id | integer | Mensagens antes deste ID |
| after_id | integer | Mensagens após este ID |
| limit | integer | Limite de mensagens (padrão: 50) |

**Resposta:**

```json
{
  "success": true,
  "data": {
    "messages": [
      {
        "id": 456,
        "direction": "incoming",
        "is_from_me": false,
        "message_body": "Hello @5521999999999!",
        "formatted_body": "Hello <span class=\"mention\">@John</span>!",
        "mentioned_jids": ["5521999999999@s.whatsapp.net"],
        "grouped_reactions": [
          {"emoji": "👍", "count": 2, "has_my_reaction": true}
        ]
      }
    ],
    "has_more": true
  }
}
```

---

### POST /chat/send

Enviar mensagem de texto com resposta otimizada para chat.

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| instance_id | string | Sim | UUID da instância |
| recipient | string | Sim | Número do destinatário |
| message | string | Sim | Conteúdo da mensagem |
| reply_to | string | Não | UUID da mensagem para responder |

---

### POST /chat/send-media

Enviar mídia com resposta otimizada para chat.

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| instance_id | string | Sim | UUID da instância |
| recipient | string | Sim | Número do destinatário |
| media_url | string | Sim | URL do arquivo de mídia |
| media_type | string | Sim | Tipo (image, video, audio, document) |
| caption | string | Não | Legenda |

---

### PATCH /chat/messages/{uuid}

Editar uma mensagem enviada.

---

### DELETE /chat/messages/{uuid}

Excluir uma mensagem enviada.

---

### POST /chat/messages/{uuid}/reaction

Adicionar reação emoji.

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| emoji | string | Sim | Emoji para reagir |

---

### DELETE /chat/messages/{uuid}/reaction

Remover reação.

---

### POST /chat/conversations/{uuid}/mark-read

Marcar conversa como lida.

---

### POST /chat/conversations/{uuid}/archive

Arquivar conversa.

---

### Alternativa: ?format=chat

Use endpoints padrão com o parâmetro `?format=chat`:

```bash
GET /api/v1/conversations?format=chat
GET /api/v1/conversations/550e8400-e29b-41d4-a716-446655440045/messages?format=chat
```

---

*Gerado por Zapini — https://zapini.app*