API de Marcación Predictiva

El sistema del cliente envía una solicitud HTTP por cada contacto a marcar. Voz MX origina la llamada saliente, corre un análisis automático de contestadora (AMD) sobre el audio de respuesta y, si confirma que contestó una persona, conecta la llamada de inmediato con la extensión del agente indicada. Si contesta un buzón o nadie responde, la llamada se cierra y se reporta el resultado — el servicio no reintenta la marcación; los reintentos, si se requieren, los gestiona el sistema del cliente.

Toda solicitud se autentica con una llave fija enviada en el encabezado X-API-Key, provista por Voz MX de forma independiente a este documento.

Solicitud

POST https://pbx.vozmx.mx/api/call
Content-Type: application/json
X-API-Key: <llave asignada>

Ejemplo — síncrono

{
  "tel": "5551234567",
  "extension": "602611",
  "ring_timeout": 60
}

Ejemplo — asíncrono con callback propio

{
  "tel": "5551234567",
  "extension": "602611",
  "mode": "async",
  "callback_url": "https://cliente.example.com/webhook/resultado"
}

1. Se recibe la solicitudVoz MX valida la llave, el número y la extensión, y origina la llamada saliente hacia tel.
2. Se analiza la respuestaAl contestar, corre la detección de contestadora (AMD) sobre los primeros segundos de audio.
3. Bifurcación según resultadoSi el análisis confirma una persona, la llamada se conecta de inmediato con la extensión del agente. Si detecta buzón, o el resultado es ambiguo, o nadie contesta, la llamada se cuelga — sin reintento.
4. Se reporta el resultadoEn modo síncrono, la respuesta HTTP se entrega hasta conocer el desenlace. En modo asíncrono, se confirma la recepción de inmediato y el resultado llega después a callback_url.

El modo se elige por solicitud con el campo mode del JSON — si se omite, se usa el default configurado del lado de Voz MX. Si el volumen de marcación es alto, se recomienda pedir modo asíncrono para no mantener conexiones HTTP abiertas por cada llamada en curso.

JSON — mismo formato en ambos modos

{
  "call_id": "51d18c42-8700-…",
  "tel": "5551234567",
  "extension": "602611",
  "status": "connected",
  "amd_status": "HUMAN"
}

Para monitoreo del servicio, sin autenticación:

GET https://pbx.vozmx.mx/api/health
→ {"status": "ok"}

Antes de subir contactos hace falta una campaña. Se puede crear desde el panel pbx.vozmx.mx/predictivo o directamente por API — útil si el sistema del cliente da de alta campañas de forma automática. La creación es idempotente por nombre: si ya existe una campaña con ese name, no se crea una segunda — se regresa la existente con su configuración actual, así que este mismo endpoint también sirve para consultar "¿ya existe esta campaña? ¿con qué parámetros quedó?" antes de decidir si crear una nueva.

Solicitud (todos los campos excepto name son opcionales)

POST https://pbx.vozmx.mx/api/campaigns
X-API-Key: <llave asignada>
Content-Type: application/json

{
  "name": "Campaña Octubre",
  "agent_strategy": "longest_idle",
  "agents": ["602611", "602612"],
  "dial_ratio": 1.0,
  "target_abandon_rate": 3.0,
  "ring_timeout_seconds": 30,
  "wrap_up_seconds": 30,
  "max_attempts": 3,
  "retry_delay_minutes": 60,
  "calling_hours_start": "09:00:00",
  "calling_hours_end": "20:00:00"
}

Respuesta — campaña nueva (código 201)

{
  "exists": false,
  "campaign": { "id": 7, "name": "Campaña Octubre", "status": "draft", "...": "resto de los parámetros" },
  "assignedAgents": ["602611", "602612"]
}

Respuesta — la campaña ya existía (código 200)

{
  "exists": true,
  "campaign": { "...": "su configuración actual" },
  "assignedAgents": ["602611", "602612"],
  "stats": [ { "status": "pending", "total": 40 } ]
}

Además de originar llamadas una por una con /api/call, Voz MX opera un motor propio de marcación predictiva (pacing y asignación automática de agente) que trabaja por campañas. Las campañas se crean y administran desde el panel pbx.vozmx.mx/predictivo (acceso provisto por Voz MX de forma independiente a este documento); al crear o abrir una campaña ahí, su ID aparece visible en la parte superior de su detalle — ese es el que se usa en la solicitud de abajo. Una vez con el ID, el sistema del cliente puede subir o ampliar la lista de contactos directamente por API, en el formato que le resulte más cómodo.

Solicitud

POST https://pbx.vozmx.mx/api/campaigns/<id>/contacts
X-API-Key: <llave asignada>

Acepta tres formatos de entrada, según convenga:

a) JSON

Content-Type: application/json

{
  "contacts": [
    { "phone": "5551234567", "name": "Juan Pérez" },
    "5559876543"
  ]
}

Cada elemento de contacts puede ser un objeto (phone/telefono + name/nombre opcional) o un número suelto, sin nombre.

b) CSV o c) Excel (.xlsx / .xls)

Content-Type: multipart/form-data
campo: file=<lista.csv | lista.xlsx>

Encabezados reconocidos: telefono/phone/numero/tel y nombre/name (sin importar mayúsculas). Sin encabezado reconocible, se toma la primera columna como teléfono y la segunda como nombre. Se aceptan números a 10 dígitos, o a 12 con lada país 52 al frente. Las filas con teléfono inválido se ignoran — no truena la subida completa.

Respuesta exitosa — 201

{ "inserted": 3 }

Toda la información visible en el panel /predictivo también está disponible por API, para integrarla a un sistema propio de reportes sin depender de la sesión web.

Listar campañas

GET https://pbx.vozmx.mx/api/campaigns
X-API-Key: <llave asignada>

Detalle de una campaña (agentes asignados con registered en vivo + estadísticas por estado)

GET https://pbx.vozmx.mx/api/campaigns/<id>

Reporte de contactos (filtrable y paginado)

GET https://pbx.vozmx.mx/api/campaigns/<id>/contacts?status=no_answer&page=1

Respuesta

{
  "filter": "no_answer",
  "page": 1,
  "totalPages": 1,
  "total": 4,
  "contacts": [
    { "id": 8, "phone": "8115167260", "name": "Horacio Frias", "status": "no_answer", "attempts": 1, "last_attempt_at": "2026-08-27 12:02:21" }
  ]
}

Los contactos que no se completaron con éxito (no contestó, contestadora, falló) se pueden regresar a la cola de marcado — el motor los vuelve a tomar como pendientes en su siguiente ciclo, respetando el ratio y el horario configurado de la campaña.

Reencolar todos los que coincidan con un estado

POST https://pbx.vozmx.mx/api/campaigns/<id>/requeue
Content-Type: application/json

{ "status": "no_answer" }

Reencolar solo contactos específicos

{ "contact_ids": [8, 11, 13] }

Si se envían ambos, contact_ids tiene prioridad. Respuesta: { "requeued": <número de contactos afectados> }.

Control de la campaña

POST https://pbx.vozmx.mx/api/campaigns/<id>/start
POST https://pbx.vozmx.mx/api/campaigns/<id>/pause
POST https://pbx.vozmx.mx/api/campaigns/<id>/stop

start pone la campaña en marcha y marca disponibles a los agentes asignados que estén registrados en el PBX; pause detiene la generación de llamadas nuevas sin colgar las que ya están en curso; stop detiene la campaña y libera a sus agentes.

Disponibilidad de agentes = registro SIP

No hay que avisar al PBX que un agente está listo: una extensión entra a la rotación en cuanto su softphone se registra y sale en cuanto se desregistra (el motor lo revisa cada 3 s). Si ninguna extensión asignada está registrada, la campaña queda en running pero no marca hasta que alguien se registre. La respuesta de start trae agents_registered y agents_unregistered, y el detalle de la campaña trae registered por agente, para comprobarlo antes de arrancar.

Inactivar y reactivar una campaña

POST https://pbx.vozmx.mx/api/campaigns/<id>/deactivate
POST https://pbx.vozmx.mx/api/campaigns/<id>/activate
GET  https://pbx.vozmx.mx/api/campaigns?include_inactive=1

Una campaña no se borra: se inactiva. deactivate la saca del listado y del motor de marcado, pero conserva sus contactos, intentos e historial de llamadas. Solo se acepta con la campaña detenida (draft, stopped o completed); si sigue running o paused responde 409 — primero stop, nunca en caliente. activate la regresa a stopped, lista para editarse o iniciarse. El listado GET /api/campaigns omite las inactivas salvo con include_inactive=1, y una campaña inactiva ya no cuenta para la idempotencia por nombre: se puede crear una nueva con el mismo name. Respuesta: { "status": "inactive", "campaign": { … } }.