ORYKSAORYKSADevelopers
Obter chaves de API

Sessões para aplicativos

Coloque o colaborador de IA dentro de apps móveis, desktop e web sem nunca enviar a chave secreta.

Só para clientes. Este canal atende os clientes da empresa (perguntas, vendas, agendamentos) com o seu Brain, produtos e serviços. Nunca é uma interface do dono: não altera configurações, não lê Atividades nem aceita ordens do dono, mesmo que alguém diga que é o dono. O dono fala com a ORYKSA só no app ORYKSA oficial, no painel e na extensão do navegador. Saiba mais

Como funciona

  1. O seu servidor chama POST /v1/sessions com a chave secreta e recebe um client_token (oryk_cs_...) válido de 5 a 1440 minutos (por padrão 60), ligado a uma conversa.
  2. A sua app recebe apenas esse token e acessa os endpoints /v1/client/*. Não consegue ler outras conversas, mudar o agente nem criar chaves.
  3. Quando o token expira, a API responde 401 session_expired: solicite outro ao seu servidor (o SDK faz isso automaticamente com getToken).

Criar uma sessão (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"
}

Usar na 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 do cliente

GET/v1/client/agent

Resposta: nome do agente, foto, saudação, sugestões e subtítulo por idioma, e se as respostas por voz estão incluídas.

POST/v1/client/chat

Envie uma mensagem, com a mesma resposta de POST /v1/chat.

Antes de a IA responder a um cliente novo, ela pede o nome, o e-mail e o telefone na conversa (os campos que o dono deixa ativados em Conectores > Chat do site > Dados do visitante). Enquanto pede, a resposta traz "collecting": "name" | "email" | "phone" para o seu app mostrar o teclado certo; o cliente responde no chat e a primeira pergunta é respondida assim que os dados estão completos.

GET/v1/client/messages

Mensagens desta conversa.

Os endpoints do cliente aceitam chamadas de qualquer origem (CORS), por isso funcionam em front-ends web, React Native, Flutter, Electron e apps nativas. Limite: 30 requisições por minuto por sessão.

Ensinar ao Brain sua 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." }],
});
AnteriorConversasPróximoEndpoints do widget