Saltar al contenido principal

Agentes

Editar agente

Actualiza y publica un agente existente. Solo se modifican los campos que incluyas; el resto se mantiene sin cambios. Todos los campos son opcionales, por lo que puedes enviar actualizaciones parciales.

Autenticación​

AuthorizationBearer

Autentica las solicitudes desde tu servidor con una API Key de Fonema. Créala en la sección de API Keys del Dashboard y envíala en el encabezado Authorization como Bearer <token>. No pongas tus claves en código del navegador ni en repositorios públicos.

Parámetros de ruta​

slugstringObligatorio
Slug único del agente a actualizar.

Cuerpo​

Parámetros de nivel superior​

namestringOpcional
Nombre del agente.
greetingstringOpcional
Mensaje de apertura al iniciar la llamada.
promptstringOpcional
Prompt del sistema que define el comportamiento del agente.
textPromptstringOpcional
Prompt usado para conversaciones de texto/chat.
farewellstringOpcional
Mensaje de cierre al final de la llamada.
voiceIdstringOpcional

Identificador de la voz del agente. Consulta los valores disponibles en Listar voces.

outputVariablesarrayOpcional

Variables a capturar durante la llamada (misma estructura que en Crear agente).

recallLogicobjectOpcional

Configuración de reintentos para llamadas no contestadas. Ver recallLogic.

numberOfAttemptintegerOpcional
Número total de intentos de llamada (primera llamada + reintentos).
allowReturnCallbooleanOpcional
Si el agente permite llamadas de retorno.
localizationsobjectOpcional
Configuración de localización.
workingHoursobjectOpcional

Horario en el que el agente puede realizar llamadas. Ver workingHours.

dtmfbooleanOpcional
Si el agente puede marcar tonos del teclado (DTMF) durante la llamada, por ejemplo para navegar menús telefónicos (IVR).
transferCallDestinationsarrayOpcional

Números de teléfono a los que el agente puede transferir la llamada. Un arreglo vacío desactiva las transferencias. Ver transferCallDestinations.

endOfCallWebhookstringOpcional
URL notificada cuando termina una llamada.
endOfSessionWebhookstringOpcional
URL notificada cuando termina una sesión.
callUpdatesWebhookstringOpcional
URL notificada en las actualizaciones de estado de la llamada.
knowledgeBaseFilesinteger[]Opcional
IDs de los archivos de base de conocimiento a adjuntar.
toolsarrayOpcional
Herramientas/skills disponibles para el agente. Ver más abajo.
configobjectOpcional
Forma alternativa de enviar valores de configuración. Ver más abajo.

Elementos de tools​

tools[].idinteger
ID de una herramienta existente (omítelo para crear una nueva).
tools[].namestring
Nombre de la herramienta. Si se omite, se usa content.functionName.
tools[].typestring
Tipo de herramienta (ej. API_CALL).
tools[].descriptionstring
Qué hace la herramienta.
tools[].variablesarray
Variables de entrada de la herramienta.
tools[].contentobject
Detalles de implementación de la herramienta (nombre de la función, URL, autenticación, etc.).

Objeto config​

config acepta la misma configuración que varios campos de nivel superior. Puedes enviar los valores en el nivel superior o dentro de config; los campos de nivel superior tienen prioridad cuando ambos están presentes. Claves soportadas:

transcriberLanguage, endOfCallMessage, silenceTimeoutSeconds, silenceMessages, maxDurationSeconds, voice, captureDataVariables, endOfCallWebhook, endOfSessionWebhook, callUpdatesWebhook, allowReturnCall, workingHours, dtmf, transferCallDestinations, localizations.

Las claves que solo existen dentro de config son:

config.transcriberLanguagestring

Idioma en el que escucha el agente. Uno de es, es-419 (español latinoamericano), en, pt, pt-BR, ro.

config.endOfCallMessagestring
Equivale a farewell en el nivel superior.
config.silenceTimeoutSecondsnumber
Segundos de silencio del cliente antes de terminar la llamada.
config.silenceMessagesstring[]

Frases que el agente dice cuando el cliente se queda en silencio (se elige una al azar) antes de que el tiempo de silencio termine la llamada. Solo se usa si silenceTimeoutSeconds está definido. Enviar este campo reemplaza la lista completa; envía [] para vaciarla.

config.maxDurationSecondsnumber
Duración máxima de la llamada, en segundos.
config.voiceobject

Ajustes finos de la voz del agente. Ver config.voice.

config.captureDataVariablesarray
Equivale a outputVariables en el nivel superior.

Objeto config.voice​

config.voice.stabilitynumber0 – 1

Valores altos suenan más estables y consistentes; valores bajos suenan más expresivos y variables.

config.voice.similarityBoostnumber0 – 1

Qué tanto se parece el audio generado a la voz original (claridad).

config.voice.speednumber0.7 – 1.2

Velocidad al hablar. 1 es la velocidad normal.

Solo se modifican las claves que envíes; el resto conserva su valor actual.

Objeto recallLogic​

Controla los reintentos automáticos cuando una llamada no es contestada (no contesta, ocupado, buzón de voz, etc.).

recallLogic.allowRetryboolean
Activa los reintentos automáticos.
recallLogic.triesarray

Un elemento por reintento, en orden. Cada elemento es { "waitMinutes": number }: minutos que se esperan después del intento anterior no contestado antes de volver a llamar. La cantidad de elementos es la cantidad de reintentos.

recallLogic.timeZonestringPor defecto America/Mexico_City

Zona horaria IANA usada para programar los reintentos (ej. America/Mexico_City). Por defecto America/Mexico_City.

recallLogic.scheduleTypestring

SAME_AS_WORKING para reintentar solo dentro de workingHours, o CUSTOM para usar availability.

recallLogic.availabilityobject

Horario de reintentos cuando scheduleType es CUSTOM. Misma estructura que workingHours.availability.

nota

tries, availability y scheduleType se reemplazan por completo cada vez que envías recallLogic, así que siempre envía la lista completa de reintentos.

Ejemplo: reintentar dos veces, 30 y 120 minutos después de una llamada no contestada, para un total de 3 intentos:

{
  "numberOfAttempt": 3,
  "recallLogic": {
    "allowRetry": true,
    "timeZone": "America/Mexico_City",
    "scheduleType": "SAME_AS_WORKING",
    "tries": [{ "waitMinutes": 30 }, { "waitMinutes": 120 }]
  }
}

Objeto workingHours​

workingHours.typestring
ALL_DAY (sin restricción) o CUSTOM.
workingHours.availabilityobject

Obligatorio cuando type es CUSTOM. Las claves son los días (monday … sunday); cada valor es una lista de ventanas { "start": "HH:mm", "end": "HH:mm" }. Los días que falten o estén vacíos no están disponibles.

{
  "workingHours": {
    "type": "CUSTOM",
    "availability": {
      "monday": [{ "start": "09:00", "end": "18:00" }],
      "tuesday": [{ "start": "09:00", "end": "14:00" }, { "start": "16:00", "end": "19:00" }]
    }
  }
}

Elementos de transferCallDestinations​

Cada destino es un número de teléfono al que el agente puede transferir la llamada. Envía un arreglo vacío para desactivar las transferencias.

transferCallDestinations[].numberstringObligatorio

Número de destino en formato E.164 (ej. +525512345678).

transferCallDestinations[].messagestringOpcional
Mensaje que el agente le dice al cliente antes de transferir.
transferCallDestinations[].extensionstringOpcional
Extensión a marcar una vez que se conecta la llamada.
transferCallDestinations[].descriptionstringOpcional

Cuándo debe transferir el agente a este número. El agente lo usa para elegir el destino correcto.

{
  "transferCallDestinations": [
    {
      "number": "+525512345678",
      "message": "Te transfiero con un asesor, un momento por favor.",
      "description": "Transferir cuando el cliente pida hablar con un asesor humano."
    }
  ]
}

Respuesta​

Devuelve el agente completo y actualizado, con la misma estructura que Consultar agente.

Errores​

400
Cuerpo de solicitud inválido.
403
El agente no existe o no es accesible con esta API Key.