Docs

Everything you need to put Ontara on your website and answer visitors in any language.

Install the widget

Sign in, create a workspace, then open Chat widget in the dashboard. Copy your snippet and paste it before </body> on every page:

<script src="https://YOUR-LINGLY-HOST/w.js" data-site="pk_your_site_key" async></script>

The widget only works on the domain you registered and its subdomains (for example example.com also covers shop.example.com). Before installing, open the Test page from the dashboard to try it.

WordPress

Install the Ontara WordPress plugin, or paste the same snippet with any header and footer scripts plugin.

Single-page apps

Add the script once in your HTML template. It keeps working across client-side route changes.

JavaScript API

After the script loads, a small global object is available:

CallWhat it does
lingly.open()Opens the chat window, for example from your own “Contact us” button.
lingly.close()Closes the chat window.
lingly.identify({ userId, email, name, hash })Tells Ontara who the visitor is. See identity verification.
lingly.reset()Forgets the visitor, for example when a user signs out.
lingly.shutdown()Removes the widget from the page.
<button onclick="lingly.open()">Chat with us</button>

To pass a signed-in user before the script loads, set window.linglySettings = { user: { email, name } } above the snippet.

Translation

Set your team language under Team. When a visitor writes in another language, the message is translated for your team and the original is one click away. Your replies are translated into the visitor's language before they're delivered. The welcome message and automatic replies are translated too.

Turn translation on or off under Automation. The widget's own buttons follow the visitor's browser language (English, Chinese, Spanish, Portuguese, French, German, Japanese, Korean and Italian), or a language you choose.

AI answers

  1. Add content under Knowledge base: questions and answers, a web page URL, or plain text.
  2. Use Try the AI on the same page to see how it would answer.
  3. Under Automation, choose when the AI answers: only when nobody is online, or always first.

The AI answers only from your knowledge base and in the visitor's language. When it can't answer, or the visitor asks for a person, it hands the conversation to your team and stops answering in that conversation. It also stops as soon as a teammate replies.

When you're away

Team & roles

RoleCan
OwnerEverything, including billing.
AdminSettings, knowledge base, websites, invitations and billing.
AgentAnswer conversations and read the knowledge base.

Invite people from Team. They sign in with the invited email address to join. Every plan has unlimited seats.

Plans & limits

See pricing for what each plan includes. When a monthly limit is reached, live chat keeps working; AI answers and translation pause until the next month or until you upgrade. Conversations older than your plan's history period are deleted automatically.

Identity verification

When a visitor is signed in to your site, you can tell Ontara who they are and prove it, so nobody can pretend to be one of your users.

  1. In Chat widget → Identity verification, turn it on and copy the secret. Keep it on your server only.
  2. On your server, compute hex(HMAC-SHA256(secret, userId)).
  3. On the page, call lingly.identify({ userId, email, name, hash }).
// Node.js import { createHmac } from "node:crypto"; const hash = createHmac("sha256", process.env.LINGLY_IDENTITY_SECRET).update(user.id).digest("hex"); // PHP $hash = hash_hmac('sha256', $userId, getenv('LINGLY_IDENTITY_SECRET'));

Agents see a Verified badge next to the visitor. A call with a wrong hash is rejected. Visitors who only type their email in the chat are not marked as verified.

Email replies

When your reply is emailed to a visitor who has left, they can simply answer that email. Their answer appears in the same conversation, and quoted text and signatures are removed.

This needs a receiving domain. In Cloudflare Email Routing, send r-*@reply.your-domain.com to the Ontara Worker, then set INBOUND_EMAIL_DOMAIN=reply.your-domain.com. Only the visitor's own address can post into their conversation; automatic replies and bounces are ignored.

Notifications

Under Account → Browser notifications, each teammate can turn on notifications for the device they're using. When a visitor writes and the inbox isn't open, a notification appears; clicking it opens the conversation. Email alerts (under Team) still work as a backup.

React

npm install @lingly/react import { LinglyChat, useLingly } from "@lingly/react"; <LinglyChat siteKey="pk_your_site_key" user={user ? { userId: user.id, email: user.email, hash: user.linglyHash } : null} /> const { open } = useLingly(); // open(), close(), identify(user), reset()

The component renders nothing itself; it loads the widget once and keeps the visitor in sync with your signed-in user. When user becomes null, the widget forgets the visitor.

The package isn't published to npm yet. Until it is, the JavaScript API above does the same job in any React app.

WordPress

  1. Download the plugin, then in WordPress go to Plugins → Add New → Upload Plugin.
  2. Activate it and open Settings → Ontara Chat.
  3. Paste your site key. Optionally paste the identity verification secret so logged-in WordPress users show as verified.

REST API

Create a key under Developers and send it with every request:

curl https://YOUR-LINGLY-HOST/api/v1/conversations?status=open \ -H "Authorization: Bearer lk_your_key"
EndpointWhat it does
GET /api/v1/sitesYour websites.
GET /api/v1/conversationsNewest first. Filters: site, status (open or closed), limit (up to 100), before (the nextBefore value from the previous page).
GET /api/v1/conversations/:idOne conversation.
GET /api/v1/conversations/:id/messagesMessages in order. after = last seq you have.
POST /api/v1/conversations/:id/messagesReply as your team: {"body": "...", "name": "Bot"}. The reply is translated for the visitor. Send the same clientId again to retry safely.
POST /api/v1/conversations/:id/close · /reopenClose or reopen.
DELETE /api/v1/conversations/:idDelete the conversation and its messages for good.
GET /api/v1/visitors/:idVisitor details, including whether they're verified.

Each key allows 120 requests per minute. Errors return JSON like {"error": "not_found"} with a matching HTTP status.

Webhooks

Add an https endpoint under Developers and pick the events you want: conversation.created, conversation.closed, conversation.reopened, message.created, visitor.email_captured.

POST /your/endpoint Lingly-Event: message.created Lingly-Signature: t=1763100000,v1=5f2c… {"id": "evt_…", "type": "message.created", "createdAt": 1763100000000, "workspaceId": "ws_…", "data": {"conversationId": "conv_…", "siteId": "site_…", "visitorId": "vis_…", "message": {…}}}

To check a request, compute hex(HMAC-SHA256(secret, t + "." + rawBody)) and compare it with v1; reject timestamps older than five minutes. Answer with any 2xx status. Failed deliveries are retried for about 20 minutes, and an endpoint that keeps failing is paused. An event can occasionally arrive twice, so use id to skip duplicates.