Llamada a API

La habilidad Llamada a API permite que tu agente llame a cualquier API HTTP externa durante una conversación. Úsala para consultar datos en tus sistemas, disparar flujos de trabajo, crear registros en un CRM/ERP o cualquier otra cosa accesible mediante un endpoint HTTP.

Cuando el agente decide usar la habilidad, Fonema envía una petición POST a la URL que configuraste, con un cuerpo JSON construido a partir de los parámetros que el agente recopiló durante la llamada. La respuesta del endpoint se devuelve al agente para que continúe la conversación.

Crear la habilidad

1. Abre el perfil de tu agente → Instrucciones → Editar agente.
2. En el panel de Habilidades, haz clic en + Crear habilidad.
3. Elige Llamada a API.

Configuración

Campo	Descripción
Skill name	Un nombre descriptivo para la habilidad (por ejemplo, Appointment confirmation).
Description	Explica al agente qué hace la habilidad y cuándo usarla.
End point URL	El endpoint que recibe la petición POST.
Auth type	Opcional. Bearer Token o Basic. El campo que aparece debajo contiene el token/credencial que se envía en el encabezado Authorization.
Headers	Opcional. Usa + Add header para incluir encabezados clave/valor personalizados en la petición (por ejemplo, un encabezado con una API key).
Argument	Usa + Add argument para definir los valores que el agente debe recopilar durante la llamada (por ejemplo, email, orderId). Cada argumento se describe para que el modelo sepa qué preguntar, y se envía en el cuerpo de la petición.

Cómo se construye la petición

Cuando el agente activa la habilidad, Fonema construye el cuerpo de la petición combinando varias fuentes:

1. Argumentos del modelo: los valores que el agente recopiló del interlocutor para cada parámetro.
2. Valores extraídos: para cada parámetro, si está marcado como ya conocido (por ejemplo, se pasó como variable de entrada al crear la llamada), Fonema usa ese valor almacenado en lugar de pedir al modelo que lo invente.
3. Datos del cliente: Fonema siempre agrega el número de teléfono del interlocutor:

{
  "...": "tus parámetros",
  "customer": {
    "number": "+1XXXXXXXXXX"
  }
}

Encabezados y autenticación

La petición se envía con content-type: application/json, más:

• Cualquier encabezado personalizado que hayas configurado.
• Un encabezado Authorization con el formato {authType} {token} cuando se establecen un tipo de autenticación y un token (por ejemplo, Authorization: Bearer abc123).

Ejemplo de petición

POST https://tu-api.example.com/lookup
content-type: application/json
authorization: Bearer abc123
x-api-key: tu-valor-de-encabezado-personalizado

{
  "email": "interlocutor@example.com",
  "orderId": "A-1024",
  "customer": {
    "number": "+34123456789"
  }
}

Manejo de la respuesta

Fonema espera una respuesta JSON. El valor que se devuelve al agente es:

• El campo message de la respuesta, si está presente.
• En caso contrario, el cuerpo completo de la respuesta.

{
  "message": "Tu pedido A-1024 se envía mañana."
}

El agente recibe este resultado y lo usa para continuar hablando con el interlocutor de forma natural.

Recomendaciones

• Mantén tu endpoint rápido: se ejecuta en medio de una conversación en vivo.
• Devuelve una cadena message concisa para que el agente tenga una respuesta clara y fácil de pronunciar.
• Menciona la habilidad en las instrucciones de tu prompt para que el agente sepa cuándo llamarla y qué parámetros recopilar.
• Prueba el endpoint con una llamada real antes de pasar a producción.