optic

API & widget reference

Build on Optic with a server-side REST API, or embed the chat widget on your site. Everything is scoped to the organisation that owns the key.

Authentication

Two key tiers, created in Settings → API keys. Keys are shown once and stored only as a hash.

sk_live_… secret — server-side only. Full org-scoped REST access. Send as Authorization: Bearer sk_live_…. Never expose in a browser.
pk_live_… publishable — browser-safe. Origin-locked, widget endpoints only. Used by the embed snippet.

REST API

Base URL https://getoptic.app/api/v1. Secret key required.

GET/api/v1/conversations?status=todo&account=:idconversations:read

List the org's conversations (joined account), ranked by impact. status defaults to todo.

POST/api/v1/conversationsconversations:write

Create a conversation. Body: { contact_email, subject, body, contact_name?, channel? }. The account is matched by email domain and impact is computed.

GET/api/v1/conversations/:idconversations:read

One conversation plus its full message timeline.

POST/api/v1/conversations/:id/messagesconversations:write

Post a reply or note. Body: { type: "agent" | "note", body, author? }. An agent message on an email conversation sends a real, threaded email.

GET/api/v1/accountsaccounts:read

The org's accounts with open-conversation counts.

GET/api/v1/patterns?date=YYYY-MM-DDpatterns:read

Support themes ("patterns") for a date; defaults to the most recent run. Returns available dates too.

Example

curl https://getoptic.app/api/v1/conversations \
  -H "Authorization: Bearer sk_live_your_key"

Embeddable chat widget

Paste this before </body>. Brand it in Settings → Chat widget; add your site to the key's allowed origins.

<script src="https://getoptic.app/widget.js"
        data-optic-key="pk_live_your_key"></script>
<script>
  // optional — link the chat to a signed-in user for impact scoring
  Optic('identify', { id: 'user_123', email: 'user@company.com', name: 'Jane Doe' });
</script>

Optic('identify', …) is optional — anonymous visitors work via a local session id. Commands: identify, open, close. Conversations land in your Inbox as the webchat channel; agent replies stream back to the widget live.

Widget endpoints (publishable key)

GET/api/public/widget/configwidget:config:read

Branding for the key's org. Used by the widget on load.

POST/api/public/widget/conversationwidget:conversation:create

Create or resume the visitor's conversation; returns a short-lived per-conversation Realtime token.

GET/api/public/widget/conversation?id=&token=widget:conversation:read_own

Read only the visitor's own conversation (customer + agent messages).

Rate limits, CORS & errors

Rate limits — REST: 120 req/min per key. Widget: 60 req/min per org+IP. Over the limit returns 429.
CORS — publishable keys are origin-locked; requests from origins not on the key's allowlist get 403. Secret keys are server-side and not origin-checked.
Errors — 401 invalid/revoked key · 403 wrong tier, missing scope, or disallowed origin · 404 not found / not yours · 429 rate limited.

Manage keys in Settings → API keys.