Zoosial
docs
InicioLlamadas con IA
Volver al sitio Volver al Dashboard
Zoosial
Buscar en docs...
⌘K
APIs · VOZ

Llamadas con IA

Crea un agente de voz, llama a tus contactos y recibe el resultado por API o webhook. También puedes probarlo desde el panel de llamadas.

Planes y llamadas simultáneas

Una llamada simultánea es una conversación activa al mismo tiempo que otra. El límite está incluido en el plan; no se cobra una cuota adicional por cada una.

PlanMensual + IVAMinutosA la vez
Esencial$499 MXN2502
Crece$1,499 MXN7505
Pro$3,999 MXN2,00010

Cada llamada contestada consume minutos por separado, redondeados por llamada al minuto completo. Los paquetes de minutos adicionales no aumentan el límite de simultáneas. Para pasar de 2 a 5, cambia a Crece (+$1,000 MXN al mes); para pasar de 5 a 10, cambia a Pro (+$2,500 MXN al mes). Diferencias más IVA e incluyen también más minutos y estados. Ver planes y paquetes.

Primeros pasos

  1. Crea tu API key o usa la sesión del panel.
  2. Consulta GET /voice/terms y acepta la versión vigente con POST /voice/terms/accept y { "version": "…" }.
  3. Crea un agente con POST /voice/agents, enviando name, prompt y firstMessage.
  4. Inicia una llamada con POST /voice/calls: envía agentId, to en formato +52, purpose y consent.source.
  5. Consulta GET /voice/calls/:id o recibe el evento call.ended en tu webhook.

Límites y errores

Si alcanzas el límite, una nueva llamada saliente devuelve 429 voz_simultaneas; espera a que termine una antes de reintentar. Una llamada entrante también se rechaza si el límite está ocupado. Sin minutos disponibles la API devuelve 402 voz_sin_minutos. Consulta tu saldo y límite con GET /billing/llamadas.

Antes de llamar revisa las condiciones de consentimiento, el propósito, horarios y números permitidos. Consulta cuerpos completos, números propios, recepción de llamadas, errores y eventos en la sección «Llamadas con IA (voz)» de llms.txt y los términos de llamadas.

Reglas que conviene conocer

  • Horario: las llamadas salen de 9:00 a 20:00 hora del centro de México (8:00 a 21:00 en Tijuana y Cancún). Una llamada de servicio puede salir fuera de horario con outsideHours, hasta 3 al día por cuenta.
  • Mismo número: máximo 3 intentos al día al mismo número por cuenta, contestados o no (también los que se cortan antes de contestar y las pruebas a tu propio celular): 429 voz_destino_tope. Si pruebas seguido con tu celular, escribe a soporte@zoosial.com y lo dejamos como número de prueba de tu cuenta.
  • Respuestas cortas, tope duro: cada respuesta del agente se corta a 120 tokens (unas 85 palabras, ~30 segundos de voz). No se sube ni con reglas propias, y si el modelo llega al tope la respuesta se corta a media frase. Para no cortarte: una idea y una pregunta por turno (~25 palabras), maxWordsPerTurn en 50–60 (descarta frases enteras en vez de cortar a media frase), lo largo en knowledge y dicho por partes, y revisa metrics.turnos[].finishReason: cada "length" es una respuesta cortada.
  • Herramientas en la llamada: el agente puede consultar tu servidor mientras habla (por ejemplo, si una hora está libre) y hablar con tu respuesta. Las declaras en el agente (tools, hasta 3: nombre, descripción, parámetros simples, una url https y pública, timeoutMs de 500 a 2500 ms y una frase de espera opcional). Al guardar la primera recibes toolsSecret, solo esa vez. Cada petición llega firmada: X-Zoosial-Signature: sha256=… es el HMAC-SHA256 de "timestamp.cuerpo crudo", con el timestamp en X-Zoosial-Timestamp; verifícala y rechaza timestamps de más de 5 minutos. Contesta 2xx con un objeto JSON (hasta 4 KB) con las horas ya dichas en voz alta; si tu servidor falla o tarda, el agente recibe {"error":"sin_respuesta"} y nunca se reintenta solo. Usa X-Zoosial-Idempotency-Key para que apartar algo dos veces no lo duplique, prueba sin llamar con POST /voice/agents/:id/tools/:name/test y mira metrics.herramientas en cada llamada. Con reglas propias, escribe en tu prompt cuándo usar cada herramienta.
  • Palabras clave: keyterms en el agente (hasta 20) hace que la transcripción reconozca mejor el nombre de tu empresa, productos y siglas como «IA». Tiene costo extra: 1 minuto más por cada 40 minutos acumulados de llamadas con keyterms (sale en billedMinutes de la llamada que cruza los 40).
  • Transcripción por llamada: POST /voice/calls acepta "stt": "flux" o "stt": "nova-3" para elegir el modelo solo en esa llamada (sin el campo, va el de la cuenta); metrics.stt dice cuál corrió. Flux cierra el turno antes y no da eventos vacíos, pero oye peor las respuestas muy cortas y los nombres; Nova-3 es más precisa y cierra con endOfSpeechMs.
  • Cuándo contesta el agente: endOfSpeechMs es el silencio que cierra el turno de la persona (el defecto es 300 ms). En nuestras pruebas por línea telefónica cerró en ~1.1–1.2 s con 300 ms y entre 1.4 y 3.3 s con 600 ms; las respuestas de una sola palabra («sí», «ajá») tardan más con cualquier valor (2.7–4.7 s). Empieza en 300–400 y sube solo si cortan a quien piensa.
  • Voz de respaldo: si la voz principal falla en una frase, esa frase suena con una voz de respaldo en vez de quedar en silencio, y el error queda en metrics.errores de la llamada.
  • Interrupciones: un acuse suelto («ok», «ajá», «sí», «claro», «gracias»…) no calla al agente; dos palabras o más que no sean acuses («qué bien») o una palabra que pide atención («espera», «no», «oye») sí. Al callarlo no retoma donde iba: contesta lo que la persona dijo y puede repetir parte de su frase. No se configura por agente.
  • Grabaciones: se borran a los 90 días (la transcripción y el análisis se quedan). Para que no se grabe, recording: false en el agente; para quitar una grabación antes, DELETE /voice/calls/:id/recording (borra el audio; la transcripción y el análisis se quedan y no se puede deshacer).
En esta página
Planes y llamadas simultáneas Primeros pasos Límites y errores Reglas que conviene conocer
¿Tienes dudas?
Nuestro equipo responde en menos de 2h
Contactar soporte