From zero to a live agent
Everything on this page describes shipped behavior, it works today, exactly as written.
Quickstart
1. Create your workspace. Sign up, verify your email, name the workspace. Your chat widget, knowledge base and provider config are created with it, every setting below is editable per workspace.
2. Teach Shinobi. In Knowledge, write articles or paste your help-center URL and import drafts straight off your site. Articles embed for retrieval automatically on save; Shinobi answers only from what lives there and records the questions it couldn't answer as gaps for you to fill.
3. Brand the widget. In Widget, set the display name, accent color, greeting, tagline, logo and position, and register the domains the widget may load on. The live preview shows exactly what customers get.
4. Install. Paste one line before </body> on your site:
<script src="https://main.d2q3vgt1xx9g5.amplifyapp.com/embed.js" async></script>On Shopify, use this version instead. It also signs the chat in as the store's logged-in customer, so order lookups skip the email code:
{% if customer %}<script>window.ShinobiChatIdentity = { email: {{ customer.email | json }}, name: {{ customer.name | json }} };</script>{% endif %}
<script src="https://main.d2q3vgt1xx9g5.amplifyapp.com/embed.js" async></script>The widget resolves your workspace from the page's origin, no keys or config in the snippet, nothing sensitive to leak.
Widget install details
Page rules live in the widget studio: an empty include list shows the widget everywhere; any exclude match wins; patterns support * wildcards (for example /checkout*). On phones under 480px the chat opens full-bleed.
Single-page apps can drive the widget programmatically once the loader has run:
window.ShinobiChat.open(); // open the chat panel
window.ShinobiChat.close(); // close itVisitor identity is progressive: anonymous chats work immediately; when order details are involved, Shinobi verifies the visitor's email with a one-time code before sharing anything account-bound. Sessions resume across page loads on the same site for 24 hours.
Custom tools
In App Store → Custom tools, point Shinobi at your own HTTP endpoints. Each tool is a name, a plain-language description (Shinobi decides when to call it from this), a URL template, a method, and optional headers. Header secrets are stored in AWS Secrets Manager under your tenant's own prefix and are never sent to the browser.
| Field | What it does |
|---|---|
| name | How the tool shows up in transcripts and usage events. |
| description | Tells Shinobi when the tool applies, write it like you'd brief a new hire. |
| url | Endpoint template; conversation values are substituted server-side. |
| method / headers | GET or POST, plus auth headers with secret values kept server-side. |
Public session API
The widget speaks a small JSON API you can also call directly, useful for custom frontends or native apps. All calls are scoped by registered origin and per-session bearer tokens; rate limits apply per IP and per session.
| Endpoint | Behavior |
|---|---|
| POST /api/public/session | ops: start (new session for a registered origin), resume, end, rate (CSAT 1–5). |
| GET /api/public/session | Poll messages since a cursor; returns presigned image URLs for attachments. |
| POST /api/public/send | Send a visitor message; streams the reply as NDJSON frames, final frame carries cited sources. |
| POST /api/public/upload | Presigned, prefix-scoped photo upload for the current session. |
| GET /api/public/widget-config | Widget branding for a registered origin, this is all the loader needs. |
| POST /api/public/agent | Publish's grounded Q&A endpoint: one bearer key, answers only from your live knowledge, sources attached. Schema at GET /api/public/agent/openapi. |
| POST /api/public/mcp | The same agent as an MCP server with one tool, ask_support_agent, for ChatGPT, Claude and any MCP-capable assistant. |
Your data stays exportable: Settings → Export streams conversations and cases as CSV at any time.
Security model
Tenant isolation. Every row in the platform carries a tenant id and every query runs through a tenant-scoped client, there is no code path that reads across workspaces.
Secrets. Model keys and tool credentials live in AWS Secrets Manager under tenant/<id>/*. Nothing secret is ever compiled into the browser bundle or the embed loader.
Identity. Console access is Cognito-backed with short-lived, httpOnly session cookies. Widget visitors verify by emailed one-time code (10-minute expiry, 5 attempts, hashed at rest) before Shinobi shares anything account-bound.
Origins. The widget renders only on domains you registered; unregistered origins get nothing, not even the config.
Your models. Default is our managed Bedrock pool with per-turn usage metering you can audit in the console; bring your own provider key and calls run on your account instead.