Documentación

API personalizada

Llama a API externas desde tu agente para obtener datos o activar integraciones.

Las acciones de API personalizada permiten que tu agente interactúe con servicios externos. Obtén datos en tiempo real, envía formularios o activa flujos de trabajo en otras herramientas.

Crear una acción de API personalizada

  1. Ve a la pestaña Acciones de tu agente
  2. Haz clic en Agregar acción → API personalizada
  3. Configura la llamada a la API:
    • URL del endpoint - El endpoint de la API al que se llama
    • Método HTTP - GET, POST, PUT, PATCH o DELETE
    • Encabezados - Autenticación y tipo de contenido
    • Cuerpo de la solicitud - Datos a enviar (para POST/PUT/PATCH)
  4. Guarda y prueba

Opciones de configuración

URL del endpoint

La URL completa del endpoint de la API:

https://api.yourservice.com/v1/data

Usa solo endpoints HTTPS. Los endpoints HTTP están bloqueados por seguridad.

Método HTTP

MétodoCaso de uso
GETObtener datos de un servicio externo
POSTEnviar datos, crear registros
PUTReemplazar registros existentes
PATCHActualizar parcialmente registros existentes
DELETEEliminar registros

Encabezados

Agrega encabezados de autenticación y de tipo de contenido:

Authorization: Bearer {{SECRET:service_api_key}}
Content-Type: application/json

Crea el secreto con nombre por separado. Agentkit resuelve {{SECRET:name}} solo en el servidor. Las lecturas de acciones y los registros nunca incluyen el valor almacenado.

Origen de los datos de entrada

Para un campo de texto con una sola dirección de correo, elige el correo verificado con pregunta si no está disponible. Agentkit usa el contacto web verificado o el remitente del correo entrante. A los visitantes anónimos les pide la dirección. El modelo no puede sustituir una dirección verificada.

Cuerpo de la solicitud

Para las solicitudes POST/PUT, define el cuerpo JSON con los datos que quieras enviar.

Cuándo se llama a la API

La IA decide cuándo llamar a la API según el contexto de la conversación y la descripción de la acción. Puedes guiar este comportamiento con una descripción clara de cuándo debe activarse la acción.

Gestionar las respuestas

Respuesta exitosa

Cuando la API responde correctamente (estado 2xx):

  • Muestra un mensaje de éxito al visitante
  • Incluye los datos de la respuesta en el chat
  • Activa acciones de seguimiento

Gestión de errores

Cuando la API falla:

  • Muestra un mensaje de error amigable
  • Registra el error para depurarlo
  • Opcionalmente, vuelve a intentar la solicitud

Ejemplos de casos de uso

Consultar el estado de un pedido

Configura un endpoint GET para obtener los datos del pedido cuando los visitantes pregunten por su estado.

Enviar a tu CRM

Configura un endpoint POST para enviar los datos de leads a tu sistema CRM.

Obtener datos en tiempo real

Configura un endpoint GET para obtener datos en tiempo real (como disponibilidad o inventario) de tus sistemas.

Consideraciones de seguridad

Claves de API

  • Guarda las claves API como secretos con nombre y usa referencias {{SECRET:name}}.
  • Usa claves específicas de cada entorno para las pruebas
  • Rota las claves periódicamente

Límite de frecuencia

  • Las API externas pueden tener límites de frecuencia
  • Configura el límite de frecuencia de tu agente en consecuencia
  • Supervisa el uso de la API en los registros

Privacidad de datos

  • Envía solo los datos necesarios
  • Asegúrate de que los servicios externos cumplan con el RGPD si es necesario
  • No registres datos sensibles de la respuesta

Tiempo de espera y reintentos

ConfiguraciónValor predeterminadoNotas
Tiempo de espera20 segundosLa solicitud falla si no hay respuesta
Reintentos0Configura los reintentos de webhook para mayor confiabilidad

Probar tu acción de API

  1. Configura la acción con un endpoint de prueba
  2. Ve a Playground
  3. Activa la acción con la entrada adecuada
  4. Comprueba la respuesta en el chat
  5. Revisa los registros para depurar

Próximos pasos