# Atendimentos

## Listar atendimentos

`GET /v1/c/{slug}/conversations` · Escopos: `conversations:read`

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |

### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Detalhes |
|---|---|---|---|
| `view` | um de `mine`, `team`, `queue`, `waiting_contact`, `snoozed`, `closed`, `mentions`, `all` | não | default `"mine"` |
| `limit` | integer | não | até 100; mínimo 1; default `50` |
| `before` | string (date-time) | não |  |
| `q` | string | não | até 200 caracteres |
| `tag` | string (uuid) | não |  |

### Exemplo de pedido

```bash
curl -X GET "https://api.donetalk.com/v1/c/demo/conversations" \
  -H "Authorization: Bearer $DONETALK_KEY"
```

### Resposta 200

```json
{
  "conversations": [
    {
      "id": "01a3c0de-7a11-7b22-8c33-9d44e55f6677",
      "status": "active",
      "handler": "human",
      "priority": "normal",
      "teamId": "01a0cb22-89c0-7e02-b96b-3f4731dde701",
      "assigneeId": "01a0cac1-4a6f-7646-b5f8-c1d19090016a",
      "unreadCount": 1,
      "lastMessageAt": "2026-10-23T13:05:52.000Z",
      "lastInboundAt": "2026-10-23T13:05:52.000Z",
      "sessionWindowEndsAt": "2026-10-24T13:05:52.000Z",
      "snoozedUntil": null,
      "sourceKind": "campaign",
      "createdAt": "2026-10-23T13:02:11.000Z",
      "tags": [
        {
          "id": "01a12150-3610-7c00-b680-188c2b4c7313",
          "name": {
            "pt-BR": "VIP",
            "en": "VIP",
            "es": "VIP"
          },
          "color": "#92400e"
        }
      ],
      "contact": {
        "id": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
        "name": "Ana Souza",
        "address": "5548999990001"
      },
      "channel": {
        "id": "01a0cccc-0000-7000-8000-000000000002",
        "name": "Captei"
      },
      "lastMessage": {
        "body": "Quero o cupom",
        "direction": "inbound",
        "type": "button",
        "status": "received"
      }
    }
  ]
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Abrir um atendimento por modelo

`POST /v1/c/{slug}/conversations` · Escopos: `messages:send_template`

Para um contato já cadastrado. `assigneeMemberId` escolhe quem atende; sem ele, o atendimento espera a resposta e entra na fila da equipe.

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |

### Corpo do pedido

| Campo | Tipo | Obrigatório | Detalhes |
|---|---|---|---|
| `contactId` | string (uuid) | sim |  |
| `channelId` | string (uuid) | não |  |
| `templateId` | string (uuid) | sim |  |
| `parameters` | object | não | default `{}` |
| `headerUploadId` | string (uuid) | não |  |
| `headerLink` | string (uri) | não | até 2000 caracteres |
| `teamId` | string (uuid) | não | null |
| `goal` | string | não | até 60 caracteres |
| `assigneeMemberId` | string (uuid) | não |  |

### Exemplo de pedido

```bash
curl -X POST "https://api.donetalk.com/v1/c/demo/conversations" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "contactId": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
  "templateId": "01a0cad0-0000-7000-8000-000000000002",
  "parameters": {
    "1": "Ana"
  }
}'
```

### Resposta 201

```json
{
  "conversation": {
    "id": "01a3c0de-7a11-7b22-8c33-9d44e55f6677"
  },
  "message": {
    "id": "01a3c0de-8b22-7c33-9d44-0e55f6677889"
  }
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `404` `contact_not_found`
- `409` `template_not_approved`
- `422` `validation_failed`
- `429` `rate_limited`

## Ver um atendimento

`GET /v1/c/{slug}/conversations/{id}` · Escopos: `conversations:read`

O atendimento com as mensagens, os eventos (atribuições, transferências) e, quando concluído, o desfecho.

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |
| `id` | O id do registro. |

### Exemplo de pedido

```bash
curl -X GET "https://api.donetalk.com/v1/c/demo/conversations/:id" \
  -H "Authorization: Bearer $DONETALK_KEY"
```

### Resposta 200

```json
{
  "conversation": {
    "id": "01a3c0de-7a11-7b22-8c33-9d44e55f6677",
    "status": "active",
    "handler": "human",
    "priority": "normal",
    "teamId": "01a0cb22-89c0-7e02-b96b-3f4731dde701",
    "assigneeId": "01a0cac1-4a6f-7646-b5f8-c1d19090016a",
    "unreadCount": 1,
    "lastMessageAt": "2026-10-23T13:05:52.000Z",
    "lastInboundAt": "2026-10-23T13:05:52.000Z",
    "sessionWindowEndsAt": "2026-10-24T13:05:52.000Z",
    "snoozedUntil": null,
    "sourceKind": "campaign",
    "createdAt": "2026-10-23T13:02:11.000Z",
    "tags": [
      {
        "id": "01a12150-3610-7c00-b680-188c2b4c7313",
        "name": {
          "pt-BR": "VIP",
          "en": "VIP",
          "es": "VIP"
        },
        "color": "#92400e"
      }
    ],
    "contact": {
      "id": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
      "name": "Ana Souza",
      "address": "5548999990001"
    },
    "channel": {
      "id": "01a0cccc-0000-7000-8000-000000000002",
      "name": "Captei"
    },
    "lastMessage": {
      "body": "Quero o cupom",
      "direction": "inbound",
      "type": "button",
      "status": "received"
    },
    "goal": null,
    "outcome": null,
    "closedAt": null
  },
  "messages": [
    {
      "id": "01a3c0de-8b22-7c33-9d44-0e55f6677889",
      "conversationId": "01a3c0de-7a11-7b22-8c33-9d44e55f6677",
      "direction": "outbound",
      "author": {
        "kind": "campaign",
        "id": "01a2b3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b"
      },
      "type": "template",
      "body": "Oi Ana! Seu cupom ANA10 vale até sexta. Quer usar agora?",
      "status": "read",
      "error": null,
      "campaignId": "01a2b3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b",
      "createdAt": "2026-10-23T13:02:11.000Z"
    }
  ],
  "pinned": [],
  "events": []
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Mandar uma mensagem no atendimento

`POST /v1/c/{slug}/conversations/{id}/messages` · Escopos: `messages:send_template` · `messages:send_text`

`type: template` com o escopo messages:send_template. `text` e `media` (arquivo de `POST /uploads`) pedem messages:send_text e a janela de 24 horas aberta.

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |
| `id` | O id do registro. |

### Corpo do pedido

| Campo | Tipo | Obrigatório | Detalhes |
|---|---|---|---|
| `type` | um de `text` | sim |  |
| `text` | string | sim | até 4096 caracteres |
| `replyToProviderMessageId` | string | não |  |
| `linkPreview` | boolean | não |  |
| `gateDecisionId` | string (uuid) | não |  |
| `gateAction` | um de `accepted`, `edited`, `overridden` | não |  |
| `templateId` | string (uuid) | sim |  |
| `parameters` | object | não | default `{}` |
| `headerUploadId` | string (uuid) | não |  |
| `headerLink` | string (uri) | não | até 2000 caracteres |
| `uploadId` | string (uuid) | sim |  |
| `caption` | string | não | até 1024 caracteres |
| `contactIds` | lista de string (uuid) | sim | até 10 |

### Exemplo de pedido

```bash
curl -X POST "https://api.donetalk.com/v1/c/demo/conversations/:id/messages" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "text",
  "text": "Oi Ana! Seu pedido saiu para entrega."
}'
```

### Resposta 202

```json
{
  "message": {
    "id": "01a3c0de-8b22-7c33-9d44-0e55f6677889",
    "status": "queued",
    "createdAt": "2026-10-23T13:02:11.000Z",
    "media": null
  }
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `403` `integration_template_only`
- `409` `window_closed`
- `422` `validation_failed`
- `429` `rate_limited`

## Concluir com um desfecho

`POST /v1/c/{slug}/conversations/{id}/close` · Escopos: `conversations:write`

`outcomeCode` vem de `GET /outcomes`. Com `ifNoReplyHours`, conclui só se o contato não responder nesse prazo.

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |
| `id` | O id do registro. |

### Corpo do pedido

| Campo | Tipo | Obrigatório | Detalhes |
|---|---|---|---|
| `outcomeCode` | string | sim | até 60 caracteres |
| `note` | string | não | até 4000 caracteres |
| `ifNoReplyHours` | integer | não | até 720; mínimo 1 |

### Exemplo de pedido

```bash
curl -X POST "https://api.donetalk.com/v1/c/demo/conversations/:id/close" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "outcomeCode": "converted",
  "note": "Fechou o plano anual."
}'
```

### Resposta 200

```json
{
  "ok": true,
  "isSuccess": true
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Reabrir

`POST /v1/c/{slug}/conversations/{id}/reopen` · Escopos: `conversations:write`

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |
| `id` | O id do registro. |

### Exemplo de pedido

```bash
curl -X POST "https://api.donetalk.com/v1/c/demo/conversations/:id/reopen" \
  -H "Authorization: Bearer $DONETALK_KEY"
```

### Resposta 200

```json
{
  "ok": true
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Enviar um arquivo

`POST /v1/c/{slug}/uploads` · Escopos: `messages:send_text` · `campaigns:write` · `messages:send_template`

multipart/form-data com o campo `file` (e `intent`: media, document, audio, sticker). Devolve o `id` para mandar numa mensagem ou pôr no cabeçalho de uma campanha.

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |

### Corpo do pedido

`multipart/form-data`: `file` + `intent` (media, document, audio, sticker).

### Exemplo de pedido

```bash
curl -X POST "https://api.donetalk.com/v1/c/demo/uploads" \
  -H "Authorization: Bearer $DONETALK_KEY"
```

### Resposta 201

```json
{
  "upload": {
    "id": "01a3d1e2-f3a4-7b5c-8d6e-7f8091a2b3c4",
    "mime": "image/jpeg",
    "sizeBytes": 182340,
    "filename": "cupom.jpg",
    "kind": "image",
    "voice": false,
    "conversion": null,
    "durationMs": null,
    "width": 1080,
    "height": 1080
  }
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`