Voice Agent Webhook
El webhook de Voice Agent permite iniciar llamadas desde aplicaciones externas de forma programática.
Endpoint
POST /api/v1/voice-agents/{id}/webhook
Autenticación
Este endpoint requiere autenticación mediante API Key con el scope voice-agents:webhook.
Headers Requeridos
Content-Type: application/json
x-api-key: tu_api_key_aqui
Crear una API Key
- Ve a Configuración → API Keys
- Haz clic en "Nueva API Key"
- Asigna un nombre descriptivo
- Selecciona el scope "Voice Agents: Webhook"
- Opcionalmente, establece una fecha de expiración
- Haz clic en "Crear API Key"
- Importante: Copia la clave inmediatamente, solo se mostrará una vez
Payload
Campos Requeridos
| Campo | Tipo | Descripción |
|---|---|---|
name | string | Nombre completo del contacto |
phone | string | Número de teléfono en formato E.164 (ej: +1234567890) |
Campos Opcionales
| Campo | Tipo | Descripción |
|---|---|---|
email | string | Dirección de email válida |
dynamicVariables | object | Variables dinámicas de la llamada. Solo las que empiezan por demo_ se reenvían al agente (ver Variables Dinámicas) |
Ejemplo de Payload
{
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+1234567890",
"dynamicVariables": {
"demo_sector": "dental",
"demo_tone": "friendly"
}
}
Respuesta
Respuesta Exitosa (201 Created)
{
"data": {
"callId": "123e4567-e89b-12d3-a456-426614174000",
"status": "queued",
"contactId": "123e4567-e89b-12d3-a456-426614174001",
"phoneNumber": "+1234567890",
"createdAt": "2024-01-20T10:30:00Z"
},
"error": null,
"statusCode": 201,
"count": 1
}
Campos de Respuesta
| Campo | Tipo | Descripción |
|---|---|---|
callId | string | ID único de la llamada creada |
status | string | Estado de la llamada (queued, ringing, in_progress, completed, failed, cancelled) |
contactId | string | ID del contacto asociado a la llamada |
phoneNumber | string | Número de teléfono que será llamado |
createdAt | string | Fecha y hora de creación de la llamada en formato ISO 8601 |
Códigos de Estado
| Código | Descripción |
|---|---|
201 | Llamada iniciada exitosamente |
400 | Payload inválido o voice agent inactivo |
401 | API Key inválida o faltante |
403 | API Key sin el scope requerido |
404 | Voice agent no encontrado |
500 | Error interno del servidor |
Errores Comunes
400 Bad Request
Payload inválido:
{
"data": null,
"error": "Phone number must be in E.164 format (e.g., +1234567890)",
"statusCode": 400
}
Voice agent inactivo:
{
"data": null,
"error": "Voice agent My Agent is not active",
"statusCode": 400
}
Variables dinámicas inválidas:
{
"data": null,
"error": "Invalid dynamic variables: invalid.variable. Available variables: company.name, contact.name, contact.email",
"statusCode": 400
}
401 Unauthorized
{
"statusCode": 401,
"message": "Invalid API Key"
}
403 Forbidden
{
"statusCode": 403,
"message": "Missing required scopes: voice-agents:webhook"
}
404 Not Found
{
"data": null,
"error": "Voice agent with ID 123e4567-e89b-12d3-a456-426614174000 not found",
"statusCode": 404
}
Ejemplos de Código
cURL
curl -X POST "https://api.salescaling.com/api/v1/voice-agents/YOUR_AGENT_ID/webhook" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+1234567890"
}'
JavaScript / Node.js
const response = await fetch(
"https://api.salescaling.com/api/v1/voice-agents/YOUR_AGENT_ID/webhook",
{
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-key": "YOUR_API_KEY"
},
body: JSON.stringify({
name: "John Doe",
email: "john.doe@example.com",
phone: "+1234567890"
})
}
);
const data = await response.json();
console.log("Call initiated:", data);
Python
import requests
url = "https://api.salescaling.com/api/v1/voice-agents/YOUR_AGENT_ID/webhook"
headers = {
"Content-Type": "application/json",
"x-api-key": "YOUR_API_KEY"
}
payload = {
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+1234567890"
}
response = requests.post(url, json=payload, headers=headers)
data = response.json()
print("Call initiated:", data)
PHP
<?php
$url = "https://api.salescaling.com/api/v1/voice-agents/YOUR_AGENT_ID/webhook";
$headers = [
"Content-Type: application/json",
"x-api-key: YOUR_API_KEY"
];
$payload = json_encode([
"name" => "John Doe",
"email" => "john.doe@example.com",
"phone" => "+1234567890"
]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
print_r($data);
?>
Variables Dinámicas
Las variables dinámicas permiten personalizar el prompt del agente. Hoy solo se reenvían a la llamada las variables cuyo nombre empieza por demo_; el resto se validan como se describe más abajo, pero no llegan al agente.
Variables demo_*
Cualquier variable que empiece por demo_ se acepta siempre (también en agentes con atributos de empresa configurados) y se entrega al agente como variable de la llamada. Úsalas en el prompt como {{demo_sector}}.
- Nombre:
demo_seguido de letras minúsculas, números y_(máx. 64 caracteres, sin puntos). - Valor: texto, número o booleano (los dos últimos se convierten a texto), de hasta 2000 caracteres.
- Máximo 30 variables
demo_*por llamada. - Una variable
demo_*mal formada (nombre inválido, valor objeto o array, demasiado larga o demasiadas) devuelve400.
Variables Estándar
Estas variables están siempre disponibles:
contact.name- Nombre completo del contactocontact.email- Email del contactocontact.full_name- Nombre completo del contacto (alias)
Variables Personalizadas
Si has configurado atributos de empresa (companyAttributes) en tu voice agent, puedes usar esas variables en el webhook. Por ejemplo:
{
"name": "John Doe",
"email": "john@example.com",
"phone": "+1234567890",
"dynamicVariables": {
"company.name": "Acme Inc",
"company.industry": "Technology",
"company.size": "50-100 employees"
}
}
Nota: Si el agente tiene atributos de empresa configurados, las variables proporcionadas (salvo las demo_*) deben coincidir con ellas; si proporcionas una no configurada, recibirás un error 400. Estas variables se validan pero no se reenvían a la llamada: los datos del contacto y de la empresa los rellena la plataforma.
Límites y Consideraciones
Límites de Tasa
- Máximo 10 llamadas activas simultáneas por voice agent
- Si se alcanza el límite, recibirás un error 400
Formato de Teléfono
El número de teléfono debe estar en formato E.164:
- Comienza con
+ - Seguido del código de país
- Seguido del número sin espacios ni guiones
- Ejemplo:
+1234567890(USA),+34912345678(España)
Creación de Contactos
Si el contacto no existe en el sistema, se creará automáticamente con la información proporcionada. Si ya existe un contacto con el mismo email, se utilizará ese contacto existente.
Mejores Prácticas
- Almacena tu API Key de forma segura: Nunca la incluyas en código versionado
- Usa variables de entorno: Almacena la API Key en variables de entorno
- Maneja errores apropiadamente: Implementa reintentos con backoff exponencial
- Valida el formato del teléfono: Asegúrate de que el número esté en formato E.164 antes de enviar
- Monitorea el estado de las llamadas: Usa el
callIdretornado para hacer seguimiento - Respeta los límites: No excedas el límite de llamadas simultáneas
Soporte
Si tienes problemas con el webhook:
- Verifica que tu API Key tenga el scope correcto
- Confirma que el voice agent esté activo
- Valida el formato del payload
- Revisa los logs de error para más detalles
Para más ayuda, contacta con soporte en support@salescaling.com