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. Las herramientas marcadas como Solo administradores no se ofrecen a los operadores.
Las herramientas que devuelven listas están paginadas y también devuelven total, page, limit y totalPages.
Empresa
getCompany
Devuelve el nombre y el 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 (las habilidades del agente, cada una con su id). 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 constartCall.updatedAt: lo usanupdateAgenty las herramientas de habilidades 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. Consulta Variables de salida. |
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. Para agregar habilidades, llama a addAgentSkill. Los números de teléfono, archivos de la base de conocimiento 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 y lo devuelve con su nuevo updatedAt. 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 | Hasta 20 ediciones pequeñas de buscar y reemplazar en el prompt de voz, cada una { "find": "...", "replace": "..." }. Cada find debe aparecer exactamente una vez; un replace vacío borra el texto. |
textPrompt | string | Prompt de texto/WhatsApp completo nuevo. |
textPromptEdits | array | Hasta 20 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. Máximo 50. Consulta Variables de salida. |
workingHours | object | Reemplaza el horario de trabajo: type ALL_DAY o CUSTOM, y availability con hasta 10 franjas { "start": "09:00", "end": "18:00" } (formato de 24 horas HH:mm, en la zona horaria del agente) por día de la semana. Los días que no se incluyen quedan sin disponibilidad. |
allowReturnCall | boolean | Si los clientes pueden devolver la llamada al agente. |
Envía prompt o promptEdits, no ambos (lo mismo para textPrompt). Hace falta al menos un campo además de slug y expectedUpdatedAt.
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."
Variables de salida
createAgent y updateAgent reciben las variables de salida con la misma forma en que las devuelve getAgent:
| Campo | Tipo | Descripción |
|---|---|---|
name | string, requerido | Nombre de la variable, hasta 100 caracteres. |
value | string, requerido | Tipo de dato: string, number, boolean o enum. |
description | string, requerido | Qué capturar, hasta 1,000 caracteres. |
enum | array, opcional | Valores permitidos, de 1 a 50. Requerido cuando value es enum. |
id | string, opcional | Conserva el id de getAgent; omítelo en las variables nuevas. |
shouldUpdateInputData | boolean, opcional | Conserva el valor de getAgent; omítelo para mantener el guardado. |
Habilidades del agente
Las habilidades son funciones que un agente puede usar durante llamadas o chats. Aparecen en getAgent como tools, cada una con un id. Estas herramientas agregan, cambian o eliminan una habilidad a la vez y no tocan las demás habilidades del agente.
Las tres son Solo administradores, necesitan el updatedAt de getAgent como expectedUpdatedAt y fallan si el agente cambió desde entonces. Cada una devuelve las habilidades del agente (tools) y su nuevo updatedAt.
Funcionan con tres tipos de habilidad:
EMAIL: envía un correo desdeinfo@fonema.ai.GPT_CALL: hace una consulta a otro modelo GPT y devuelve su respuesta al agente.PHONE_CALL: solo para agentes de WhatsApp y chat web. Programa una llamada telefónica de uno de tus agentes de voz a la persona de la conversación.
Las habilidades de llamada a API, HubSpot, Google Calendar, plantillas de WhatsApp y personalizadas se configuran en el dashboard; estas herramientas no pueden cambiarlas ni eliminarlas.
addAgentSkill
Solo administradores. Agrega una habilidad a un agente. Devuelve las habilidades del agente, el skillId de la nueva habilidad y el nuevo updatedAt.
| Parámetro | Tipo | Descripción |
|---|---|---|
slug | string, requerido | Slug del agente. |
expectedUpdatedAt | string, requerido | El updatedAt de getAgent. |
skill | object, requerido | La habilidad. Consulta los campos abajo. |
Campos de skill, para todos los tipos:
| Campo | Tipo | Descripción |
|---|---|---|
type | string, requerido | EMAIL, GPT_CALL o PHONE_CALL. |
name | string, requerido | Nombre de la función que ve el agente, por ejemplo send_quote_email. Hasta 64 caracteres; letras, dígitos, _ y - (cualquier otro carácter se convierte en _). Debe ser único dentro del agente. |
description | string, requerido | Cuándo debe usar el agente la habilidad y qué hace, hasta 1,000 caracteres. El agente decide a partir de esto. |
parameters | array, opcional | Hasta 30 argumentos que el agente envía al usar la habilidad. Consulta Parámetros de habilidad. |
Campos por tipo:
| Tipo | Campo | Descripción |
|---|---|---|
EMAIL | to | Requerido. De 1 a 20 destinatarios. Cada uno es una dirección de correo o un solo {{parametro}}. |
EMAIL | subject | Requerido. Hasta 500 caracteres. Admite placeholders {{parametro}}. |
EMAIL | html | Requerido. Cuerpo del correo, hasta 20,000 caracteres. Texto plano o HTML sencillo; se conservan los saltos de línea. Admite placeholders {{parametro}}. |
EMAIL | replyTo | Opcional. Dirección Reply-To o un solo {{parametro}}. |
GPT_CALL | prompt | Requerido. Instrucción para el modelo GPT, hasta 20,000 caracteres. Su respuesta vuelve al agente. Admite placeholders {{parametro}}. |
EMAIL, GPT_CALL | requestStartMessage | Opcional. Frase corta que se dice en las llamadas de voz en cuanto empieza la habilidad, hasta 300 caracteres, por ejemplo "Un momento, te envío el correo." |
PHONE_CALL | voiceAgentSlug | Requerido. Slug del agente de voz de tu empresa que hace la llamada. |
PHONE_CALL | timing | Opcional. NOW (por defecto) marca de inmediato, DELAY espera delayMinutes, REQUESTED llama a la hora que pida la persona (de inmediato si no pide una). |
PHONE_CALL | delayMinutes | Minutos de espera, de 1 a 10080 (7 días). Requerido con DELAY y no permitido en los demás casos. |
Cada {{placeholder}} del texto de la habilidad necesita un parámetro con el mismo nombre; si falta, la habilidad se rechaza.
Menciona la habilidad en el prompt del agente si debe usarse en un momento concreto, por ejemplo "Usa send_quote_email cuando el cliente confirme su correo."
updateAgentSkill
Solo administradores. Cambia una habilidad EMAIL, GPT_CALL o PHONE_CALL. Solo cambian los campos enviados, y el tipo de la habilidad no puede cambiar. Devuelve las habilidades del agente, el skillId y el nuevo updatedAt.
| Parámetro | Tipo | Descripción |
|---|---|---|
slug | string, requerido | Slug del agente. |
expectedUpdatedAt | string, requerido | El updatedAt de getAgent. |
skillId | integer, requerido | El id de la habilidad en tools de getAgent. |
name | string | Nuevo nombre de la función. |
description | string | Nueva descripción. |
parameters | array | Reemplaza toda la lista de parámetros. |
requestStartMessage | string | EMAIL y GPT_CALL. Un texto vacío lo elimina. |
to, subject, html, replyTo | Solo EMAIL. | |
prompt | string | Solo GPT_CALL. |
voiceAgentSlug, timing, delayMinutes | Solo PHONE_CALL. Si timing deja de ser DELAY, se borra delayMinutes. |
Los campos siguen las mismas reglas que en addAgentSkill. Enviar un campo que no corresponde al tipo de la habilidad falla.
removeAgentSkill
Solo administradores. Elimina una habilidad EMAIL, GPT_CALL o PHONE_CALL de un agente. Devuelve las habilidades restantes y el nuevo updatedAt.
| Parámetro | Tipo | Descripción |
|---|---|---|
slug | string, requerido | Slug del agente. |
expectedUpdatedAt | string, requerido | El updatedAt de getAgent. |
skillId | integer, requerido | El id de la habilidad en tools de getAgent. |
Si el prompt del agente menciona la habilidad, actualiza también el prompt.
Parámetros de habilidad
| Campo | Tipo | Descripción |
|---|---|---|
name | string, requerido | Nombre del argumento sin llaves, hasta 64 letras, dígitos o _. Se usa como {{name}} en el texto de la habilidad. Cada nombre una sola vez. |
type | string, requerido | string, number o boolean. |
description | string | Qué debe completar el agente, hasta 500 caracteres. Requerido salvo que alreadyExists sea true. |
alreadyExists | boolean, opcional | true toma el valor de la variable de entrada de la llamada o del contacto con el mismo nombre (consulta inputVariables en getAgent) en lugar de pedírselo al agente. |
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. También devuelve total. 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 (nombre y slug), toNumber, fromNumber, direction, createdAt, startAt, endAt, durationSeconds, endedReason, successEvaluation, inputData y un resumen de hasta 500 caracteres.
| Parámetro | Tipo | Descripción |
|---|---|---|
phoneNumber | string, opcional | Número del cliente con código de país, por ejemplo "+5215512345678". Se ignoran espacios y guiones. Un número de México coincide tanto si se guardó con el 1 después del 52 como sin él. |
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. |
direction, successEvaluation, outcome, endedReason, output | opcional | Consulta Filtros de llamadas. Necesitan startDate y endDate, con un máximo de 30 días entre ambas. |
Los filtros se combinan, así que agent + startDate devuelve solo las llamadas de ese agente desde esa fecha. Para contar llamadas o clientes, el asistente usa getCallStats en lugar de recorrer páginas de listCalls.
getCallStats
Cuenta llamadas y suma su duración y su costo, con la opción de agruparlas por hasta dos dimensiones. El asistente la usa para totales, desgloses y tendencias, como "¿Cuántas llamadas hizo cada agente la semana pasada?" o "Llamadas por día de este mes, exitosas y no exitosas". Solo lectura.
| Parámetro | Tipo | Descripción |
|---|---|---|
startDate | string, requerido | Llamadas creadas a partir de esta fecha. ISO 8601 con zona horaria. |
endDate | string, requerido | Llamadas creadas hasta esta fecha. Como máximo 30 días después de startDate. |
timeZone | string, opcional | Zona horaria IANA para los grupos hour, day y week, por ejemplo "America/Mexico_City". Por defecto UTC. |
agent | string, opcional | Solo las llamadas de este agente (slug). |
direction, successEvaluation, outcome, endedReason, output | opcional | Consulta Filtros de llamadas. |
groupBy | array, opcional | Hasta dos dimensiones distintas, y como máximo una de hour, day y week. Omítelo para obtener un solo total. |
contactMetrics | boolean, opcional | true agrega conteos por persona. Por defecto false. Consulta más abajo. |
Dimensiones para groupBy:
| Dimensión | Agrupa por |
|---|---|
hour, day, week | Tiempo, en timeZone. Las semanas empiezan el lunes. Los periodos sin llamadas se incluyen con cero. |
agent | Agente. Agrega dos columnas, agent (nombre) y agentSlug. |
direction | inbound o outbound. |
successEvaluation | true, false (incluye buzones de voz) o null (sin evaluar). |
outcome | answered, voicemail, no-answer, busy, other o unknown. Consulta Filtros de llamadas. |
endedReason | El motivo de fin tal como se guardó. |
{ "output": "key" } | Una variable de salida capturada, por ejemplo { "output": "isInterested" }. Los valores se pasan a minúsculas; null significa que no se capturó. |
El resultado es compacto: columns nombra los valores de cada entrada de rows (primero las dimensiones, luego las métricas), y totals contiene las métricas de todo el rango. También devuelve timeZone y currency (USD). Métricas:
| Métrica | Significado |
|---|---|
count | Número de llamadas. |
totalDurationSeconds, avgDurationSeconds | Duración total y promedio de las llamadas. |
cost | Lo que se le cobra a tu empresa por las llamadas, en USD. Es igual a fonemaCost + telephonyCost. |
fonemaCost | El precio por minuto de Fonema. |
telephonyCost | El costo del operador telefónico. |
avgCost | Costo promedio por llamada. |
costPerMinute | Costo por minuto de conversación. |
Los costos de la última hora todavía pueden cambiar, porque los precios del operador llegan después de la llamada.
Métricas de contactos. El conteo de llamadas incluye los reintentos, así que un mismo cliente suele contar varias veces. Con contactMetrics: true, cada fila y totals incluyen además:
| Métrica | Significado |
|---|---|
uniqueContacts | Clientes distintos con al menos una llamada. |
contactsReached | Clientes distintos con al menos una llamada contestada. |
contactsSuccessful | Clientes distintos con al menos una llamada evaluada como exitosa. |
El cliente es el toNumber de la llamada, en ambas direcciones, comparado solo por sus dígitos; un número de México con o sin el 1 después del 52 cuenta como un solo cliente. Los filtros se aplican primero a las llamadas. Son conteos de valores distintos, así que las filas no suman el total: un cliente al que se llamó dos días distintos, o desde dos agentes, cuenta en ambas filas. El total de todo el rango está en totals. totals.callsWithoutContact cuenta las llamadas que quedan fuera porque no tienen número de cliente (llamadas web, o llamadas cuyos datos de cliente se borraron).
Límites:
- Un resultado puede tener como máximo 1,000 filas. Si una agrupación produce más, la herramienta pide un periodo de tiempo más amplio, menos dimensiones o más filtros.
- Una consulta que tarda más de 90 segundos se detiene. Al asistente se le indica que la acote: un solo agente, un rango más corto o menos filtros de variables de salida.
Filtros de llamadas
listCalls y getCallStats comparten estos filtros opcionales. Se combinan con AND y necesitan startDate y endDate con un máximo de 30 días entre ambas.
| Filtro | Tipo | Descripción |
|---|---|---|
direction | string | inbound o outbound. |
successEvaluation | boolean | true = llamadas evaluadas como exitosas, false = evaluadas como no exitosas. Los buzones de voz se evalúan como false, así que false son sobre todo llamadas que nadie contestó; combínalo con outcome: ["answered"] para obtener las conversaciones que no tuvieron éxito. Las llamadas sin evaluación no coinciden con ninguno de los dos. |
outcome | array | Cómo terminó la llamada: answered (el cliente estaba en la línea), voicemail, no-answer, busy, other (errores, llamadas fallidas o canceladas) o unknown (todavía sin motivo de fin, por ejemplo en curso). |
endedReason | array | Hasta 20 motivos de fin exactos, por ejemplo "customer-ended-call". Normalmente outcome es más sencillo. |
output | array | Hasta 5 filtros sobre las variables de salida capturadas, cada uno { "key": "...", "op": "...", "value": "..." }. key es el nombre de la variable de salida tal como aparece en getAgent. |
Operadores para output:
op | Coincide cuando |
|---|---|
eq | El valor es igual a value (sin distinguir mayúsculas). |
neq | El valor es distinto de value, o no se capturó. |
contains | El valor contiene value (sin distinguir mayúsculas). |
isTrue | Un valor afirmativo, como true, sí o 1. |
isFalse | Un valor negativo, como false, no o 0. |
exists | La variable se capturó y no está vacía. |
eq, neq y contains necesitan un value (hasta 200 caracteres).
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, con los segundos desde el inicio de la llamada. La transcripción incluye los turnos del cliente y del agente, y las herramientas que el agente usó durante la llamada: una entrada tool_call tiene el nombre de la herramienta y sus argumentos, y su entrada tool_result (mismo id) puede llegar después, tras más conversación, porque la llamada sigue mientras la herramienta trabaja. Los resultados de herramientas de más de 2,000 caracteres se recortan. 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.
startCall marca a un número de teléfono real y la llamada se cobra como cualquier otra. Una vez marcada no se puede deshacer, por eso la mayoría de las apps te piden confirmación antes de ejecutarla.
| 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". Se ignoran espacios, guiones, puntos y paréntesis. 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. Los nombres usan letras, dígitos y _; los valores son texto (hasta 2,000 caracteres), números o booleanos. |
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.outsideWorkingHoursynextAvailableAt: 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.
- Si tu cuenta llama a través de tu propio SIP trunk, el agente tenga un número de SIP trunk.
- 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.
WhatsApp y chat web
listWhatsappContacts
Lista las personas que chatearon con tus agentes de WhatsApp y de chat web, empezando por el mensaje más reciente. Solo lectura.
Cada contacto incluye:
contactId: úsalo congetWhatsappConversation.name,number,channel(whatsappoweb) yagent(el slug del agente).lastMessageAtylastMessage: quién lo envió (customeroagent), su tipo, los primeros 200 caracteres y cuándo se envió.tag: la etiqueta del contacto, si tiene.inputData: lo que se sabe del contacto: variables de campaña o de Excel, datos que capturó el agente ysessionSummariesde conversaciones anteriores.
| Parámetro | Tipo | Descripción |
|---|---|---|
phoneNumber | string, opcional | Número del cliente con código de país, por ejemplo "+5215512345678". Se ignoran espacios y guiones. Un número de México coincide con o sin el 1 después del 52. |
search | string, opcional | Parte del nombre del contacto o dígitos del número. No distingue mayúsculas. |
agent | string, opcional | Slug del agente. |
startDate | string, opcional | Contactos cuyo último mensaje es de esta fecha en adelante. ISO 8601 con zona horaria, por ejemplo "2026-11-03T00:00:00-06:00". |
endDate | string, opcional | Contactos cuyo último mensaje es de esta fecha o anterior. |
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 con AND.
getWhatsappConversation
Devuelve un contacto de WhatsApp o de chat web (con la misma forma que en listWhatsappContacts) y sus mensajes, del más antiguo al más reciente: lo que escribió el cliente y lo que respondió el agente. Solo lectura.
Cada mensaje incluye su id, quién lo envió (customer o agent), su tipo, su contenido (recortado a 4,000 caracteres) y sentAt. Los mensajes del agente también incluyen deliveredAt y readAt de WhatsApp cuando se conocen, y las herramientas que el agente usó para esa respuesta (nombre, argumentos y resultado, recortado a 2,000 caracteres).
| Parámetro | Tipo | Descripción |
|---|---|---|
contactId | integer, requerido | id del contacto, como lo devuelve listWhatsappContacts. |
limit | integer, opcional | Número de mensajes a devolver, empezando por el más reciente. Por defecto 50, máximo 200. |
beforeId | integer, opcional | Solo mensajes anteriores a este id de mensaje. |
Cuando hasMore es true, hay mensajes más antiguos: el asistente pasa nextBeforeId como beforeId para leerlos.