Listar llamadas

GET /api/v1/calls

Este endpoint permite obtener un listado de llamadas entrantes o salientes registradas en la plataforma, dentro de un rango de fechas definido por el usuario.

Es útil para monitorear la actividad telefónica, generar métricas operativas y auditar interacciones con clientes o usuarios finales.

A través de una solicitud GET, es posible recuperar llamadas aplicando filtros opcionales como tipo de llamada, campaña asociada o límites de paginación para acotar los resultados.

La respuesta del endpoint incluye un conjunto de datos estructurados que proporciona información relevante de cada llamada, como el número de origen y destino, fecha y hora de la interacción, duración total y campaña relacionada, etc.

A continuación, se describen los parámetros disponibles, ejemplos de solicitud y la estructura detallada de la respuesta esperada.

ℹ Recuerda que:

La URL base para todas las solicitudes es: https://tu-dominio.c3.pe

Importante: reemplaza tu-dominio por el nombre de dominio específico que te haya proporcionado C3.

Solicitud

Cabeceras

Encabezado	Tipo	Obligatorio	Descripción
Authorization	String	✅ Sí	Token de autenticación (Bearer Token).

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Descripción
from_date	string	✅ Sí	Fecha y hora de inicio en formato YYYY-MM-DD HH:MM:SS.
to_date	string	✅ Sí	Fecha y hora de fin en formato YYYY-MM-DD HH:MM:SS.
call_type	string	❌ No (Por defecto incoming)	Tipo de llamada (incoming, outgoing, etc.).
campaign_id	int	❌ No	ID de la campaña.
with_form	int	❌ No (Por defecto 0)	Incluir el formulario en la respuesta (1 para activarlo).
with_pagination	int	❌ No (Por defecto 0)	Incluir la paginación en la respuesta (1 para activarlo).
page	int	❌ No (Por defecto 1)	Número de página (requiere with_pagination=1).
per_page	int	❌ No (Por defecto 15)	Resultados por página (requiere with_pagination=1).

Ejemplo de solicitud

GET /api/v1/calls?from_date=2025-02-01 00:00:00&to_date=2025-04-20 23:59:59&call_type=incoming&campaign_id=11&with_form=1&with_pagination=1&page=1&per_page=1

Respuesta

La API devuelve un json con la siguiente estructura.

Respuesta base 200

 {
  "message": "Llamadas obtenidas correctamente",
  "data": [
    {
      "id": 52,
      "campaign_id": 1,
      "campaign_name": "campaña00",
      "agent_id": 3,
      "agent_name": "Agente 1",
      "customer_number": "99999999",
      "customer_name": null,
      "ring_duration": 1,
      "talk_duration": 25,
      "total_duration": 26,
      "created_at": "2025-04-04 17:44:48",
      "call_type": "incoming_campaign",
      "result": "COMPLETECALLER",
      "is_vip": 0,
      "extension": "7002"
    }
  ]
}

Respuesta con formulario 200

{
  "message": "Llamadas obtenidas correctamente",
  "data": [
    {
      "id": 52,
      "campaign_id": 1,
      "campaign_name": "campaña00",
      "agent_id": 3,
      "agent_name": "Agente 1",
      "customer_number": "99999999",
      "customer_name": null,
      "ring_duration": 1,
      "talk_duration": 25,
      "total_duration": 26,
      "created_at": "2025-04-04 17:44:48",
      "call_type": "incoming_campaign",
      "result": "COMPLETECALLER",
      "is_vip": 0,
      "extension": "7002",
      "call_form": {
        "id": 38,
        "fields": [
          {
            "name": "Nombre",
            "value": null
          },
          {
            "name": "destino",
            "value": null
          }
        ],
        "form_id": "90465948-34ed-4635-9021-29415d2379c7",
        "form_type": "INBOUND",
        "created_at": "2025-04-04 17:47:13.000000",
        "submit_type": "AUTOMATIC"
      }
    }
  ]
}

Respuesta con paginación 200

{
  "message": "Llamadas obtenidas correctamente",
  "data": [
    {
      "id": 52,
      "campaign_id": 1,
      "campaign_name": "campaña00",
      "agent_id": 3,
      "agent_name": "Agente 1",
      "customer_number": "99999999",
      "customer_name": null,
      "ring_duration": 1,
      "talk_duration": 25,
      "total_duration": 26,
      "created_at": "2025-04-04 17:44:48",
      "call_type": "incoming_campaign",
      "result": "COMPLETECALLER",
      "is_vip": 0,
      "extension": "7002",
      "call_form": {
        "id": 38,
        "fields": [
          {
            "name": "Nombre",
            "value": null
          },
          {
            "name": "destino",
            "value": null
          }
        ],
        "form_id": "90465948-34ed-4635-9021-29415d2379c7",
        "form_type": "INBOUND",
        "created_at": "2025-04-04 17:47:13.000000",
        "submit_type": "AUTOMATIC"
      }
    }
  ],
  "pagination": {
    "total_items": 1,
    "items_per_page": 15,
    "current_page": 1,
    "total_pages": 1
  }
}

Definición de atributos

Campo	Tipo	Descripción
message	String	Mensaje de respuesta del servidor.
data	Array	Lista de llamadas obtenidas.
data.id	Integer	Identificador de la llamada.
data.campaign_id	Integer	Identificador de la campaña.
data.campaign_name	String	Nombre de la campaña.
data.agent_id	Integer	Identificador del agente.
data.agent_name	String	Nombre del agente.
data.customer_number	String	Número del cliente.
data.customer_name	String | null	Nombre del cliente.
data.ring_duration	Integer	Duración del timbrado en segundos.
data.talk_duration	Integer	Duración de la conversación en segundos.
data.total_duration	Integer	Duración total de la llamada en segundos.
data.created_at	String	Fecha y hora de creación de la llamada.
data.call_type	String	Tipo de llamada (ej. "incoming_campaign", "external_incoming", "internal_incoming", "outgoing_campaign).
data.result	String	Resultado de la llamada (ej. "COMPLETECALLER", "ANSWERED", "NO ANSWERED", "ABANDON", "COMPLETEAGENT").
data.is_vip	Integer	Indicador si el cliente es VIP.
data.extension	String	Extensión de la llamada.
data.call_form	Object	Información del formulario asociado a la llamada.
data.call_form.id	Integer	Identificador del formulario.
data.call_form.fields	Array	Lista de campos del formulario.
data.call_form.fields.name	String	Nombre del campo del formulario.
data.call_form.fields.value	String | null	Valor del campo del formulario.
data.call_form.form_id	String	UUID del formulario.
data.call_form.form_type	String	Tipo de formulario (ej. "INBOUND", "OUTBOUND").
data.call_form.created_at	String	Fecha y hora de creación del formulario.
data.call_form.submit_type	String	Tipo de envío del formulario (ej. "AUTOMATIC", "MANUALLY").
pagination	Object	Información de la paginación.
pagination.total_items	Integer	Total de elementos encontrados.
pagination.items_per_page	Integer	Elementos por página.
pagination.current_page	Integer	Página actual.
pagination.total_pages	Integer	Total de páginas.

Errores generales

Código HTTP	Tipo	Causa común
401	Unauthorized	El token de acceso no fue proporcionado en el encabezado Authorization, es inválido o ha sido revocado. Verifique que el token sea correcto y esté activo.
422	Unprocessable Entity	La solicitud fue entendida, pero contiene errores semánticos que impiden su procesamiento. Esto puede deberse a: 1. Parámetros faltantes o inválidos (ej, from_date no es una fecha válida); 2. Recurso inexistente (wa_number no registrado en el sistema); 3. Violación de reglas de negocio (el rango de fechas excede el límite permitido).
500	Server Error	Error interno del servidor. Intenta nuevamente más tarde o contacta soporte técnico.