Llamadas

Gestión de llamadas de video. Incluye listado, detalles, asignación, inicio, finalización y carga de archivos.

Endpoints

Método	Endpoint	Descripción	Rol Mínimo
`GET`	`/api/v1/calls`	Listar llamadas	`attendant`
`GET`	`/api/v1/calls/:id`	Detalles de la llamada	`attendant`
`POST`	`/api/v1/calls/:id/assign`	Asignar llamada a un agente	`attendant`
`POST`	`/api/v1/calls/:id/start`	Iniciar llamada	`attendant`
`POST`	`/api/v1/calls/:id/complete`	Finalizar llamada	`attendant`
`POST`	`/api/v1/calls/:call_id/upload`	Carga de archivo en la llamada	`attendant`
`GET`	`/api/v1/calls/:call_id/tags`	Tags de la llamada	`attendant`
`POST`	`/api/v1/calls/:call_id/tags`	Agregar tag	`attendant`
`DELETE`	`/api/v1/calls/:call_id/tags/:tag_id`	Eliminar tag	`attendant`
`GET`	`/api/v1/calls/:call_id/transcript`	Transcripción de la llamada	`attendant`
`GET`	`/api/v1/calls/:call_id/summary`	Resumen IA de la llamada	`attendant`
`POST`	`/api/v1/calls/:id/manager-notes`	Agregar nota gerencial	`supervisor`

Listar Llamadas

Devuelve la lista paginada de llamadas del tenant.

GET /api/v1/calls

Query Parameters

Parámetro	Tipo	Predeterminado	Descripción
`page`	`integer`	`1`	Número de página
`page_size`	`integer`	`20`	Elementos por página
`sort_by`	`string`	`inserted_at`	Campo para ordenamiento
`sort_order`	`string`	`desc`	Dirección del ordenamiento
`status`	`string`	-	Filtro por estado: `queued`, `active`, `completed`, `missed`, `cancelled`
`department_id`	`uuid`	-	Filtro por departamento
`user_id`	`uuid`	-	Filtro por agente
`date_from`	`string`	-	Fecha inicio (ISO 8601)
`date_to`	`string`	-	Fecha fin (ISO 8601)
`search`	`string`	-	Búsqueda por nombre/email del cliente

Ejemplo de Request

bash

curl -X GET "https://voki.avanter.com.br/api/v1/calls?page=1&page_size=10&status=completed&date_from=2026-02-01" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Respuesta Exitosa (200)

json

{
  "data": [
    {
      "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "status": "completed",
      "department_id": "e5f6a7b8-c9d0-1234-efgh-567890123456",
      "department_name": "Suporte Técnico",
      "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_name": "João Silva",
      "customer_name": "Carlos Ferreira",
      "customer_email": "carlos@email.com",
      "customer_phone": "+5511999998888",
      "duration": 345,
      "wait_time": 12,
      "rating": 5,
      "notes": "Cliente precisava de ajuda com configuração",
      "has_recording": true,
      "started_at": "2026-02-15T14:30:00Z",
      "completed_at": "2026-02-15T14:35:45Z",
      "inserted_at": "2026-02-15T14:29:48Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "page_size": 10,
    "total_pages": 15,
    "total_count": 142
  }
}

Detalles de la Llamada

GET /api/v1/calls/:id

Ejemplo de Request

bash

curl -X GET https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Respuesta Exitosa (200)

json

{
  "data": {
    "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "status": "completed",
    "department_id": "e5f6a7b8-c9d0-1234-efgh-567890123456",
    "department_name": "Suporte Técnico",
    "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "user_name": "João Silva",
    "customer_name": "Carlos Ferreira",
    "customer_email": "carlos@email.com",
    "customer_phone": "+5511999998888",
    "duration": 345,
    "wait_time": 12,
    "rating": 5,
    "notes": "Cliente precisava de ajuda com configuração",
    "has_recording": true,
    "recording_url": "/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/recording",
    "tags": [
      {
        "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "name": "Suporte",
        "color": "#3b82f6"
      }
    ],
    "started_at": "2026-02-15T14:30:00Z",
    "completed_at": "2026-02-15T14:35:45Z",
    "inserted_at": "2026-02-15T14:29:48Z"
  }
}

Asignar Llamada

Asigna una llamada de la cola a un agente.

POST /api/v1/calls/:id/assign

Request Body (opcional)

Campo	Tipo	Obligatorio	Descripción
`user_id`	`uuid`	No	ID del agente (predeterminado: usuario autenticado)

Ejemplo de Request

bash

curl -X POST https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/assign \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json"

Respuesta Exitosa (200)

json

{
  "data": {
    "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "status": "assigned",
    "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "user_name": "João Silva"
  }
}

Iniciar Llamada

Marca el inicio efectivo de la videollamada.

POST /api/v1/calls/:id/start

Ejemplo de Request

bash

curl -X POST https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/start \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Respuesta Exitosa (200)

json

{
  "data": {
    "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "status": "active",
    "started_at": "2026-02-18T14:30:00Z"
  }
}

Finalizar Llamada

Marca la llamada como finalizada.

POST /api/v1/calls/:id/complete

Request Body (opcional)

Campo	Tipo	Obligatorio	Descripción
`notes`	`string`	No	Notas del agente sobre la llamada

Ejemplo de Request

bash

curl -X POST https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/complete \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Problema resolvido. Cliente satisfeito."
  }'

Respuesta Exitosa (200)

json

{
  "data": {
    "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "status": "completed",
    "completed_at": "2026-02-18T14:45:00Z"
  }
}

Carga de Archivo

Sube un archivo asociado a una llamada (ej: documentos compartidos).

POST /api/v1/calls/:call_id/upload

Request

Envíe como multipart/form-data.

Campo	Tipo	Obligatorio	Descripción
`file`	`file`	Sí	Archivo a enviar

Ejemplo de Request

bash

curl -X POST https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/upload \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -F "file=@documento.pdf"

Respuesta Exitosa (201)

json

{
  "data": {
    "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "filename": "documento.pdf",
    "content_type": "application/pdf",
    "size": 245678,
    "url": "/uploads/calls/1a2b3c4d/documento.pdf"
  }
}

Tags de la Llamada

Listar Tags

GET /api/v1/calls/:call_id/tags

bash

curl -X GET https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/tags \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Agregar Tag

POST /api/v1/calls/:call_id/tags

bash

curl -X POST https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/tags \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890"
  }'

Eliminar Tag

DELETE /api/v1/calls/:call_id/tags/:tag_id

bash

curl -X DELETE https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/tags/t1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Estado de la Llamada

Estado	Descripción
`queued`	En cola esperando agente
`assigned`	Asignada a un agente
`active`	Videollamada en curso
`completed`	Finalizada
`missed`	No atendida (timeout)
`cancelled`	Cancelada por el cliente
`abandoned`	Abandonada (expirada en la cola)

Transcripción de la Llamada

Devuelve la transcripción generada automáticamente durante la llamada (cuando la feature de transcripción está habilitada en el plan).

GET /api/v1/calls/:call_id/transcript

Ejemplo de Request

bash

curl -X GET https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/transcript \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Respuesta Exitosa (200)

json

{
  "data": {
    "call_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "transcript": "Agente: Buenos días, cómo puedo ayudarle?\nCliente: Necesito soporte técnico...",
    "language": "pt-BR",
    "generated_at": "2026-02-18T14:46:00Z"
  }
}

Errores

Estado	Descripción
`403`	Feature `transcription` no disponible en el plan
`404`	Llamada no encontrada o sin transcripción

Resumen IA de la Llamada

Devuelve el resumen generado por IA después de la finalización de la llamada (disponible en planes con feature ai_summaries).

GET /api/v1/calls/:call_id/summary

Ejemplo de Request

bash

curl -X GET https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/summary \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Respuesta Exitosa (200)

json

{
  "data": {
    "call_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "summary": "El cliente se comunicó para resolver un problema de configuración...",
    "provider": "openai",
    "model": "gpt-4o-mini",
    "generated_at": "2026-02-18T14:46:30Z"
  }
}

Errores

Estado	Descripción
`403`	Feature `ai_summaries` no disponible en el plan
`404`	Llamada no encontrada o sin resumen

Notas Gerenciales

Agrega notas gerenciales a una llamada finalizada. Las notas son append-only (se agregan con timestamp y autor), no se reemplazan.

Roles permitidos: owner, manager, supervisor

POST /api/v1/calls/:id/manager-notes

Request Body

Campo	Tipo	Obligatorio	Descripcion
`notes`	`string`	Sí	Texto de la nota gerencial

Ejemplo de Request

bash

curl -X POST https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/manager-notes \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Excelente atención. Solicitar feedback del cliente."
  }'

Respuesta Exitosa (200)

json

{
  "data": {
    "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "manager_notes": "[2026-02-18 14:50 - Ana Supervisora] Excelente atención. Solicitar feedback del cliente."
  }
}

Errores

Estado	Descripción
`403`	Solo owner, manager o supervisor pueden agregar notas
`404`	Llamada no encontrada
`422`	Campo `notes` vacío

Reconexión de Llamadas

Cuando un participante se desconecta durante una llamada activa, el sistema inicia un período de gracia de 60 segundos para reconexión automática. El campo end_reason indica cómo fue finalizada la llamada.

Campos de Reconexión

Campo	Tipo	Descripción
`disconnected_at`	`datetime`	Momento de la desconexión (null si no hubo)
`reconnected_at`	`datetime`	Momento de la reconexión (null si no se reconectó)
`end_reason`	`string`	Razón de finalización: `normal`, `timeout`, `disconnect`, `abandoned`

Flujo de Reconexión

Participante se desconecta -> evento peer_disconnected enviado via WebSocket
Timer de 60 segundos inicia en el frontend (UI de reconexión con cuenta regresiva)
Si se reconecta dentro de 60s -> evento peer_reconnected -> renegociación WebRTC
Si no se reconecta -> llamada finalizada con end_reason: "disconnect"

Llamadas ​

Endpoints ​

Listar Llamadas ​

Query Parameters ​

Ejemplo de Request ​

Respuesta Exitosa (200) ​

Detalles de la Llamada ​

Ejemplo de Request ​

Respuesta Exitosa (200) ​

Asignar Llamada ​

Request Body (opcional) ​

Ejemplo de Request ​

Respuesta Exitosa (200) ​

Iniciar Llamada ​

Ejemplo de Request ​

Respuesta Exitosa (200) ​

Finalizar Llamada ​

Request Body (opcional) ​

Ejemplo de Request ​

Respuesta Exitosa (200) ​

Carga de Archivo ​

Request ​

Ejemplo de Request ​

Respuesta Exitosa (201) ​

Tags de la Llamada ​

Listar Tags ​

Agregar Tag ​

Eliminar Tag ​

Estado de la Llamada ​

Transcripción de la Llamada ​

Ejemplo de Request ​

Respuesta Exitosa (200) ​

Errores ​

Resumen IA de la Llamada ​

Ejemplo de Request ​

Respuesta Exitosa (200) ​

Errores ​

Notas Gerenciales ​

Request Body ​

Ejemplo de Request ​

Respuesta Exitosa (200) ​

Errores ​

Reconexión de Llamadas ​

Campos de Reconexión ​

Flujo de Reconexión ​

Llamadas

Endpoints

Listar Llamadas

Query Parameters

Ejemplo de Request

Respuesta Exitosa (200)

Detalles de la Llamada

Ejemplo de Request

Respuesta Exitosa (200)

Asignar Llamada

Request Body (opcional)

Ejemplo de Request

Respuesta Exitosa (200)

Iniciar Llamada

Ejemplo de Request

Respuesta Exitosa (200)

Finalizar Llamada

Request Body (opcional)

Ejemplo de Request

Respuesta Exitosa (200)

Carga de Archivo

Request

Ejemplo de Request

Respuesta Exitosa (201)

Tags de la Llamada

Listar Tags

Agregar Tag

Eliminar Tag

Estado de la Llamada

Transcripción de la Llamada

Ejemplo de Request

Respuesta Exitosa (200)

Errores

Resumen IA de la Llamada

Ejemplo de Request

Respuesta Exitosa (200)

Errores

Notas Gerenciales

Request Body

Ejemplo de Request

Respuesta Exitosa (200)

Errores

Reconexión de Llamadas

Campos de Reconexión

Flujo de Reconexión