Herramientas disponibles

El asistente elige estas herramientas por su cuenta según lo que le pidas. No necesitas llamarlas por nombre, pero saber qué hace cada una te ayuda a escribir mejores solicitudes.

Todas las herramientas trabajan sobre la empresa del usuario que autorizó la app.

Empresa

getCompany

Devuelve el id, nombre y slug de tu empresa. Solo lectura.

Agentes

listAgents

Lista tus agentes de voz y de WhatsApp, ordenados por nombre, con el nombre y slug de cada uno. Solo lectura.

Parámetro	Tipo	Descripción
search	string, opcional	Texto a buscar en el nombre o slug del agente, por ejemplo "ventas". No distingue mayúsculas.
page	integer, opcional	Número de página. Por defecto 1.
limit	integer, opcional	Tamaño de página. Por defecto 50, máximo 100.

getAgent

Devuelve la configuración de un agente: prompt de voz, prompt de texto (WhatsApp), saludo, voz, lógica de rellamada y reintentos, horario de trabajo, destinos de transferencia, variables de salida, archivos de la base de conocimiento y herramientas. Nunca incluye secretos ni credenciales. Solo lectura.

También devuelve:

• inputVariables: los {{placeholders}} que usan el prompt de voz y el saludo, para que el asistente sepa qué enviar con startCall.
• updatedAt: lo usa updateAgent para no sobrescribir cambios de otra persona.

Parámetro	Tipo	Descripción
slug	string, requerido	Slug del agente, como lo devuelve listAgents.

createAgent

Solo administradores. Crea un nuevo agente de voz en tu empresa y lo devuelve con la misma forma que getAgent (incluido updatedAt). Funciona igual que crear un agente desde el dashboard o con la API de creación de agentes.

Parámetro	Tipo	Descripción
name	string, requerido	Nombre visible.
prompt	string, requerido	Prompt de voz. Usa placeholders {{variable}} para los datos que cambian en cada llamada.
voiceId	string, requerido	Voz a usar, como la devuelve listVoices.
greeting	string, opcional	Primer mensaje que dice el agente.
farewell	string, opcional	Mensaje antes de colgar.
outputVariables	array, opcional	Datos que el agente captura en cada llamada. Máximo 50.

Para configurar el prompt de texto/WhatsApp, el horario de trabajo u otros ajustes, el asistente llama a updateAgent justo después con el updatedAt devuelto. Los números de teléfono, archivos de la base de conocimiento, herramientas y webhooks se configuran en el dashboard.

Para evitar duplicados, Fonema rechaza la solicitud si:

• Ya se creó un agente con el mismo nombre en los últimos 10 minutos (normalmente un reintento). Al asistente se le indica que actualice ese agente o elija otro nombre.
• La conexión ya creó 20 agentes en la última hora.

updateAgent

Solo administradores. Actualiza un agente. Solo cambian los campos enviados, y el cambio se publica de inmediato, igual que al publicar desde el dashboard.

Parámetro	Tipo	Descripción
slug	string, requerido	Slug del agente.
expectedUpdatedAt	string, requerido	El updatedAt de getAgent. La actualización falla si el agente cambió desde entonces, para que no se pierdan ediciones.
name	string	Nombre visible. El slug no cambia.
prompt	string	Prompt de voz completo nuevo.
promptEdits	array	Ediciones pequeñas de buscar y reemplazar en el prompt de voz. Cada find debe aparecer exactamente una vez.
textPrompt	string	Prompt de texto/WhatsApp completo nuevo.
textPromptEdits	array	Ediciones de buscar y reemplazar en el prompt de texto.
greeting	string	Primer mensaje que dice el agente.
farewell	string	Mensaje antes de colgar.
outputVariables	array	Reemplaza toda la lista de variables capturadas.
workingHours	object	Reemplaza el horario de trabajo (ALL_DAY o CUSTOM con horarios por día de la semana).
allowReturnCall	boolean	Si los clientes pueden devolver la llamada al agente.

Envía prompt o promptEdits, no ambos (lo mismo para textPrompt).

tip

Pide al asistente que te muestre el cambio antes de aplicarlo, por ejemplo: "Sugiere un nuevo saludo para mi agente de ventas y espera mi OK antes de actualizarlo."

Voces

listVoices

Lista las voces disponibles para tus agentes, incluidas las voces personalizadas de tu empresa. Cada voz incluye su voiceId, nombre, país, idioma, sexo, un detalle corto y la URL de un audio de muestra. Solo lectura.

Parámetro	Tipo	Descripción
language	string, opcional	Texto a buscar en el idioma, por ejemplo "spanish". No distingue mayúsculas.
country	string, opcional	Texto a buscar en el país, por ejemplo "mexico". No distingue mayúsculas.

Usa el voiceId con createAgent.

Llamadas

listCalls

Lista las llamadas entrantes y salientes, de la más reciente a la más antigua. Solo lectura. Cada llamada incluye su uid, agente, números, dirección, horarios, duración, motivo de fin, evaluación de éxito, variables de entrada y un resumen corto.

Parámetro	Tipo	Descripción
phoneNumber	string, opcional	Número del cliente con código de país, por ejemplo "+5215512345678".
agent	string, opcional	Slug del agente.
startDate	string, opcional	Llamadas creadas a partir de esta fecha. ISO 8601 con zona horaria, por ejemplo "2026-09-23T00:00:00-06:00".
endDate	string, opcional	Llamadas creadas hasta esta fecha.
page	integer, opcional	Número de página. Por defecto 1.
limit	integer, opcional	Tamaño de página. Por defecto 20, máximo 50.

Los filtros se combinan, así que agent + startDate devuelve solo las llamadas de ese agente desde esa fecha.

getCall

Devuelve una llamada con su análisis completo de fin de llamada (resumen, evaluación de éxito, datos capturados) y la transcripción en orden cronológico. La transcripción incluye los turnos del cliente y del agente, y las herramientas que el agente usó durante la llamada (entradas tool_call y tool_result). Solo lectura.

Parámetro	Tipo	Descripción
uid	string, requerido	uid de la llamada, como lo devuelve listCalls.

La grabación no se devuelve; hasRecording indica si existe una.

startCall

Hace una llamada saliente con uno de tus agentes. La llamada se pone en cola y se marca en aproximadamente un minuto, con las mismas reglas que la API de llamadas: aplican el horario de trabajo, los reintentos y el control de volumen.

Parámetro	Tipo	Descripción
agent	string, requerido	Slug del agente.
phoneNumber	string, requerido	Número del cliente con código de país, por ejemplo "+5215512345678". Un número de 10 dígitos sin + usa el código de país por defecto del agente.
name	string, opcional	Nombre del cliente, disponible para el prompt.
email	string, opcional	Email del cliente, disponible para el prompt.
variables	object, opcional	Variables de entrada para el prompt, sin llaves: { "poliza": "123" }. Máximo 50.
delayMinutes	integer, opcional	Minutos de espera antes de llamar. Por defecto 0, máximo 10080 (7 días).

La respuesta le indica al asistente:

• callAt: cuándo está programada la llamada.
• outsideWorkingHours y nextAvailableAt: si la hora cae fuera del horario del agente, cuándo se marcará realmente.
• missingVariables: variables del prompt que no se enviaron.

Antes de ponerla en cola, Fonema verifica que:

• El agente tenga prompt de voz.
• La facturación de tu cuenta esté activa.
• No haya ya una llamada pendiente del mismo agente al mismo número.
• La conexión no haya iniciado más de 10 llamadas en los últimos 10 minutos.

Una vez marcada, la llamada aparece en listCalls.