Developers (en español)

English version: Developers.

Todo lo que necesitas para integrarte con Dialer Digital: una API REST de plano de control para campañas, leads, CDR, evidencia de cumplimiento, supervisión, caller-ID/DIDs, promesas, callbacks y facturación, además de un flujo WebSocket del piso en vivo para entrega en tiempo real por push.

Las páginas de esta sección que aún no tienen versión en español (REST API y el resto) se enlazan a su versión en inglés y lo dicen en el enlace.

La superficie de integración de un vistazo

Superficie	Úsala para	Documentación
REST API (/v1)	Campañas y su ciclo de vida, importación de leads, consultas de CDR, dispositions tipadas, promesas, callbacks, agentes, estadísticas, rotación de claves de API y llamadas entrantes (rutas, menús IVR, colas).	API REST
Referencia de la API (generada)	La referencia completa de endpoints, generada en la compilación a partir de la especificación OpenAPI de core, más guías para el cliente sobre autenticación, errores, webhooks y límites.	Referencia de la API (en inglés)
Colección de Postman	27 carpetas sobre /v1, importables: vendorizada desde el harness de integración y publicada sin la credencial local.	Postman
WebSocket del piso en vivo (/v1/ws)	Entrega por push de presencia de agentes, ciclo de vida de llamadas, estadísticas de pacing y eventos de promesas, sin sondeo.	Eventos WebSocket
Webhooks salientes (/v1/webhooks)	Push de servidor a servidor de hechos de llamadas, promesas, SMS y grabaciones a tu propio endpoint: firmados, reintentados y deduplicados por id de entrega. Disponibles en core desde v0.36.0: están en la Referencia de la API.	Webhooks salientes
SMS y plantillas	Plantillas aprobadas (/v1/sms-templates), aplicación de la política de plantillas, hilos de bandeja conversacional (/v1/sms/threads) y respuestas automáticas fuera de horario. Disponible en core desde v0.94.0.	Mensajería SMS
Canal de correo	Direcciones ligadas a su procedencia, supresión de solo-anexar, plantillas aprobadas, email_blast, eventos firmados del proveedor y baja con un clic. Disponible en core desde v0.97.0 y apagado por defecto en cada tenant.	Canal de email
Repo de contratos	Los esquemas Protobuf dialer.v1 que usan los planos internos de la plataforma.	Contratos
Roadmap	Superficies diseñadas pero aún no implementadas (reportes protojson, …).	Roadmap

URL base y entornos

https://api.usa.dialerdigital.com     # production (US region ingress)
http://127.0.0.1:4000                # local stack (dd/integration-tests)

La API escucha en el puerto 4000 (API_PORT). Las métricas de Prometheus se sirven aparte en el puerto 9568 (GET /metrics, sin autenticación) y nunca se exponen por el ingress público de la API.

Todos los ejemplos de esta documentación usan los datos semilla del stack local: tenant local-dev, campaña local-demo, extensión de agente 1000 y el bearer token de la semilla (localdev-m2-demo-token en el stack de integration-tests).

Convenciones

La API sigue un conjunto pequeño de reglas, de forma consistente:

JSON de entrada, JSON de salida

Los cuerpos de petición y de respuesta son JSON. Se rechazan los cuerpos de petición de más de 8 MiB. Un Content-Type incorrecto en una petición con cuerpo devuelve 415 unsupported_media_type.

El sobre de error

Toda respuesta de error tiene la misma forma:

{
  "error": {
    "code": "conflict",
    "message": "campaign cannot transition from completed to running"
  }
}

code es una cadena estable y legible por máquina; message es legible por personas y puede cambiar. Ramifica por code, nunca por message. El conjunto completo de códigos:

error.code	HTTP habitual	Significado
bad_request	400	JSON mal formado, parámetros de consulta incorrectos, tipos de campo erróneos (se rechaza cerrando por seguridad).
invalid	400	El registro viola un invariante del dominio (validación a nivel de changeset).
unauthorized	401	Clave de API ausente, desconocida o revocada.
forbidden	403	El tenant está suspendido.
not_found	404	El recurso no existe para este tenant: los ids de otro tenant también caen aquí.
conflict	409	Violación de unicidad o de la máquina de estados (nombre de campaña duplicado, transición de ciclo de vida inválida, asiento ocupado).
unprocessable	422	Una violación de contrato tipado (p. ej. el contrato de promesa de pago, las reglas de callbacks, los filtros de rewind reservados).
unsupported_media_type	415	Cuerpo que no es JSON.
internal	500	Fallo del lado del servidor; reintenta con backoff e informa el X-Request-ID.

Ids de petición

Toda respuesta lleva la cabecera X-Request-ID. Si envías la tuya se propaga (cuando es razonable); si no, se asigna una. Inclúyela en los tickets de soporte: enlaza directamente con los logs estructurados.

Tenancy

La autenticación es una clave de API por tenant: la clave es el tenant. La API nunca acepta un id de tenant por ruta, query ni cuerpo: no existe la cabecera X-Tenant-ID. Los ids de otro tenant siempre se leen como 404 not_found; la existencia de un recurso nunca se filtra. Detalles en Autenticación.

Marcas de tiempo

RFC 3339 / ISO-8601 en UTC: 2026-06-11T14:30:00Z. Las horas del día (ventanas de llamada) son HH:MM:SS. Los parámetros de consulta que reciben rangos de tiempo (from, to) esperan RFC 3339.

Las dispositions son cadenas en minúsculas

Las dispositions del motor son cadenas snake_case en minúsculas (answered_human, abandoned, delivered, ai_conversation, answered_machine, ai_stream_lost, busy, no_answer, canceled, rejected, failed). Desde core v0.73.0, una llamada contestada sin puente a un agente es abandoned solo cuando se esperaba un agente: ver llamadas contestadas sin puente. La correspondencia con la nomenclatura del enum Protobuf dialer.v1 (DISPOSITION_*) es un seguimiento de alineación de contratos: ver el Roadmap.

Límites de uso

Cada clave de API de tenant tiene su propia cuota de peticiones en /v1 (publicada en core v0.86.0 (publicada como v0.86.0-prod-0.1)), y los pipelines de marcación y de SMS aplican frenos de ritmo y topes de gasto mensual (429 throttled, 429 sms_spend_cap_exceeded): ver Rate limits & caps (en inglés). Sé un buen ciudadano: pagina con cursores keyset en lugar de abusar de valores altos de limit, y prefiere el flujo WebSocket al sondeo.

Versionado

La API REST se versiona en la ruta: /v1/.... Las adiciones compatibles hacia atrás (campos nuevos, endpoints nuevos) ocurren dentro de v1; los cambios incompatibles requieren /v2. El paquete Protobuf dialer.v1 evoluciona solo de forma compatible hacia atrás: ver Contratos.

Un recorrido de 60 segundos

TOKEN=localdev-m2-demo-token            # local stack seed; production keys look like dd_...
API=http://127.0.0.1:4000

# 1. Liveness (no auth)
curl -s $API/healthz
# -> {"status":"ok","service":"dialer-core","version":"0.2.0"}

# 2. Who am I? (validates the key)
curl -s $API/v1/me -H "Authorization: Bearer $TOKEN"
# -> {"tenant":{"id":"...","name":"local-dev","status":"active","seats":5,...}}

# 3. List campaigns (the seed ships "local-demo")
curl -s $API/v1/campaigns -H "Authorization: Bearer $TOKEN"

# 4. Pull today's call attempts (append-only CDR, keyset-paginated)
curl -s "$API/v1/call_attempts?from=2026-06-11T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $TOKEN"

Continúa con Autenticación.

Más guías en español

• Constructor de reportes
• Inteligencia post-llamada
• Evaluación de calidad con IA
• Copiloto en vivo
• Analítica de producto y NPS