Ir al contenido principal
Integraciones

Cómo iniciar campañas de salida a partir de un disparador de API

Esta guía explica cómo activar llamadas salientes individuales a través de la API, lo que permite iniciar una llamada cuando se produce un evento en tu sistema.

Escrito por Product

Última actualización Hace 3 meses

Descripción general

A diferencia de las campañas por lotes, en las que se carga una lista y se inician todas las llamadas, los disparadores de la API te permiten iniciar una sola llamada en tiempo real. Cuando se produce un evento en tu sistema (nuevo cliente potencial, pedido completado, cita creada), tu aplicación llama a la API DeepAgent y el agente llama inmediatamente al contacto.

Esta guía aborda el caso de uso más habitual. La referencia completa y siempre actualizada de todos los puntos de conexión se encuentra en Documentación de la API de DeepAgent.

Casos de uso típicos

Cliente potencial en tiempo real: un cliente potencial rellena un formulario en la web y el agente le llama en un plazo de 30 segundos para calificarlo.

Confirmación de pedido: el cliente completa una compra, el agente llama para confirmar los detalles y proponer ventas adicionales.

Recordatorio de cita: 24 horas antes de una cita, el sistema gestiona activa una llamada de confirmación.

Alertas y notificaciones: un sistema de supervisión detecta un problema; el agente llama al responsable para avisarle.

Requisitos previos

Para utilizar los desencadenantes de la API, debes disponer de:

  1. Un agente de llamadas salientes configurado y activo

  2. Un número de teléfono asignado al agente

  3. Una clave de API DeepAgent con el ámbito calls:write (se genera desde Configuración > API)

Punto de conexión de la API

El punto de conexión para iniciar una llamada saliente es:

POST https://platform.deepagent.app/api/v1/calls

Encabezados necesarios

Authorization: Bearer da_<env>_<key_id>_<secret>Content-Type: application/jsonIdempotency-Key: <stringa univoca per ogni richiesta>

Idempotency-Key es obligatorio. Sirve para evitar que un reintento tras un tiempo de espera haga que el teléfono de un cliente suene dos veces: la misma clave y el mismo cuerpo devuelven la respuesta original; la misma clave con un cuerpo diferente devuelve un 409. Utiliza un UUID generado por tu sistema.

También existe un encabezado opcional, X-Workspace-Id, para indicar el espacio de trabajo en el que se va a operar. Debe omitirse si la clave solo tiene uno; solo se admite para las claves con delegación de socio.

Cuerpo de la solicitud

{  "agent_id": "6f1c9a24-8b3d-4f7a-9c25-1d0e7a3b5c88",  "to": "+393331234567",  "variables": {  "nome": "Mario",  "cognome": "Rossi",  "prodotto": "Piano Premium",  "scadenza": "28/02/2026"  } }

agent_id (obligatorio): el UUID del agente que debe realizar la llamada. Debe estar activo y tener un número asignado; de lo contrario, la llamada no se realizará. Lo encontrarás en la página de detalles del agente.

to (obligatorio): el número al que llamar en formato E.164, es decir, con el + y el prefijo internacional. Si el número figura en la lista de exclusiones, la llamada se rechaza.

variables: las variables dinámicas que utilizará el agente durante la llamada. Deben coincidir con los marcadores de posición del mensaje de voz del agente y los valores deben ser cadenas de caracteres: los números y los valores booleanos deben convertirse antes de enviarlos.

phone_number_id (opcional): el número desde el que se realiza la llamada. Si se omite, se utiliza el asignado al agente.

skip_time_check (opcional, por defecto false): omite la franja horaria configurada para el agente. Si se deja en false, se evitan las llamadas fuera de horario, lo cual supone un problema de cumplimiento normativo más que de cortesía.

Respuesta

Si se realiza correctamente, recibirás un 202 Accepted:

{  "data": {  "id": "9d84a1f0-52c7-4a1e-9f33-0b6e2c7d4411",  "status": "queued",  "agent_id": "6f1c9a24-8b3d-4f7a-9c25-1d0e7a3b5c88",  "phone_number_id": "b27f5e13-90aa-4c6d-8e21-77c4d9f0a562"  } }

La respuesta llega antes de que suene el teléfono: el estado es siempre «queued». Utiliza «data.id» junto con «GET /v1/calls/{id}» para realizar un seguimiento del resultado de la llamada.

Integraciones habituales

Desde un formulario web

Cuando un usuario rellena un formulario de contacto, tu backend puede iniciar inmediatamente una llamada:

// Esempio Node.js app.post('/contact-form', async (req, res) => {  const { nome, telefono, interesse } = req.body;   await fetch('https://platform.deepagent.app/api/v1/calls', {  method: 'POST',  headers: {  'Authorization': 'Bearer ' + process.env.DEEPAGENT_API_KEY,  'Content-Type': 'application/json',  'Idempotency-Key': crypto.randomUUID()  },  body: JSON.stringify({  agent_id: '6f1c9a24-8b3d-4f7a-9c25-1d0e7a3b5c88',  to: telefono,  variables: { nome, interesse }  })  });   res.json({ message: 'Ti richiamiamo subito!' }); });

Desde n8n

Crea un flujo de trabajo de n8n con un nodo «HTTP Request» que llame a la API DeepAgent. Puedes activar el flujo de trabajo desde cualquier evento: nuevo registro en Airtable, nuevo pedido en WooCommerce, nuevo ticket en Zendesk.

Configuración del nodo «HTTP Request»:

  • Método: POST

  • URL: https://platform.deepagent.app/api/v1/calls

  • Autenticación: token de portador

  • Encabezado adicional: Idempotency-Key, con el ID del registro que ha activado el flujo de trabajo

  • Cuerpo: JSON con agent_id, to y variables asignados desde los nodos anteriores

Desde Zapier / Make

Utiliza la acción «Webhook» para llamar a la API DeepAgent cuando se produzca un desencadenante en otra aplicación.

Desde CRM (HubSpot, Salesforce, Pipedrive)

Configura un flujo de trabajo en el CRM para que, cuando un cliente potencial entre en una fase determinada, se active un webhook. El webhook puede ser un punto final propio que, a su vez, llame a la API DeepAgent, o bien puedes utilizar n8n/Zapier como intermediario.

Webhook de callback

Puedes recibir una notificación cuando finalice la llamada suscribiéndote a un webhook. Los eventos disponibles son call.completed, call.failed, campaign.completed, recall.scheduled, message.received y contact.created.

El punto final de destino debe estar en https, ya que la carga útil contiene datos de tus clientes. Al crear la suscripción, recibirás un secret, que solo se muestra una vez: sirve para verificar la firma X-DeepAgent-Signature de cada entrega, en el formato t=<epoch>,v1=<hmac-sha256 di "<t>.<body>">. Comprueba siempre la firma antes de procesar el contenido: sin ese control, tu punto final aceptará cualquier solicitud POST que llegue desde Internet.

La estructura exacta de la carga útil de cada evento se encuentra en documentación de la API. Con estos datos puedes actualizar tu CRM, notificar al equipo de ventas o activar otras automatizaciones en función del resultado.

Gestión de colas y límites de frecuencia

La API está sujeta a límites de frecuencia: si se superan, recibirás un 429 Too Many Requests. Implementa un reintento con retroceso exponencial, reutilizando la misma Idempotency-Key de la solicitud original, de modo que un reintento no genere una segunda llamada.

Las llamadas se ponen en cola y se procesan por orden. Si el agente ya está atendiendo una llamada, las nuevas esperan a que se libere: tenlo en cuenta si inicias muchas en poco tiempo.

Gestión de errores

Cada error responde con un objeto error que contiene code (el código estable sobre el que escribir la lógica), message (en inglés, puede cambiar entre versiones: no lo compares en el código), details y request_id. Indica siempre el request_id cuando notifiques un problema al servicio de asistencia: es lo que permite localizar la solicitud en los registros.

400 Bad Request: faltan parámetros o el formato es incorrecto. Comprueba agent_id y el formato E.164 de to.

401 Unauthorized: clave de API ausente, no válida o revocada.

403 Forbidden: la clave no tiene el ámbito calls:write o no está autorizada en el espacio de trabajo solicitado.

409 Conflicto: has reutilizado una Idempotency-Key con un cuerpo diferente.

429 Demasiadas solicitudes: se ha superado el límite de frecuencia; vuelve a intentarlo con un tiempo de espera.

500 Internal Server Error: problema en el lado de DeepAgent; vuelve a intentarlo o ponte en contacto con el servicio de asistencia a través de request_id.

Supervisión

Todas las llamadas iniciadas a través de la API aparecen en el Historial de llamadas. Puedes filtrarlas para ver solo aquellas activadas mediante programación.

A través de la API, GET /v1/calls/{id} devuelve los detalles de cada llamada, mientras que GET /v1/calls/{id}/transcript y GET /v1/calls/{id}/recording proporcionan la transcripción y la grabación. Utiliza estos datos para analizar el rendimiento y optimizar el agente.

Buenas prácticas

Valida primero el número: comprueba que cumpla el formato E.164 antes de llamar a la API. Los números mal formados consumen una solicitud sin realizar la llamada.

Genera una clave de idempotencia determinista: utilizando el ID del registro de origen (cliente potencial, pedido, cita) evitarás llamadas duplicadas, incluso si tu sistema vuelve a intentarlo.

Respeta los consentimientos: inicia llamadas solo a números que hayan dado su consentimiento y lleva un registro de los mismos en tu sistema.

Limita los reintentos automáticos: si un número no responde, no vuelvas a intentarlo inmediatamente. Utiliza una lógica de retroceso (backoff) o programa un reintento manual.

Registra todo: guarda las respuestas de la API, incluido el «request_id», para la depuración y las auditorías.

Prueba primero: antes de conectar la API al sistema de producción, realiza pruebas con números de prueba para comprobar que todo funciona correctamente.