Ir al contenido
ES
Abrir la app

For AI assistants: this page as plain markdown is at https://docs.voicelogica.ai/raw/es/outbound-calls/api.md, and https://docs.voicelogica.ai/llms.txt lists the docs by topic, one file each, small enough to read whole. Read those rather than this HTML page.

API

6 min de lectura
Copiar como Markdown
Ver como MarkdownAbrir el archivo .md.md

Una llamada saliente desde su sistema: un evento de CRM, un formulario, una devolución de llamada perdida. Una lista en un horario es Campaigns, no este endpoint.

La configuración de Outgoing del agent sigue aplicándose. Esta solicitud elige el número, el agent y el contexto adicional opcional para esta llamada.

  1. El plan incluye Allow Outbound Calls.
  2. Clave API con el grupo Calls.
  3. Un trunk (o teléfono VoIP) desde el cual marcar - Su propio operador / Números de Voice Logica.
  4. El agent id - desde la URL del agent en My Agents, o Copy en una fila de campaña.

Primera configuración - una llamada, luego Calls

Sección titulada «Primera configuración - una llamada, luego Calls»
POST https://api.voicelogica.ai/api/v1/phones/calls/initiate-call
x-api-key: YOUR_API_KEY
Content-Type: application/json

Resellers: opcional x-company-id para actuar sobre una subsidiaria. Sin él, se usa la propia empresa de la clave.

Envíe destinationNumber y agentId. Envíe sipTrunkId o voipPhoneId a menos que la empresa ya tenga una ruta saliente / trunk predeterminado que pueda llevar la llamada - si no se envía ninguno y no se puede resolver un trunk, la API devuelve que no se especificó un SIP trunk activo o teléfono VoIP.

Trunk (usual):

Ventana de terminal
curl -X POST https://api.voicelogica.ai/api/v1/phones/calls/initiate-call \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sipTrunkId": "your_sip_trunk_id",
"destinationNumber": "+14155552671",
"agentId": "your_agent_id"
}'

VoIP phone id aún funciona - el servidor lo resuelve a un trunk.

El éxito es { "callId": "..." }. Si el destino está fuera del horario local 09:00–21:00, puede obtener "scheduled": true más scheduleTime y reason. Abra Calls y escuche.

destinationNumber en E.164 (+14155552671).

Requerido para una llamada saliente de IA

CampoQué hace
destinationNumberNúmero a llamar.
agentIdAgent que habla. Requerido para llamadas salientes de IA; opcional solo para isInternalCall.

Origen de la llamada - envíe uno, o confíe en el predeterminado saliente de la empresa

CampoQué hace
sipTrunkIdTrunk desde Telephony → Trunks. Prefiera esto.
voipPhoneIdID de línea heredado. Se resuelve a un trunk.
callerIdE.164 o SIP URI mostrado al destinatario. Debe ser un número que el trunk pueda presentar.

Solo esta llamada

CampoQué hace
contextForAiSe agrega al prompt del sistema para esta llamada.
dynamicVariablesPares clave/valor de cadena que el prompt puede usar ({{customer_name}}).
superVariablesValores tipados: { placeholder, value, type } - text / number / boolean / date / time.
metadataSu seguimiento. Almacenado en la llamada. Las claves que comienzan con scenario_ se eliminan.
emailAddressDónde enviar el resumen / grabación.
welcomeMessageOverrideSe habla en lugar del saludo del agent.
isWelcomeMessageAIGeneratedLa IA escribe el saludo para esta llamada.
scheduledAtFecha ISO. Llamar más tarde en lugar de ahora.
maxRetriesLlamadas en total, incluida la primera: 1–3, predeterminado 3. 3 = la primera llamada más hasta 2 reintentos; 0 o 1 = sin reintento. Se reintenta si la línea está ocupada, no hay respuesta, salta el buzón de voz o la llamada falla.
retryDelayMinutesMinutos entre esas llamadas: 30–1440, predeterminado 30.
additionalPhoneNumbersNúmeros adicionales en la misma solicitud.

No envíe fromNumber. El contrato público es sipTrunkId / voipPhoneId.

Las llamadas entrantes nunca están restringidas.

  • Hora (activado) - 09:00–21:00 en la hora del país de su empresa. Fuera de eso, la llamada se programa para la siguiente hora permitida. Omitir: overrideTimeRestriction: true.
  • Día (activado) - los fines de semana / feriados pueden estar bloqueados por el país de destino. Omisión: overrideDayRestriction: true.
  • Anti-acoso (activado salvo que envíe useAntiHarassmentProtection: false) - por número y por día: máximo 3 llamadas completadas y 3 fallidas, 1 hora entre llamadas completadas, sin llamada activa/programada duplicada. El día se reinicia a medianoche UTC. Los Allowed test numbers de la campaña omiten esto. Todas las reglas: Call limits.

Omitir las reglas de hora o día puede violar la ley local. Mantenga el anti-acoso activado para quien no haya pedido las llamadas.

El cuerpo es { "error": "<code>", "reason": "<message>" }.

CódigoSignificado
call_already_in_progressYa existe una llamada en vivo o programada a este número.
agent_not_found / voip_phone_not_foundID incorrecto.
daily_call_limit_reached3 llamadas exitosas a este número hoy (anti-acoso).
failed_call_limit_reached3 intentos fallidos hoy.
cooldown_period_activeEspere 1 hora después de una llamada exitosa a este número.
call_already_scheduled / failed_to_schedule_callConflicto de horario.
callee_opted_outEste número pidió no ser llamado nuevamente.
insufficient_credits / no_seconds_available / no_channels_available / no_concurrent_calls_availablePlan / créditos.
maximum_authentication_attempts_exceededTeléfono desactivado después de repetidos fallos de autenticación.

402 es facturación. 400 es una solicitud incorrecta o una protección. 500 es el servidor de llamadas - reintente más tarde.

const response = await fetch('https://api.voicelogica.ai/api/v1/phones/calls/initiate-call', {
method: 'POST',
headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
body: JSON.stringify({
destinationNumber: '+14155552671',
agentId: 'your_agent_id',
sipTrunkId: 'your_sip_trunk_id',
contextForAi: 'Customer asked about order ORD123',
dynamicVariables: { customer_name: 'Ada', order_id: 'ORD123' },
useAntiHarassmentProtection: true,
}),
});
const result = await response.json();
if (result.callId) console.log(result.callId);
else console.error(result.error, result.reason);

Programación + reintentos:

{
"destinationNumber": "+14155552671",
"agentId": "your_agent_id",
"sipTrunkId": "your_sip_trunk_id",
"scheduledAt": "2026-09-16T14:30:00Z",
"maxRetries": 2,
"retryDelayMinutes": 120
}

scheduledAt se convierte a la zona del país de destino. Las protecciones siguen aplicándose a menos que las anule.

  • 400 “no active SIP trunk” - envíe sipTrunkId, o agregue un trunk con números y un predeterminado saliente.
  • scheduled: true cuando esperaba ahora - la hora local de destino está fuera de 09:00–21:00.
  • El agent habla sobre “hola” - Outgoing Who speaks first, no esta carga útil.
  • Llamada faltante en Calls - empresa incorrecta (x-company-id), o la solicitud nunca devolvió un callId.
¿Por qué fromNumber ya no funciona en la llamada a la API initiate-call?

El body público espera sipTrunkId o voipPhoneId. Envíe el id de la troncal que aparece en Telephony → Trunks.

Quería llamar al instante por la API, ¿por qué recibo scheduled: true?

Se aplica una restricción de hora o de día, por eso la llamada quedó programada. Espere a la ventana permitida, o use overrideTimeRestriction / overrideDayRestriction solo si tiene autorización para hacerlo.

Escriba a developers@voicelogica.ai - créditos de prueba adicionales y ayuda con la integración.