# Permiso para llamar por WhatsApp

WhatsApp solo deja llamar a quien dio permiso. El permiso puede ser **temporal** (7 días) o **permanente**, y la persona lo puede quitar cuando quiera. Con estas dos rutas tu sistema consulta si el contacto dio permiso y se lo pide.

En las dos, `agent_id` es el agente de voz que atiende el número de WhatsApp. Si atiende varios números, indica cuál con `whatsapp_number`.

---

## Consultar el permiso

**GET** `/v2/get-whatsapp-call-permission?agent_id=…&phone=…`

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `agent_id` | string | El agente de voz. |
| `phone` | string | Teléfono del contacto, con código de país. Ejemplo: `+5491122334455` |
| `whatsapp_number` | string | Opcional: el número de WhatsApp, si el agente atiende varios. |

```bash
curl --request GET \
     --url 'https://calls.anunzi.net/v2/get-whatsapp-call-permission?agent_id=agent_7f3c9d2e1b&phone=%2B5491122334455' \
     --header 'Authorization: Bearer TU_API_KEY'
```

### Respuesta — 200 OK

```json
{
  "phone": "+5491122334455",
  "whatsapp_number": "+5491155550190",
  "status": "temporary",
  "granted": true,
  "expires_at": "2026-11-23T14:00:00Z",
  "can_request": false,
  "can_call": true,
  "requested_at": "2026-11-16T13:58:00Z"
}
```

| Campo | Descripción |
|-------|-------------|
| `status` | `temporary`, `permanent` o `no_permission`. |
| `granted` | `true` si se lo puede llamar por WhatsApp. |
| `expires_at` | Vencimiento del permiso temporal (`null` si es permanente o no hay permiso). |
| `can_request` | Si ahora WhatsApp permite pedirle permiso. |
| `can_call` | Si ahora WhatsApp permite llamarlo. |
| `requested_at` | Cuándo se le pidió permiso por última vez. |

---

## Pedir permiso

**POST** `/v2/request-whatsapp-call-permission`

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `agent_id` | string | El agente de voz. Requerido. |
| `phone` | string | Teléfono del contacto, con código de país. Requerido. |
| `text` | string | Opcional: el texto del mensaje que acompaña el botón (solo si la conversación está abierta). |
| `whatsapp_number` | string | Opcional: el número de WhatsApp, si el agente atiende varios. |

```bash
curl --request POST \
     --url https://calls.anunzi.net/v2/request-whatsapp-call-permission \
     --header 'Authorization: Bearer TU_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
  "agent_id": "agent_7f3c9d2e1b",
  "phone": "+5491122334455",
  "text": "¿Te podemos llamar por WhatsApp para coordinar la visita?"
}'
```

* Si la conversación con el contacto está abierta (escribió en las últimas 24 h), le llega un mensaje con un botón para dar permiso, con tu `text`. Es gratis.
* Si no, le llega la **plantilla de permiso** de tu número, que se cobra como cualquier plantilla de WhatsApp.
* La respuesta trae los mismos campos que la consulta, más `requested: true` y `via` (`interactive` o `template`). Si ya había dado permiso, responde `requested: false` y no envía nada.
* WhatsApp permite **1 pedido por día y 2 por semana** por contacto.

Cuando el contacto acepta, el permiso queda guardado: puedes consultarlo de nuevo o llamarlo con [Crear llamada de WhatsApp](crear-llamada-whatsapp.md).

---

## Errores

| Código | `code` | Qué pasó |
|--------|--------|----------|
| `400` | `missing_phone` | Falta el teléfono del contacto. |
| `409` | `no_whatsapp_line` | El agente no atiende ningún número de WhatsApp con las llamadas activas. |
| `429` | `permission_request_limit` | WhatsApp no permite pedirle permiso ahora (1 por día y 2 por semana). |
| `502` | `whatsapp_error` | WhatsApp no respondió o rechazó el pedido (la respuesta trae el detalle). |
