VoiceAgents para llamadas salientes

En este artículo aprenderás a configurar y utilizar la función VoiceAgent de CloudTalk para las llamadas salientes. La guía explica cómo activar llamadas automatizadas y gestionar conversaciones sin que intervengan agentes humanos.

Nivel de usuario: Administrador

VoiceAgent para llamadas salientes permite a los equipos automatizar las interacciones salientes con los clientes iniciando llamadas mediante agentes impulsados por IA. Es ideal para tareas como seguimientos, confirmaciones de citas, encuestas o notificaciones proactivas: libera a los agentes humanos para conversaciones más complejas y aumenta la eficiencia operativa.

💡 ¿Prefieres gestionar las llamadas entrantes con automatización? Consulta la guía VoiceAgent para llamadas entrantes y descubre cómo utilizar los VoiceAgents en escenarios de llamadas entrantes.

Cómo funciona

Las llamadas salientes que utilizan VoiceAgent se inician a través del endpoint de VoiceAgents de la API de CloudTalk. Cuando hay que ejecutar una llamada, normalmente se envía una solicitud desde una herramienta externa o un CRM a la API con los datos necesarios de la persona a la que se va a contactar. Estos datos suelen incluir el número de teléfono del destinatario y cualquier información contextual que el VoiceAgent deba utilizar durante la conversación. El VoiceAgent consulta durante la interacción los datos de la llamada enviados en la solicitud a la API, lo que le permite responder y comportarse según lo definido en la configuración del VoiceAgent. Todo el proceso está automatizado y no requiere la intervención de un agente humano, lo que permite una comunicación saliente eficiente y escalable.

Cómo activar llamadas salientes del VoiceAgent a través de la API

En esta sección se explica cómo activar llamadas salientes del VoiceAgent con la API de CloudTalk, incluidos los pasos de configuración clave necesarios para garantizar una ejecución y una gestión de datos correctas.

Requisitos previos

La funcionalidad VoiceAgents activada en tu CloudTalk Dashboard.
Un VoiceAgent de llamadas salientes configurado en tu cuenta. Puedes crearlo:
- seleccionando una plantilla que incluya la Dirección de llamada saliente
- creando un VoiceAgent personalizado y seleccionando la Dirección de llamada saliente.

Implementación

En lugar de iniciar las llamadas manualmente, las llamadas salientes del VoiceAgent se inician a través de la API de CloudTalk, normalmente como parte de una automatización de flujos de trabajo con:

HubSpot Workflows
Zapier
Make
Tus sistemas internos
Automatizaciones basadas en Webhook

Configura tu solicitud a la API siguiendo estas instrucciones:

En la herramienta que prefieras, define el endpoint de la solicitud a la API. Empieza por especificar el endpoint de destino de la solicitud:
POST https://api.cloudtalk.io/v1/voice-agent/calls
En los encabezados de la configuración, configura el encabezado Authorization.
Authorization: Basic BASE64(api_key_id:api_key)
La API de CloudTalk utiliza autenticación básica, donde
- api_key_id : es el ID de tu clave de API en CloudTalk Dashboard > Configuración > Claves de API > Detalle de la clave de API > ID
- api_key es tu clave de API sin procesar en CloudTalk Dashboard > Configuración > Claves de API > Detalle de la clave de API > Clave
En el cuerpo de la solicitud, configura los campos obligatorios.
1. call_number - número de teléfono al que llamará el voiceagent en formato E.164
2. voice_agent_id - el ID del VoiceAgent. Puedes obtenerlo en CloudTalk Dashboard → VoiceAgents -> Agentes. Abre el detalle del VoiceAgent que quieras y copia el ID de la URL de esa página.
3. call_properties que contiene
  1. variables de system_prompt - se envían al system prompt del VoiceAgent y son visibles para la IA durante la llamada. Úsalas para personalizar la llamada (p. ej., #{{name}}, #{{order_id}}). Solo son necesarias si utilizas variables en la configuración del VoiceAgent.
  2. variables de output - se incluyen en el payload del Webhook de análisis de llamadas.

⚠️ Incluye el objeto system_prompt y el objeto output en la solicitud a la API solo si realmente utilizas variables en el prompt del VoiceAgent.

Ejemplo de solicitud a la API:

curl \--location 'https://api.cloudtalk.io/v1/voice-agent/calls' \--header 'Content-Type: application/json' \--header 'Authorization: Basic dfjag57df********f5gdf4gs4dgd' \--data '{  "call_number": "+421 903 123 123",  "voice_agent_id": "67eaa636148d700a8dmckaf1",  "call_properties": {    "system_prompt": {      "variables": {        "name": "John"      }    },    "output": {      "variables": {        "customer_id": 12345      }    }  }}'

Diferencias entre las variables de system prompt y las variables de output

Al configurar una llamada de VoiceAgent a través de la API, puedes incluir dos tipos de variables para enriquecer la conversación y facilitar el procesamiento posterior a la llamada:

variables de system prompt
variables de output.

Cada tipo de variable cumple una función distinta en el flujo de trabajo del VoiceAgent y debe utilizarse en consecuencia.

Variables de system prompt

⚠️ Las variables de contacto no funcionan en los agentes de llamadas salientes. Variables como #{{contact.name}} o #{{caller_number}} se completan automáticamente solo en los agentes de llamadas entrantes. En los agentes de llamadas salientes defines tus propias variables personalizadas y envías sus valores en la solicitud a la API, como se describe a continuación. Consulta VoiceAgents para llamadas entrantes para la personalización en llamadas entrantes.

Las variables de system prompt son visibles para la IA durante la llamada y ayudan a personalizar la conversación o a aportar el contexto esencial para el VoiceAgent. Inserta las variables en tu prompt con dobles llaves (#{{ }}). Ejemplo de saludo:

Hello #{{name}}, I'm calling to confirm your order number #{{order_id}} placed on #{{order_date}}.

Al enviar la solicitud a la API, asegúrate de incluir estas variables en el objeto system_prompt.variables del cuerpo de la solicitud. Por ejemplo:

"system_prompt": {
  "variables": {
    "name": "Alex",
    "order_id": "123456",
    "order_date": "2025-05-18"
  }
}

Si una variable aparece en el prompt pero no se envía en la solicitud a la API, el VoiceAgent no podrá utilizarla, lo que puede provocar errores o empeorar la experiencia del usuario.

Variables de output

Las variables de output no son visibles para la IA durante la llamada. En su lugar, sirven para adjuntar a la conversación metadatos o contexto que estarán disponibles en el análisis de la llamada y en la extracción de información una vez finalizada la llamada. Estas variables se envían con la solicitud a la API y se incluyen en el payload del webhook, lo que permite a tus sistemas procesar el resultado de la llamada con todo el contexto, aunque el VoiceAgent no haya utilizado estos datos en la conversación. Ejemplo Supongamos que tu habilidad Extraer información está configurada así:

En tu solicitud a la API incluyes una variable de output para transmitir contexto externo (en este caso, customer_id):

"output": {  "variables": {    "customer_id": 12345  }}

Este valor no es visible para el VoiceAgent durante la llamada, pero sí se incluye en el payload del webhook que se envía cuando termina la llamada. El payload completo del webhook tiene este aspecto:

{  "data": {    "ct_call_context": {      "uuid": "160f677d-d2f2-419d-822d-b45f33e4fe6c",      "status": "Connected",      "datetime": "2026-06-17T08:38:31Z",      "duration": 23    },    "message_left_by_caller": {      "caller_name": null,      "content": null    },    "customer_id": 12345,    "Summary": "The caller confirmed they want a callback tomorrow morning.",    "Callback_Confirmed": true  }}

💡 Ahora todos los payloads de webhook incluyen un objeto ct_call_context con el UUID, el estado, la hora de inicio y la duración de la llamada. Puedes usar el campo uuid para localizar la llamada en CloudTalk o asociarla con registros de tu CRM o de tu data warehouse. Consulta Habilidades del VoiceAgent – Extraer información para ver la referencia completa del payload.

Así puedes enriquecer la automatización o los informes posteriores a la llamada con contexto adicional que nunca formó parte de la conversación hablada.

Combinando los dos tipos de variables, puedes crear conversaciones muy personalizadas durante la llamada y mantener todo el contexto operativo después, sin sobrecargar a la IA con datos innecesarios.

¿Necesitas ayuda o tienes alguna pregunta? Escríbenos a través de nuestro Portal de atención al cliente — estamos aquí para ayudarte.

Primeros pasos

Números y portabilidad

IA

AI Sales Dialer

CloudTalk Phone y Go

Mensajería

Dashboard

Integraciones

Facturación y suscripción

Novedades y actualizaciones técnicas

Dashboard antiguo

VoiceAgents para llamadas salientes