ORYKSAORYKSADevelopers
Obtener claves de API

Sesiones para apps

Pon el empleado de IA dentro de apps móviles, de escritorio y web sin enviar nunca la clave secreta.

Solo para clientes. Este canal atiende a los clientes de la empresa (preguntas, ventas, reservas) con tu Brain, productos y servicios. Nunca es una interfaz del dueño: no cambia ajustes, no lee Actividades ni acepta órdenes del dueño, aunque alguien diga que es el dueño. El dueño habla con ORYKSA solo en la app oficial de ORYKSA, el panel y la extensión del navegador. Más información

Cómo funciona

  1. Tu servidor llama a POST /v1/sessions con la clave secreta y recibe un client_token (oryk_cs_...) válido de 5 a 1440 minutos (por defecto 60), ligado a una conversación.
  2. Tu app recibe solo ese token y habla con los endpoints /v1/client/*. No puede leer otras conversaciones, cambiar el agente ni crear claves.
  3. Cuando el token caduca la API responde 401 session_expired: pide otro a tu servidor (el SDK lo hace solo con getToken).

Crear una sesión (servidor)

POST/v1/sessions
import { Oryksa } from "@oryksa/sdk";
const oryksa = new Oryksa(process.env.ORYKSA_API_KEY);

// e.g. GET /oryksa-token in YOUR backend, after your own user login
app.get("/oryksa-token", requireLogin, async (req, res) => {
  const s = await oryksa.createSession({
    conversationId: "user-" + req.user.id,   // one conversation per app user
    customerName: req.user.firstName,
    ttlMinutes: 60,
  });
  res.json({ token: s.client_token });
});
curl https://api.oryksa.com/v1/sessions \
  -H "Authorization: Bearer oryk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": "user-4812", "customer_name": "Ana", "ttl_minutes": 60}'
{
  "object": "client_session",
  "client_token": "oryk_cs_6sCKXnHtZMpCXVO5LgpWbPF4jcSqpcOe",
  "conversation_id": "user-4812",
  "expires_at": "2026-09-24T10:41:07+00:00"
}

Usarla en la app

import { OryksaClient, mountChat } from "@oryksa/sdk";

const client = new OryksaClient({
  // called again automatically when the token expires
  getToken: async () => (await fetch("/oryksa-token").then(r => r.json())).token,
});

// ready-made chat UI (same look as the website chat)
mountChat({ client, lang: "en" });

// or headless, with your own UI
const agent = await client.agent();          // name, photo, greeting, suggestions
const r = await client.send("How do I reset my password?");
console.log(r.reply);
# the app only uses the short-lived token
curl https://api.oryksa.com/v1/client/agent    -H "Authorization: Bearer oryk_cs_..."
curl https://api.oryksa.com/v1/client/chat     -H "Authorization: Bearer oryk_cs_..." \
     -H "Content-Type: application/json" -d '{"message": "Hi!"}'
curl https://api.oryksa.com/v1/client/messages -H "Authorization: Bearer oryk_cs_..."

Endpoints del cliente

GET/v1/client/agent

Respuesta: nombre del agente, foto, saludo, sugerencias y subtítulo por idioma, y si las respuestas de voz están incluidas.

POST/v1/client/chat

Enviar un mensaje, con la misma respuesta que POST /v1/chat.

Antes de que la IA responda a un cliente nuevo, le pide el nombre, el correo y el teléfono en la conversación (los campos que el dueño deja activados en Conectores > Chat de la web > Datos del visitante). Mientras los pide, la respuesta trae "collecting": "name" | "email" | "phone" para que tu app muestre el teclado adecuado; el cliente responde en el chat y la primera pregunta se responde en cuanto los datos están completos.

GET/v1/client/messages

Mensajes de esta conversación.

Los endpoints del cliente aceptan llamadas desde cualquier origen (CORS), así que funcionan en front-ends web, React Native, Flutter, Electron y apps nativas. Límite: 30 peticiones por minuto por sesión.

Enseñar al Brain tu app

import { Oryksa } from "@oryksa/sdk";
const oryksa = new Oryksa(process.env.ORYKSA_API_KEY);

// Teach the AI employee about YOUR app, e.g. on every release (CI step)
await oryksa.learnApp({
  name: "FitTrack",
  agentName: "Nova",
  description: "FitTrack is a fitness app to log workouts and follow training plans.",
  languages: ["en", "pt"],
  screens: [
    { title: "Workouts", content: "Tap + to log a workout: running, cycling, gym or yoga." },
    { title: "Plans", content: "5K beginner (6 weeks), Half marathon (12 weeks). Plans are Premium." },
  ],
  settings: { units: "metric", sync: "Apple Health and Google Fit" },
  faq: [{ question: "How do I cancel Premium?", answer: "Settings > Subscription > Cancel." }],
});
AnteriorConversacionesSiguienteEndpoints del widget