# Mensajes

## Enviar una plantilla a un teléfono

`POST /v1/c/{slug}/messages/template` · Alcances: `messages:send_template`

En la conversación abierta del contacto, o en una nueva, atendida como el número atiende lo que llega. El contacto se crea si no existe. `idempotencyKey` (o el encabezado Idempotency-Key) evita enviar dos veces.

### Parámetros de la dirección

| Campo | Detalles |
|---|---|
| `slug` | El identificador de la empresa en DoneTalk (el de la clave). |

### Cuerpo de la solicitud

| Campo | Tipo | Obligatorio | Detalles |
|---|---|---|---|
| `phone` | string | sí |  |
| `contactName` | string | no | hasta 200 caracteres |
| `channelId` | string (uuid) | no |  |
| `templateId` | string (uuid) | sí |  |
| `body` | lista de string | no | hasta 20; default `[]` |
| `header` | lista de string | no | hasta 5; default `[]` |
| `buttons` | object | no | default `{}` |
| `handling` | uno de `number`, `team` | no | default `"number"` |
| `assigneeEmail` | string (email) | no | hasta 320 caracteres |
| `idempotencyKey` | string | sí | hasta 200 caracteres |

### Ejemplo de solicitud

```bash
curl -X POST "https://api.donetalk.com/v1/c/demo/messages/template" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+5548999990001",
  "contactName": "Ana Souza",
  "templateId": "01a0cad0-0000-7000-8000-000000000002",
  "body": [
    "Ana",
    "ANA10"
  ],
  "idempotencyKey": "pedido-88213-lembrete"
}'
```

### Respuesta 201

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

### Errores posibles

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

## Estado de un mensaje y la respuesta

`GET /v1/c/{slug}/messages/{id}` · Alcances: `conversations:read` · `messages:send_template` · `messages:send_text`

### Parámetros de la dirección

| Campo | Detalles |
|---|---|
| `slug` | El identificador de la empresa en DoneTalk (el de la clave). |
| `id` | El id del registro. |

### Ejemplo de solicitud

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

### Respuesta 200

```json
{
  "message": {
    "id": "01a3c0de-8b22-7c33-9d44-0e55f6677889",
    "conversationId": "01a3c0de-7a11-7b22-8c33-9d44e55f6677",
    "channelId": "01a0cccc-0000-7000-8000-000000000002",
    "direction": "outbound",
    "from": null,
    "type": "template",
    "text": "Oi Ana! Seu cupom ANA10 vale até sexta. Quer usar agora?",
    "status": "read",
    "errorCode": null,
    "createdAt": "2026-10-23T13:02:11.000Z",
    "sentAt": "2026-10-23T13:02:12.000Z",
    "deliveredAt": "2026-10-23T13:02:13.000Z",
    "readAt": "2026-10-23T13:05:40.000Z",
    "reply": {
      "id": "01a0d05a-3ee3-75bd-9db5-dc9856f079c9",
      "type": "button",
      "text": "Quero o cupom",
      "at": "2026-10-23T13:05:52.000Z"
    }
  }
}
```

### Errores posibles

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

## Mensajes de un teléfono

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

Los mensajes de un teléfono desde un momento, los más nuevos primero.

### Parámetros de la dirección

| Campo | Detalles |
|---|---|
| `slug` | El identificador de la empresa en DoneTalk (el de la clave). |

### Parámetros de consulta

| Campo | Tipo | Obligatorio | Detalles |
|---|---|---|---|
| `phone` | string | sí |  |
| `since` | string (date-time) | sí |  |
| `channelId` | string (uuid) | no |  |
| `direction` | uno de `inbound`, `outbound` | no |  |
| `limit` | integer | no | hasta 100; mínimo 1; default `20` |

### Ejemplo de solicitud

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

### Respuesta 200

```json
{
  "messages": [
    {
      "id": "01a3c0de-8b22-7c33-9d44-0e55f6677889",
      "conversationId": "01a3c0de-7a11-7b22-8c33-9d44e55f6677",
      "channelId": "01a0cccc-0000-7000-8000-000000000002",
      "direction": "outbound",
      "from": null,
      "type": "template",
      "text": "Oi Ana! Seu cupom ANA10 vale até sexta. Quer usar agora?",
      "status": "read",
      "errorCode": null,
      "createdAt": "2026-10-23T13:02:11.000Z",
      "sentAt": "2026-10-23T13:02:12.000Z",
      "deliveredAt": "2026-10-23T13:02:13.000Z",
      "readAt": "2026-10-23T13:05:40.000Z"
    }
  ]
}
```

### Errores posibles

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