Guía para desarrolladores de API de Robotalker: automatice llamadas y SMS desde su aplicación

🔑 Conclusiones clave:

  • La API de Robotalker utiliza convenciones REST estándar con cargas útiles JSON: cualquier lenguaje o marco que pueda realizar solicitudes HTTP puede integrarse con él.
  • Los webhooks son el patrón recomendado para recibir el estado de entrega y los eventos de mensajes entrantes; Se desaconseja sondear la API para determinar su estado a escala.
  • Los números de teléfono deben estar en formato E.164 (+12125550100) para todas las llamadas API; la normalización en la capa de aplicación antes de pasar a la API evita los errores de solicitud más comunes.

La API de Robotalker le permite activar llamadas automatizadas y mensajes SMS directamente desde su aplicación, CRM, sistema de programación o flujo de trabajo personalizado, sin cargas manuales ni programación por lotes a través de una interfaz de usuario. Esta guía cubre los conceptos y patrones que los desarrolladores necesitan para pasar de cero a la integración en producción.

Autenticación

Todas las solicitudes de API se autentican mediante una clave API pasada en el encabezado de la solicitud. Su clave API está disponible en el panel de su cuenta de Robotalker en Configuración → API.

Encabezado de autenticación
Authorization: Bearer YOUR_API_KEY

Incluya este encabezado en cada solicitud de API. Las solicitudes sin una clave API válida devuelven HTTP 401 no autorizado.

Puntos finales de API principales

Punto final Método Propósito
/api/v1/calls PUBLICAR Iniciar una única llamada saliente o una campaña por lotes
/api/v1/calls/{id} OBTENER Recuperar el estado y el resultado de una llamada específica
/api/v1/campaigns PUBLICAR Cree y programe una campaña de transmisión de voz masiva
/api/v1/campaigns/{id} OBTENER Recuperar el estado de la campaña y agregar estadísticas de entrega
/api/v1/sms PUBLICAR Envíe un solo SMS o un lote de SMS masivos
/api/v1/contacts PUBLICAR / OBTENER Crear, recuperar y administrar contactos y estados de exclusión voluntaria

Envío de una única llamada automatizada

POST /api/v1/calls — Cuerpo de la solicitud
{
  "to": "+12125550100",
  "from": "+18005550199",
  "message": "Hello {FIRST_NAME}, this is a reminder about your appointment on {APPT_DATE} at {APPT_TIME}. Press 1 to confirm or 2 to reschedule.",
  "voice": "en-US-Neural-F",
  "variables": {
    "FIRST_NAME": "Sarah",
    "APPT_DATE": "Tuesday, April 15th",
    "APPT_TIME": "3:15 PM"
  },
  "dtmf": {
    "1": {"action": "webhook", "url": "https://yourapp.com/confirm"},
    "2": {"action": "webhook", "url": "https://yourapp.com/reschedule"},
    "9": {"action": "optout"}
  },
  "webhook_url": "https://yourapp.com/call-status"
}
Respuesta
{
  "call_id": "cal_9x7k2m4p",
  "status": "queued",
  "to": "+12125550100",
  "created_at": "2025-04-15T10:30:00Z"
}

La llamada se pone en cola inmediatamente. Utilice el call_id para recuperar el estado o confiar en el webhook para obtener actualizaciones basadas en eventos.

Recibir el estado de entrega a través de Webhooks

Registrar un webhook_url en su llamada o solicitud de campaña para recibir eventos de estado en tiempo real. Robotalker envía una POST HTTP a su punto final cuando se activa cada evento:

Carga útil del evento de webhook (llamada completada)
{
  "event": "call.completed",
  "call_id": "cal_9x7k2m4p",
  "to": "+12125550100",
  "status": "answered",
  "duration_seconds": 28,
  "dtmf_response": "1",
  "amd_result": "human",
  "timestamp": "2025-04-15T10:30:45Z"
}

Tipos de eventos clave que su webhook debe manejar:

  • call.completed — Llamada finalizada; incluye estado de respuesta, duración, respuesta DTMF
  • call.no_answer — La llamada sonó pero no fue respondida.
  • call.voicemail — AMD detectó correo de voz; mensaje dejado o colgado según configuración
  • call.failed — No se pudo realizar la llamada (número no válido, falla del operador)
  • contact.optout — El destinatario presionó la tecla de exclusión voluntaria o respondió DETENER

Manejo de errores y límites de velocidad

La API devuelve códigos de estado HTTP estándar:

  • 200/201: Éxito
  • 400: Solicitud incorrecta: JSON con formato incorrecto, formato de número de teléfono no válido, falta un campo obligatorio
  • 401: Error de autenticación: clave API no válida o faltante
  • 429: Se superó el límite de velocidad: implementar una reducción exponencial y volver a intentarlo
  • 500: Error del servidor: reintente con retroceso; registro para la investigación

Los límites de tarifas varían según el plan. Consulte el panel de su cuenta para conocer los límites de tarifas actuales. Para envíos masivos de campañas, utilice el/api/v1/campaignsPunto final por lotes en lugar de solicitudes de llamada única en bucle: los puntos finales por lotes manejan la limitación interna y son más eficientes a escala.

Cree llamadas automatizadas en su aplicación

Obtenga su clave API de Robotalker y comience a enviar llamadas y SMS automatizados desde su aplicación hoy, sin necesidad de compromiso a largo plazo.

  • ✔️ API RESTful con cargas útiles JSON
  • ✔️ Entrega de webhook para manejo de eventos en tiempo real
  • ✔️ Soporte de variables dinámicas para mensajes personalizados
Obtenga acceso API →

Preguntas frecuentes: API de Robotalker

Cualquier lenguaje que pueda realizar solicitudes HTTP funciona con la API REST: Python, Node.js, PHP, Ruby, Java, C#, Go y otros. No hay ningún requisito de SDK; solo necesitas una biblioteca HTTP y serialización JSON. Si está utilizando un marco popular, existen ejemplos comunitarios para la mayoría de las pilas. La API sigue las convenciones REST estándar, por lo que cualquier desarrollador familiarizado con la integración REST será productivo rápidamente.

Utilice la API con sus propios números de teléfono verificados durante el desarrollo: las llamadas a números que usted controla le permiten verificar el flujo completo sin poner en riesgo a los contactos de su lista de producción. Para las pruebas de webhook, herramientas como ngrok o webhook.site le permiten exponer un punto final local para recibir eventos de webhook durante el desarrollo sin implementarlo en un servidor. Comience con solicitudes de API de llamada única antes de probar campañas masivas para detectar cualquier problema de configuración con anticipación.

Artículos relacionados