SalescalingDocs
DemoApp

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
emailstringDirección de email válida
phoneNumberstringNúmero de teléfono en formato E.164 (ej: +1234567890)

Campos Opcionales

CampoTipoDescripción
dynamicVariablesobjectVariables dinámicas para personalizar el prompt del agente

Ejemplo de Payload

json
{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phoneNumber": "+1234567890",
  "dynamicVariables": {
    "company.name": "Acme Inc",
    "contact.jobTitle": "CEO"
  }
}

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",
    "phoneNumber": "+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",
      phoneNumber: "+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",
    "phoneNumber": "+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",
    "phoneNumber" => "+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 con información específica del contacto o empresa.

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",
  "phoneNumber": "+1234567890",
  "dynamicVariables": {
    "company.name": "Acme Inc",
    "company.industry": "Technology",
    "company.size": "50-100 employees"
  }
}

Nota: Las variables dinámicas proporcionadas deben coincidir con las configuradas en el voice agent. Si proporcionas una variable no configurada, recibirás un error 400.

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