Sessions d'application

Intégrez l’employé IA dans des applications mobiles, desktop et web sans jamais transmettre la clé secrète.

Pour les clients uniquement. Ce canal sert les clients de l'entreprise (questions, ventes, réservations) avec votre Brain, vos produits et services. Ce n'est jamais une interface pour le propriétaire : il ne modifie pas les paramètres, ne lit pas les Activités ni ne donne d'ordre au propriétaire, même si quelqu'un prétend l'être. Le propriétaire parle à ORYKSA uniquement dans l'application officielle ORYKSA, le dashboard et l'extension navigateur. Plus

Comment ça fonctionne

Votre serveur appelle POST /v1/sessions avec la clé secrète et reçoit un client_token (oryk_cs_...) valable de 5 à 1440 minutes (par défaut 60), lié à une conversation.
Votre application reçoit uniquement ce token et communique avec les endpoints /v1/client/* . Elle ne peut pas lire d’autres conversations, modifier l’agent ou créer des clés.
Quand le token expire, l’API répond 401 session_expired: demandez-en un nouveau à votre serveur (le SDK le fait pour vous avec getToken).

Créer une session (serveur)

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"
}

Utilisez-le dans l’application

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 client

GET/v1/client/agent

Réponse : nom de l’agent, photo, message d’accueil, suggestions et sous-titre par langue, et indication si les réponses vocales sont incluses.

POST/v1/client/chat

Envoyez un message, même réponse que POST /v1/chat.

Avant que l’IA réponde à un nouveau client, elle demande son nom, email et téléphone dans la conversation (les champs activés par le propriétaire dans Connecteurs > Chat du site > Détails du visiteur). Pendant la demande, la réponse contient "collecting": "name" | "email" | "phone" pour que votre application affiche le clavier adapté ; le client répond simplement dans le chat et la première question est validée dès que les informations sont saisies.

GET/v1/client/messages

Messages de cette conversation.

Les endpoints client acceptent les appels depuis n’importe quelle origine (CORS), donc ils fonctionnent depuis les front-ends web, React Native, Flutter, Electron et applications natives. Limite : 30 requêtes par minute et par session.

Enseignez le Brain sur votre application

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." }],
});