> ## 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 llamada

> Inicia una llamada telefónica con IA a un paciente. Consume 15 créditos base + 10 créditos por minuto.

## Body

<ParamField body="patientId" type="string" required>
  ID del paciente a llamar.
</ParamField>

<ParamField body="purpose" type="string" required>
  Propósito e instrucciones para la IA. Describe el objetivo de la llamada, preguntas clave y contexto clínico relevante.
</ParamField>

<ParamField body="language" type="string" default="es">
  Idioma de la llamada. Valores: `es` (español), `en` (inglés), `ca` (catalán).
</ParamField>

<ParamField body="maxDuration" type="integer" default="600">
  Duración máxima de la llamada en segundos (máximo 1800 = 30 minutos).
</ParamField>

### Coste en créditos

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

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "call_abc123",
    "patientId": "pat_xyz789",
    "status": "queued",
    "purpose": "Seguimiento post-operatorio día 3. Preguntar por nivel de dolor, movilidad y estado de la herida.",
    "language": "es",
    "maxDuration": 300,
    "createdAt": "2026-05-14T10:30:00Z"
  }
  ```
</ResponseExample>

<ResponseField name="id" type="string">
  Identificador único de la llamada con prefijo `call_`.
</ResponseField>

<ResponseField name="status" type="string">
  Estado inicial: `queued`. Ver [estado de llamada](/api-reference/calls/status) para todos los estados.
</ResponseField>


## OpenAPI

````yaml openapi.yml POST /voice/call
openapi: 3.1.0
info:
  title: LINA Healthcare Platform API
  version: 1.0.0
  description: |
    API de integración para la plataforma LINA Healthcare.
    Todas las rutas requieren un token JWT obtenido intercambiando una API Key.
servers:
  - url: https://api.linahealthcareplatform.com/api/v1
    description: Production
security:
  - bearerAuth: []
paths:
  /voice/call:
    post:
      tags:
        - Llamadas
      summary: Iniciar llamada IA
      description: Inicia una llamada telefónica con IA al paciente
      operationId: initiateCall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - patientId
              properties:
                patientId:
                  type: string
                purpose:
                  type: string
                language:
                  type: string
                  enum:
                    - es
                    - en
                    - ca
      responses:
        '201':
          description: Llamada iniciada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceCall'
components:
  schemas:
    VoiceCall:
      type: object
      properties:
        id:
          type: string
        patientId:
          type: string
        status:
          type: string
          enum:
            - queued
            - ringing
            - in-progress
            - completed
            - failed
        duration:
          type: integer
        transcript:
          type: string
        summary:
          type: string
        createdAt:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Token JWT obtenido via POST /auth/token

````