API v1

REST and JSON. The Onix app itself uses the same API, so the data you see in the app comes through these endpoints.

Base URL: https://onix.sassly.ai/api/v1. Every path on this page is relative to the base URL. Request bodies are JSON (Content-Type: application/json). The full OpenAPI 3.1 spec is at /docs/openapi.yaml — import it into Postman, Insomnia, or an SDK generator.

Authentication

Creating an API key

1. Open Settings → API (requires the Manage API keys permission; Pro only).
2. Click Create key, give it a name (e.g. "CRM integration"), and choose a scope: read (read-only) or write (read and change data).
3. Keys start with onx_live_ and are shown only once. Keep them in a secret manager, never in frontend code or a repository.
4. Up to 10 active keys per workspace. Requests with a revoked key get 401.

export ONIX_API_KEY="onx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

An API key acts on behalf of the workspace and isn't limited by roles, so treat it like a password. Management endpoints (members, roles, settings, API keys, billing) are app-only. The API doesn't support CORS: call it from your server, not from browser JavaScript.

Response format

Successful responses are always {"data": …, "meta": {…}}; meta appears only when relevant. Errors always look like:

{
  "error": {
    "code": "validation_error",
    "message": "Workspace name must be 2–120 characters.",
    "fields": {"name": "Workspace name must be 2–120 characters."}
  }
}

• code is stable and safe to use in program logic; message is human-readable text that follows the language (header X-Locale: en|id).
• fields appears only on input errors, with a message per field.
• Times are always UTC in ISO 8601, e.g. 2026-10-08T02:30:00Z. Convert them to your own time zone for display; the Onix app uses the user's personal time zone, or the workspace time zone.
• Paginated lists accept page (from 1) and per_page (max 100, default 25 unless stated otherwise) and return meta.page, meta.per_page, meta.total, and meta.pages.

Rate limits

• 120 requests per minute per API key.
• Responses include the X-RateLimit-Limit and X-RateLimit-Remaining headers.
• Going over the limit returns 429 rate_limited with a Retry-After header (seconds until the next minute).

Error codes

Endpoints

The Permission column shows what an app user needs (set through roles); "—" means every workspace member. API keys are treated as holding every workspace permission and see all data.

Data limits (teams): permissions control menus & actions, while the conversations & tickets a user sees follow teams. Unassigned conversations are visible to everyone with interactions.view; conversations assigned to a Frontline team are visible only to that team's members; conversations assigned to a person are visible only to that person. Tickets without an assignee are visible to the members of their Back Office team; tickets with an assignee are visible only to participants (assignees, creator, people @mentioned). Team-only knowledge base articles are visible only to members of the chosen teams (no team = all teams). Pipeline leads without an owner are visible to the lead's team; leads with an owner only to that owner. The Owner, admin roles, and members with "Can view all data" see everything (channel access still applies). Data a user may not see returns 404.

Available with an API key

Onix app only

These endpoints accept only an app session (cookie + X-CSRF-Token). With an API key they return 403 forbidden.

Public

Live chat widget (public)

Called by the live chat widget (the livechat.js loader & the Onix iframe) without signing in. {key} = the channel\'s public key. Apart from config and logo, all of them use the visitor token in Authorization: Bearer. Full details: Live chat.

Channel API (channel key)

For your system sending customer messages to Onix through an API channel, with the channel key onx_ch_… in Authorization: Bearer (not a workspace API key). Agent replies are sent to your webhook. Guide, sample payloads, and signature verification: Channel API.

Examples

Who owns this key

curl -s "https://onix.sassly.ai/api/v1/me" \
  -H "Authorization: Bearer $ONIX_API_KEY"

{
  "data": {
    "user": {"id": 12, "name": "Budi Santoso", "email": "[email protected]", "avatar_url": null, "locale": "en", "timezone": null, "last_login_at": "2026-10-08T02:00:00Z"},
    "via": "key",
    "timezone": "Asia/Jakarta",
    "workspace": {
      "id": 3, "name": "Toko Budi", "slug": "toko-budi", "plan": "pro", "pro_until": "2026-11-08T03:15:00Z", "in_grace": false, "timezone": "Asia/Jakarta",
      "limits": {"channels": 4, "users": 10, "tickets_per_month": 200, "replies_per_day": 0, "ai_per_month": 2000, "ai": true, "api": true},
      "created_at": "2026-10-08T02:00:00Z"
    },
    "role": {"id": 1, "name": "Owner"},
    "is_owner": true,
    "is_platform_admin": false,
    "permissions": ["dashboard.view", "interactions.view", "interactions.reply", "interactions.assign", "templates.manage", "channels.manage", "settings.members", "settings.roles", "settings.billing", "settings.audit", "settings.workspace", "settings.api"],
    "channel_ids": null,
    "realtime": true
  }
}

In limits, 0 means unlimited. A null channel_ids means access to every channel. timezone is the effective zone (the user's personal zone, or the workspace zone).

Replying to a WhatsApp customer

Find unanswered conversations, then send a reply (requires a write key). The message goes out through the conversation's WhatsApp number and is recorded under the key's name.

curl -s "https://onix.sassly.ai/api/v1/interactions?tab=unreplied&per_page=5" \
  -H "Authorization: Bearer $ONIX_API_KEY"

curl -s -X POST "https://onix.sassly.ai/api/v1/interactions/42/messages" \
  -H "Authorization: Bearer $ONIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hi, your order shipped today 🙏"}'

{
  "data": {
    "id": 981, "interaction_id": 42, "direction": "out", "type": "text", "body": "Hi, your order shipped today 🙏",
    "media": null, "reply_to": null, "sender": {"name": "API · CRM", "user_id": 12, "jid": null},
    "status": "sent", "error": null, "reactions": [], "sent_at": "2026-10-09T03:15:00Z", "created_at": "2026-10-09T03:15:00Z"
  },
  "meta": {"replies": {"used": 1, "limit": 0}}
}

Messages rejected by WhatsApp are kept with "status": "failed" and the reason in error; resend them via /retry. At most 30 messages per minute per number (429 beyond that). Attachments: send multipart/form-data with a file field (up to 16 MB).

Member audit log since the start of the month

curl -s "https://onix.sassly.ai/api/v1/audit-logs?category=anggota&from=2026-10-01&per_page=20" \
  -H "Authorization: Bearer $ONIX_API_KEY"

{
  "data": [
    {
      "id": 41, "action": "member.invited", "label": "Invited a member", "category": "anggota", "icon": "user-plus",
      "target": "[email protected]", "details": "Role: Agent",
      "user": {"id": 12, "name": "Budi Santoso", "avatar_url": null},
      "ip": "203.0.113.10", "created_at": "2026-10-08T03:20:00Z"
    }
  ],
  "meta": {"page": 1, "per_page": 20, "total": 1, "pages": 1, "categories": [{"key": "anggota", "label": "Members & invitations"}, "…"], "users": [{"id": 12, "name": "Budi Santoso"}]}
}

JavaScript (Node 18+) and PHP

const res = await fetch("https://onix.sassly.ai/api/v1/members", {
  headers: { Authorization: `Bearer ${process.env.ONIX_API_KEY}` },
});
const { data, error } = await res.json();
if (error) throw new Error(`${error.code}: ${error.message}`);

$ch = curl_init('https://onix.sassly.ai/api/v1/roles');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ONIX_API_KEY')],
]);
$body = json_decode(curl_exec($ch), true);

Real-time events

The app receives events over WebSocket (Centrifugo) on the ws:{workspace_id} and user:{user_id} channels. Each event looks like {"event": "…", "data": {…}, "at": "…Z"}.

The conv:{id} channel is granted only if the user may view that conversation (channel access + team rules). When a conversation is assigned to another team/person, users who lose access are unsubscribed from its channel automatically.

The ticket:{id} channel is only granted to users who can open that ticket (participants, team members for tickets without an assignee, or those who see all data).

The live chat widget uses a separate visitor:{session} channel (token from POST /livechat/{key}/realtime) with the message, queue, typing, and read events — see Live chat.