Voice Agent Webhook

El webhook de Voice Agent permite iniciar llamadas desde aplicaciones externas de forma programática.

Endpoint

text
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

text
Content-Type: application/json
x-api-key: tu_api_key_aqui

Crear una API Key

  1. Ve a Configuración → API Keys
  2. Haz clic en "Nueva API Key"
  3. Asigna un nombre descriptivo
  4. Selecciona el scope "Voice Agents: Webhook"
  5. Opcionalmente, establece una fecha de expiración
  6. Haz clic en "Crear API Key"
  7. Importante: Copia la clave inmediatamente, solo se mostrará una vez

Payload

Campos Requeridos

CampoTipoDescripción
namestringNombre completo del contacto
phonestringNúmero de teléfono en formato E.164 (ej: +1234567890)

Campos Opcionales

CampoTipoDescripción
emailstringDirección de email válida
dynamicVariablesobjectVariables dinámicas de la llamada. Solo las que empiezan por demo_ se reenvían al agente (ver Variables Dinámicas)

Ejemplo de Payload

json
{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "dynamicVariables": {
    "demo_sector": "dental",
    "demo_tone": "friendly"
  }
}

Respuesta

Respuesta Exitosa (201 Created)

json
{
  "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

CampoTipoDescripción
callIdstringID único de la llamada creada
statusstringEstado de la llamada (queued, ringing, in_progress, completed, failed, cancelled)
contactIdstringID del contacto asociado a la llamada
phoneNumberstringNúmero de teléfono que será llamado
createdAtstringFecha y hora de creación de la llamada en formato ISO 8601

Códigos de Estado

CódigoDescripción
201Llamada iniciada exitosamente
400Payload inválido o voice agent inactivo
401API Key inválida o faltante
403API Key sin el scope requerido
404Voice agent no encontrado
500Error interno del servidor

Errores Comunes

400 Bad Request

Payload inválido:

json
{
  "data": null,
  "error": "Phone number must be in E.164 format (e.g., +1234567890)",
  "statusCode": 400
}

Voice agent inactivo:

json
{
  "data": null,
  "error": "Voice agent My Agent is not active",
  "statusCode": 400
}

Variables dinámicas inválidas:

json
{
  "data": null,
  "error": "Invalid dynamic variables: invalid.variable. Available variables: company.name, contact.name, contact.email",
  "statusCode": 400
}

401 Unauthorized

json
{
  "statusCode": 401,
  "message": "Invalid API Key"
}

403 Forbidden

json
{
  "statusCode": 403,
  "message": "Missing required scopes: voice-agents:webhook"
}

404 Not Found

json
{
  "data": null,
  "error": "Voice agent with ID 123e4567-e89b-12d3-a456-426614174000 not found",
  "statusCode": 404
}

Ejemplos de Código

cURL

bash
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

javascript
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

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
<?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) devuelve 400.

Variables Estándar

Estas variables están siempre disponibles:

  • contact.name - Nombre completo del contacto
  • contact.email - Email del contacto
  • contact.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:

json
{
  "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

  1. Almacena tu API Key de forma segura: Nunca la incluyas en código versionado
  2. Usa variables de entorno: Almacena la API Key en variables de entorno
  3. Maneja errores apropiadamente: Implementa reintentos con backoff exponencial
  4. Valida el formato del teléfono: Asegúrate de que el número esté en formato E.164 antes de enviar
  5. Monitorea el estado de las llamadas: Usa el callId retornado para hacer seguimiento
  6. Respeta los límites: No excedas el límite de llamadas simultáneas

Soporte

Si tienes problemas con el webhook:

  1. Verifica que tu API Key tenga el scope correcto
  2. Confirma que el voice agent esté activo
  3. Valida el formato del payload
  4. Revisa los logs de error para más detalles

Para más ayuda, contacta con soporte en support@salescaling.com