Saltar al contenido principal

Acceso API

Conectarte a tu agente mediante la API es como darle a tu propio software una linea telefonica directa con el: en lugar de que una persona escriba en una ventana de chat, tu aplicacion envia un mensaje en codigo y recibe la respuesta del agente en codigo. Esta es la forma de conectar tu agente a una aplicacion personalizada, a una herramienta interna o a cualquier sistema que deba hablar con el automaticamente.

En esta guia, API se refiere a la conexion que tu software usa para hablar con Nirvai. Envias una solicitud (el mensaje que estas enviando) y recibes de vuelta una respuesta (la respuesta del agente). Esta pagina esta escrita para desarrolladores, asi que es un poco mas tecnica que el resto, pero cada termino se explica la primera vez que aparece.

Exportacion de canal API mostrando la clave APIImage: Exportacion de canal API mostrando la clave API

Antes de empezar​

  • Un agente completado en el Panel de Control de Agentes
  • La capacidad de enviar una solicitud HTTP: esa es la forma estandar en que los programas hablan con servicios web. Puedes hacerlo desde tu propio codigo o probarlo primero con una herramienta como Postman (una aplicacion gratuita para probar solicitudes a mano)

Configurar el acceso API​

  1. Abre tu agente en el Panel de Control de Agentes
  2. Haz clic en el nodo Canales
  3. Selecciona API en la seccion Web
  4. Haz clic en Crear Exportacion API
  5. Se genera una clave API: copiala y guardala en un lugar seguro. Una clave API es una contrasena privada que le permite a tu aplicacion demostrar que tiene permiso para hablar con tu agente.

Creando una exportacion API y copiando la claveImage: Creando una exportacion API y copiando la clave

aviso

Manten tu clave API en secreto. Cualquiera que la tenga puede enviar mensajes a tu agente y consumir tus creditos. No la pongas en codigo que corre en un navegador ni la subas a un repositorio publico: mantenla en tu servidor.

Realizar solicitudes​

Tu aplicacion envia cada mensaje al endpoint del agente: la direccion web especifica que llamas en Nirvai. Incluye tu clave API para que Nirvai sepa que la solicitud realmente proviene de ti, luego envia el mensaje y lee la respuesta del agente.

curl -X POST https://api.nirvana-ai.app/v1/agent/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your business hours?",
    "session_id": "user-123"
  }'

Que hace esta solicitud, linea por linea:

  • POST https://api.nirvana-ai.app/v1/agent/chat — envia ("POST") tu mensaje al endpoint del agente
  • Authorization: Bearer YOUR_API_KEY — demuestra que eres tu. Reemplaza YOUR_API_KEY por la clave que copiaste
  • Content-Type: application/json — le indica a Nirvai que el mensaje esta en JSON, un formato de texto comun para enviar datos estructurados
  • message — el texto que estas enviando al agente
  • session_id — una etiqueta que eliges para mantener juntos los mensajes de una misma conversacion (mas sobre esto abajo)

Conceptos clave​

ConceptoDescripcion
Clave APIUna contrasena privada que demuestra que la solicitud proviene de tu aplicacion. Se envia en el header Authorization (la parte de una solicitud que lleva la identidad y los ajustes)
Session IDUna etiqueta que agrupa mensajes en una conversacion. Reutiliza el mismo ID para mensajes de seguimiento, asi el agente recuerda el contexto
MessageEl texto que estas enviando al agente
ResponseLa respuesta del agente, devuelta en el cuerpo de la respuesta
tip

Para mantener una conversacion en marcha, envia el mismo session_id con cada mensaje. Un session_id nuevo inicia una conversacion desde cero, sin memoria de lo anterior: util cuando empieza a chatear un usuario distinto.

Casos de uso​

  • Aplicaciones personalizadas — Construye tu propia interfaz de chat que se comunique con tu agente de Nirvai
  • Herramientas internas — Conecta tu agente a paneles internos o paneles de administracion
  • Automatizacion — Activa conversaciones con el agente desde otros sistemas, tareas programadas o alertas automaticas cuando ocurre algo en otro lugar
  • Aplicaciones moviles — Agrega tu agente a una aplicacion iOS o Android

Gestion de tu exportacion​

  • Regenerar clave: Si tu clave API queda expuesta, crea una nueva exportacion y elimina la anterior. La clave anterior deja de funcionar de inmediato.
  • Eliminar: Desactiva la exportacion API. Las claves existentes dejan de funcionar inmediatamente.

Solucion de problemas​

ProblemaSolucion
Recibes un error "401 Unauthorized"La clave API falta o es incorrecta. Verifica que sea correcta y que se envie en el header Authorization como Bearer YOUR_API_KEY
El agente no respondeAsegurate de que el agente este creado y que la exportacion API siga activa
La conversacion no recuerda el contextoUsa el mismo session_id para cada mensaje que pertenezca a la misma conversacion
Recibes un error de "Content-Type" o de lecturaEnvia el cuerpo como JSON e incluye el header Content-Type: application/json

Que sigue​

Para ver las formas sin codigo de poner tu agente en la web (un widget de chat flotante o un enlace publico), consulta la Vision General de Canales.