Iris Docs
Admin Start free

Preview. The public REST & realtime API, SDKs, and webhooks described here are in active development and not yet generally available — endpoints and payload shapes may change. The embeddable widget, operator console, and compliance controls are live today.

Quickstart

From zero to first message

Iris gives you three surfaces over one tenant: an embeddable widget, an operator portal, and a REST + realtime API. This guide gets a live conversation flowing in about five minutes.

You'll need a workspace. Create one free — your tenant slug and keys are issued instantly.

1

Embed the widget

Paste the snippet before </body>. It mounts inside a shadow DOM, so it never inherits or leaks your site's styles.



      

        
2
Mint a session token server-side
Exchange your secret key for a short-lived session. Tokens are never passed through query strings or exposed to the browser.

      

      


      

        
3
Answer from the console
Open the operator console. The moment a guest sends a message, a room appears in your queue with an Iris draft reply ready to send or edit.

      

    


    
    

      
Core concepts

      
A small vocabulary covers the whole platform.

      
    
        
  • Tenant — the isolated home for one workspace's data. Every API call is scoped to a tenant, enforced by row-level security.
    • 
        
  • Room — a single conversation thread between a guest (or verified user) and your operators.
    • 
        
  • Session — a short-lived, server-minted token that authorizes a specific end user inside a tenant.
    • 
        
  • Operator — a member of your team who answers rooms in the portal. Roles: owner, admin, operator, viewer.
    • 
        
  • Guest → linked identity — a conversation can start anonymous and upgrade to a verified Auth0/SSO identity mid-thread without losing history.
    • 
      

    


    
    

      
Authentication

      
Iris uses two key types. Know which one belongs where.

      
    
        
  • Publishable key (iris_pub_…) — browser-safe integration key for product APIs as they come online. The current widget bootstrap uses your tenant ID.
    • 
        
  • Secret key (iris_live_…) — server-side only. Keep it out of client code and use bearer session tokens for chat traffic.
    • 
      

      
Never expose a secret key in client code. Mint session tokens from your backend and hand only the session token to the widget.

      
Authenticate REST calls with a bearer header:

      
# every server-side request
Authorization: Bearer <session-token>

    


    
    

      
REST API

      
Base path /api/v1 on the API host. JSON in, JSON out, conventional status codes.

      
Endpoints

      
POST/session/guestStart or resume a restricted guest chat session

      
POST/session/exchangeExchange an upstream identity token for a chat token

      
POST/session/linkLink a guest conversation to a signed-in identity

      
POST/session/refreshRotate an active chat token

      
GET/channelsList visible conversation channels

      
POST/channels/:id/messagesPost a message to a channel

      
GET/widget-configRead published public widget branding


      
Example — post a message

      

    


    
    

      
Realtime & WebSocket

      
Connect to the realtime socket for live delivery, presence, typing indicators, and read-state sync. The transport reconnects automatically and resumes from REST state.

      
const ws = new WebSocket("wss://rt.irissays.com/ws", ["bearer", token]);
ws.onmessage = (e) => {
  const ev = JSON.parse(e.data);
  // ev.type: "message.new" | "presence.changed" | "typing.indicator"
  render(ev);
};

      
Realtime is read-optimized. Send messages over REST (POST /channels/:id/messages) — the socket echoes them back to subscribers.

    


    
    

      
Webhooks

      
Register an endpoint in Admin → Webhooks to receive signed event payloads. Verify every request with your signing secret.

      

        
EventFires when

        
          
message.createdA guest or operator posts a message

          
channel.createdA new conversation channel is created

          
channel.archivedAn operator archives a channel

          
identity.linkedA guest upgrades to a verified identity

          
presence.changedAn operator goes online, away, or offline

        
      

    


    
    

      
Client SDKs

      
Drop-in libraries for the surfaces you build yourself.

      

        
Web / React
@irissays/react · preview
An <Iris /> component plus headless hooks for fully custom UIs.

        
iOS (Swift)
IrisKit · preview
Swift Package with a UIKit & SwiftUI chat surface and background reconnection.

        
Windows host
WebView2 · reference
A reference WebView2 host embedding the widget in desktop apps.

        
Server (Node)
@irissays/node · preview
Mint sessions, call the REST API, and verify webhook signatures.

      

    


    
    

      
Compliance

      
Iris was built inside a HIPAA-regulated imaging network. These controls are defaults, configured per tenant in Admin → Compliance.

      
    
        
  • HIPAA & BAA — a Business Associate Agreement is available on Business and Compliance plans.
    • 
        
  • Tenant isolation — Postgres row-level security policies, verified by automated isolation checks on every deploy.
    • 
        
  • Append-only audit log — every message and admin action is recorded immutably and exportable to your SIEM.
    • 
        
  • Retention & evidence — per-tenant retention windows with scheduled purge drills that produce signed evidence bundles.
    • 
      

      
Need a security review or a signed BAA? Talk to our solutions team.