> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linahealthcareplatform.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Iniciar llamadas IA

> Guía completa para iniciar llamadas telefónicas con IA a pacientes, gestionar el flujo de la llamada y procesar los resultados.

## Descripción general

LINA puede realizar llamadas telefónicas inteligentes a pacientes usando IA conversacional. Las llamadas son ideales para seguimiento post-operatorio, recordatorios de medicación, evaluaciones de bienestar y triaje inicial.

### Coste en créditos

| Concepto                   | Créditos |
| -------------------------- | -------- |
| Inicio de llamada (base)   | 15       |
| Por minuto de conversación | 10       |

<Info>
  Una llamada de 5 minutos consume **15 + (5 × 10) = 65 créditos**. La duración se redondea al minuto más cercano.
</Info>

## Flujo de una llamada

```mermaid theme={null}
sequenceDiagram
    participant API as Tu servidor
    participant LINA as LINA API
    participant Phone as Teléfono paciente

    API->>LINA: POST /voice/call
    LINA-->>API: 201 (status: queued)
    LINA->>Phone: Llamada saliente
    Note over LINA,Phone: Estado: ringing
    Phone-->>LINA: Paciente contesta
    Note over LINA,Phone: Estado: in-progress
    LINA->>LINA: Conversación IA
    Note over LINA,Phone: Estado: completed
    LINA->>API: Webhook call.ended
```

## Iniciar una llamada

<Steps>
  <Step title="Realizar la petición">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.linahealthcareplatform.com/api/v1/voice/call \
        -H "Authorization: Bearer YOUR_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "patientId": "pat_xyz789",
          "purpose": "Seguimiento post-operatorio día 3. Preguntar por nivel de dolor, movilidad y estado de la herida.",
          "language": "es",
          "maxDuration": 300
        }'
      ```

      ```javascript Node.js theme={null}
      const response = await fetch('https://api.linahealthcareplatform.com/api/v1/voice/call', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_TOKEN',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          patientId: 'pat_xyz789',
          purpose: 'Seguimiento post-operatorio día 3. Preguntar por nivel de dolor, movilidad y estado de la herida.',
          language: 'es',
          maxDuration: 300
        })
      });
      const call = await response.json();
      console.log(call.id); // call_abc123
      ```

      ```python Python theme={null}
      import requests

      response = requests.post(
          "https://api.linahealthcareplatform.com/api/v1/voice/call",
          headers={
              "Authorization": "Bearer YOUR_TOKEN",
              "Content-Type": "application/json"
          },
          json={
              "patientId": "pat_xyz789",
              "purpose": "Seguimiento post-operatorio día 3. Preguntar por nivel de dolor, movilidad y estado de la herida.",
              "language": "es",
              "maxDuration": 300
          }
      )
      call = response.json()
      print(call["id"])  # call_abc123
      ```
    </CodeGroup>

    **Respuesta:**

    ```json theme={null}
    {
      "id": "call_abc123",
      "patientId": "pat_xyz789",
      "status": "queued",
      "purpose": "Seguimiento post-operatorio día 3...",
      "language": "es",
      "maxDuration": 300,
      "createdAt": "2026-05-14T10:30:00Z"
    }
    ```
  </Step>

  <Step title="Monitorizar el estado">
    Consulta el estado de la llamada en cualquier momento:

    ```bash theme={null}
    curl -X GET https://api.linahealthcareplatform.com/api/v1/voice/calls/call_abc123 \
      -H "Authorization: Bearer YOUR_TOKEN"
    ```

    Los estados posibles son:

    | Estado        | Descripción                                              |
    | ------------- | -------------------------------------------------------- |
    | `queued`      | Llamada en cola, pendiente de iniciar                    |
    | `ringing`     | El teléfono del paciente está sonando                    |
    | `in-progress` | Conversación en curso                                    |
    | `completed`   | Llamada finalizada con éxito                             |
    | `failed`      | Error en la llamada (no contesta, número inválido, etc.) |
  </Step>

  <Step title="Procesar los resultados">
    Una vez completada la llamada, recibirás el webhook `call.ended` con la transcripción y el resumen generado por IA:

    ```json theme={null}
    {
      "event": "call.ended",
      "data": {
        "id": "call_abc123",
        "patientId": "pat_xyz789",
        "status": "completed",
        "duration": 187,
        "creditsConsumed": 55,
        "transcript": [
          { "role": "assistant", "content": "Hola María, soy LINA del equipo del Dr. García. ¿Cómo se encuentra hoy?" },
          { "role": "patient", "content": "Bien, aunque tengo algo de molestia en la zona de la operación." },
          { "role": "assistant", "content": "Entiendo. En una escala del 1 al 10, ¿cómo calificaría su nivel de dolor?" },
          { "role": "patient", "content": "Diría que un 4." }
        ],
        "summary": "Paciente refiere dolor 4/10 en zona quirúrgica. Movilidad limitada pero mejorando. Herida sin signos de infección. Recomienda seguimiento en 48h.",
        "completedAt": "2026-05-14T10:33:07Z"
      }
    }
    ```
  </Step>
</Steps>

## Parámetro `purpose`

El campo `purpose` es fundamental para la calidad de la llamada. Proporciona instrucciones claras sobre:

* **Objetivo** de la llamada
* **Preguntas específicas** a realizar
* **Contexto clínico** relevante
* **Criterios de alerta** si aplican

<Warning>
  No incluyas información clínica sensible completa en el `purpose`. Usa identificadores internos y contexto general. LINA tiene acceso al historial del paciente de forma segura.
</Warning>

## Gestión de errores

Si la llamada falla, el campo `failureReason` indica el motivo:

| Código           | Descripción                              |
| ---------------- | ---------------------------------------- |
| `no_answer`      | El paciente no contestó tras 30 segundos |
| `busy`           | Línea ocupada                            |
| `invalid_number` | Número de teléfono no válido             |
| `rejected`       | Llamada rechazada por el paciente        |
| `network_error`  | Error de red del operador                |

<Note>
  Las llamadas con estado `failed` por `no_answer` o `busy` solo consumen 5 créditos. Las llamadas rechazadas o con error de red no consumen créditos.
</Note>

## Horarios de llamada

LINA respeta las franjas horarias adecuadas para llamadas médicas:

* **Lunes a viernes:** 9:00 – 20:00 (hora local del paciente)
* **Sábados:** 10:00 – 14:00
* **Domingos y festivos:** No se realizan llamadas

Las llamadas fuera de horario se encolan automáticamente para la siguiente franja disponible.