Documentation

Creating your account

All three products share one account and one sign-in. You set this up once, and it works for whichever products you decide to use — now or later. You do not need to already be a client of Pearl Organisation to sign up.

1. Open the sign-up page. From the main products site, choose Get Started or Sign Up. You'll be asked for an email address — use one you check regularly, since this is where all account notices (renewal reminders, receipts, security alerts) will be sent.
2. Verify your email address. A six-digit code is emailed to you within a few seconds. Copy that code into the sign-up page to prove the email address is really yours. If it doesn't arrive within a minute or two, check your spam or promotions folder before requesting a new code.
3. Choose a password. Pick something you don't use anywhere else. From this point on, you'll sign in with your email and this password — the one-time code is only needed during sign-up, or later if you ever need to reset your password.

Signing in later

Return to the products site and choose Sign In, then enter your email and password. If you've forgotten your password, choose Forgot password — you'll be emailed a fresh one-time code, and after entering it you can set a new password and you'll be signed in automatically, without any extra steps.

Your dashboard

Once you're signed in, the page called Subscriptions is your home base. Think of it as the control room for everything you've activated. From there you can:

• See every product on your account, and whether it's active, past due or cancelled
• Open each product's settings page: Pearl AI with its usage card, the Pearl AI Chat configurator with its Conversations tab, and the Pearl Workstation Agent manager with its Activity logs and screenshots
• Copy the activation key for Pearl AI Chat and Pearl Workstation Agent
• Download the invoice for every purchase, top-up and extra from the Billing page
• Turn on two-step verification from the Security tab
• Open your Pearl Marketplace dashboard in one click
• Go to checkout to add another product to your account

If you visit this page while signed out, you'll be sent to the sign-in page first and brought straight back here afterwards.

Signing in to Pearl Marketplace

Your Pearl Products account also works on Pearl Marketplace, with the same email and password. From your dashboard you can open your marketplace dashboard in one click, and come back the same way, without signing in again.

If you don't have a marketplace business profile yet, one is set up for you automatically. It stays unpublished until you choose to publish it.

Already a Pearl Organisation client? Your products are managed from your client workspace instead, and the site takes you there automatically.

Two-step verification

Two-step verification adds a one-time code to your sign-in, so your password alone isn't enough to get into your account. It's optional, and you can turn it on or off at any time from the Security tab of your dashboard.

• Choose how you get the code: by WhatsApp or by email.
• Signing in: after your email and password, enter the code we send you to finish signing in.
• Two-step verification is also available for sign-ins on Pearl Marketplace.

Good to know.

• Each code works for 5 minutes. After 5 wrong tries, request a new one.
• You can resend a code up to 3 times, a minute apart. For your safety, only a limited number of codes can be sent per hour.
• You can choose to trust the device you're signing in on, so it won't ask for a code there again for 30 days.

PEARL AI

What Pearl AI is

Pearl AI is an artificial-intelligence service you can talk to, or build into your own software. In plain terms: you send it a question or a piece of text, and it writes back a natural-language answer — similar to the well-known consumer AI chat tools, but made available to you as a building block you can use in your own product, website, or internal tool.

Two ways to use it, depending on how technical you want to get:

• The ready-made chat page. If you just want to chat with it directly, Pearl AI includes its own page under your account, laid out like a familiar chat app — a list of your past conversations down the side, a "new chat" button, and a light/dark appearance toggle. No setup involved.
• The API. ("API" stands for Application Programming Interface — a fancy term for "a way for one piece of software to talk to another.") If you or a developer wants to build Pearl AI into a website, app, or automated workflow, you connect to it using a small piece of code and a private key, covered later in this section.

The Pearl AI chat page

The chat page is Pearl AI ready to use, with nothing to set up. Open it from Subscriptions → Pearl AI. Alongside your past conversations and a light/dark toggle, you can:

• Talk instead of type: use voice input, or hands-free mode for a spoken back-and-forth.
• Show it something: attach an image or use your camera, and ask about what it sees.
• Search the web: for up-to-date questions it searches live and lists the sources it used.
• Create images: describe what you want and choose square, portrait or landscape. Ask for a transparent background for logos and icons, use Try another version for a different take, and download the result in one click.
• Copy with formatting: the Copy button keeps headings, bold text and bullet points, so replies paste cleanly into emails and documents.
• Suggested follow-ups appear under replies so you can keep going with one click.

Everything on the chat page uses your Pearl AI credits, the same as the API.

Everything the chat page can do

The Pearl AI chat page at products.pearlorganisation.com/pearl-ai is more than a chat box. Here is what you can do, and where to find each feature.

Modes

Click Modes beside the message box (or press Alt+M) and choose how Pearl AI should think. The message box and suggestions change colour so you always know which mode is on, and each chat remembers its mode.

• General: everyday questions, ideas and help.
• Image: every message creates or edits a picture: logos, posters, social posts and banners.
• Coding: working code first, short explanations, help with errors.
• Research: searches the web live, compares sources and shows where facts came from.
• Writing: emails, posts, rewrites and editing in the tone you want.
• Data & Analysis: works through numbers step by step, with tables and charts.
• Marketing: campaigns, ad copy, social plans and SEO ideas.

Live replies and stopping

Answers appear word by word as Pearl AI writes them. While a reply is coming in, the send button turns into a stop button: press it to stop the reply. The part already written is kept, and you are only charged for that part.

Images

Ask Pearl AI to create or redesign an image, or switch to Image mode. It picks the right shape (square for logos, tall for posters, wide for banners) and gives logos a transparent background. While the image is being made, an animated preview shows progress. Under each image you can open it full size, download it, or press Try another version.

Reading your documents

Press + and choose Upload a document, or drag a file onto the chat. Pearl AI reads PDF, Word (.docx), Excel (.xlsx), CSV and plain text files up to 5 MB, then answers questions about them: summaries, key dates, risks in a contract, totals in a spreadsheet. Follow-up questions in the same chat keep using the document. Scanned PDFs (photos of pages) cannot be read yet.

Charts

Ask for a chart, for example "show my monthly sales as a line chart", or upload a spreadsheet and ask for one. Pearl AI draws bar, line, area, pie and doughnut charts from your figures. Hover over the chart to see exact values, use Show data to see the numbers as a table, or Download PNG to save the picture.

Voice

Press Listen under any reply to hear it, or turn on Hands-free to talk with Pearl AI out loud. In Voice settings you can switch on Natural voice (HD) and choose from ten human-sounding voices. The HD voice uses AI credits, about 2 cents per minute of speech; if it is not available, the standard voice of your browser is used instead.

Editing a message

Point at one of your earlier messages and press Edit. Change the text and press Save & send: that message and everything after it is replaced with a new answer.

Saving as PDF or Word

Under each reply, PDF and Word save that answer together with your question. To save the whole chat, press Export in the top bar. Images and charts are included. Word files open in Microsoft Word.

Sharing a chat

Press Share in the top bar and then Create public link. Anyone with the link can read a copy of the chat; photos and documents you uploaded are never included. Use Update with latest messages to refresh the copy, or Stop sharing to take the page down. Shared pages are hidden from search engines.

Activity

Activity & logs in the sidebar lists your conversations with the number of messages and the credits used in each. Open one to see every message, its cost and response time, or export everything as a CSV file.

What uses credits

Messages, live web searches, created images and the natural HD voice use AI credits. Uploading documents, exporting, sharing and editing are free.

The playground

The quickest way to see what Pearl AI can do, before creating an account or writing any code, is the playground. Open the Playground page from the products site and start typing a question — you'll get a reply within a few seconds.

The playground exists so you can judge, in your own words and on your own topics, whether Pearl AI's answers are useful to you before committing to anything. It isn't meant to be used as a permanent tool — for ongoing use, create an account and either use the full chat page or connect to the API.

Authentication

Authentication simply means "proving who you are" before the system lets you in. Pearl AI uses two different methods depending on what you're doing:

To get an API key: sign in, open Subscriptions → Pearl AI, and choose Generate API key. This key is a long string of letters and numbers that acts like a password for your account's AI access — anyone who has it can use your account and your credits, so treat it with the same care as a password.

Your first request

This part is written for a developer connecting Pearl AI to their own software. If that's not you, feel free to skip ahead to Credits & usage.

Pearl AI's chat endpoint ("endpoint" = a specific web address your code sends a request to) accepts a short conversation and sends back a reply, in the same general shape used by most AI chat services — so if a developer has connected to one of these before, this will look familiar.

curl https://products.pearlorganisation.in/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "system", "content": "You are a concise, helpful assistant." },
      { "role": "user", "content": "Summarize what Pearl AI does in one sentence." }
    ]
  }'

// Node.js
const response = await fetch("https://products.pearlorganisation.in/api/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    messages: [
      { role: "system", content: "You are a concise, helpful assistant." },
      { role: "user", content: "Summarize what Pearl AI does in one sentence." }
    ]
  })
});

const data = await response.json();
console.log(data.choices[0].message.content);

# Python
import requests

response = requests.post(
    "https://products.pearlorganisation.in/api/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "messages": [
            {"role": "system", "content": "You are a concise, helpful assistant."},
            {"role": "user", "content": "Summarize what Pearl AI does in one sentence."},
        ]
    },
)

print(response.json()["choices"][0]["message"]["content"])

Request options

These are the extra settings a developer can include alongside the conversation itself:

A successful reply includes the AI's answer, plus a short usage summary showing how much of your credit balance that one request used.

Endpoints & models

Every request uses your API key (it starts with pai_) in the Authorization: Bearer header. The base address is https://products.pearlorganisation.in/api.

Models

pearl-4-mini is fast and low-cost, and is used when you don't name a model. pearl-4 gives higher accuracy and better reasoning. Choose one with the model field in your request.

Limits and usage

Each API key can make up to 60 requests a minute. Every reply shows the credits that request used and the credits you have left.

Assistants & variables

An assistant is a saved set of instructions for one job, for example replying to support tickets, summarising leads, or checking quality. Each assistant has its own address, and you call it with your normal API key, so your code only has to send the conversation.

The monthly plan includes 1 assistant and the 12-month plan includes 2. You can add more for $20 each; see Plans & pricing for how extras work.

Creating an assistant

1. Open Pearl AI → Configure → Assistants and choose + New assistant.
2. Give it a name and write its instructions: what it should do and how it should reply.
3. Wherever something changes from one request to the next, write a variable in double curly brackets, such as {{customer_name}} or {{plan}}. Each variable you type is listed under the instructions automatically.
4. Save. The Code button shows a ready-to-copy example with the assistant's own address.

Calling an assistant

curl https://products.pearlorganisation.in/api/v1/assistants/YOUR_ASSISTANT_ID/chat/completions \
  -H "Authorization: Bearer pai_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [ { "role": "user", "content": "Hello" } ],
    "variables": { "customer_name": "Asha", "plan": "Pro" }
  }'

The values in variables are filled into the instructions before the reply is written. If a variable the assistant needs is missing, the request is refused with a message naming it.

Common mistake: the assistant ID (it starts with asst_) goes in the address, while your API key (it starts with pai_) goes in the header. Sending the assistant ID as the key returns an error saying so.

Switching assistants on and off

You can switch an assistant off without deleting it; a switched-off assistant replies that it is unavailable. You can have as many switched on as your plan allows. To switch on another, switch one off or add an extra assistant.

Every reply from an assistant is paid for from your Pearl AI credits, the same as a normal request.

Tools, knowledge & testing

Each assistant card in Pearl AI → Configure → Assistants has buttons that make the assistant more useful. Everything you set up here is used automatically when your app calls the assistant through the API.

Tools

Tools let the assistant look things up and take actions in your own systems while it answers, for example checking an order's status or creating a booking. Add your own web address as a tool, or connect an MCP server (many services such as Notion offer one; some ask you to sign in once). For tools that change something, you can switch on Ask before acting: the assistant then asks the user to confirm before it goes ahead. Every tool call is logged, and the answer lists the tools it used in tool_calls.

Knowledge

Knowledge is what the assistant should know about your business. Add notes, exact questions and answers, up to 5 documents (PDF, Word or text, up to 5 MB each) and your website, which Pearl reads and keeps up to date. For each question, Pearl adds only the parts of this knowledge that match it, so answers stay focused and use fewer credits.

Try it

Try it opens a chat with the assistant right on the page, working exactly as your app would: the same instructions, variables, knowledge and tools. Each answer shows the knowledge and tools it used, its size and cost, and Show as API request gives you the matching request to copy into your code. Answers here use your credits like API calls and appear in the Activity log as playground tests.

Advanced options

Four optional settings for apps that need more than a simple question and answer. They work with /v1/chat/completions and with your assistants (background answers are for assistants only).

JSON answers

Ask for the answer as data your code can read straight away. Use {"type": "json_object"} for any JSON, or give a schema to get exactly the fields you need. The answer is in choices[0].message.content as text and, ready to use, in choices[0].message.parsed.

curl https://products.pearlorganisation.in/api/v1/assistants/YOUR_ASSISTANT_ID/chat/completions \
  -H "Authorization: Bearer pai_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [ { "role": "user", "content": "I want to cancel order A-1001, it arrived broken." } ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "ticket",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "intent":   { "type": "string", "enum": ["cancel", "refund", "question", "other"] },
            "order_id": { "type": "string" },
            "urgent":   { "type": "boolean" }
          },
          "required": ["intent", "order_id", "urgent"],
          "additionalProperties": false
        }
      }
    }
  }'

If the schema itself cannot be used, the request is refused with 422 and a message saying what to change.

Streaming

Add "stream": true and the answer arrives word by word as it is written, so your users see it straight away. The reply is a stream of data: lines (server-sent events) in the same shape as OpenAI's chat API: each piece has its text in choices[0].delta.content, the last piece also carries usage and credits, and the stream ends with data: [DONE]. When the assistant uses tools, the tools run first and the answer then follows in pieces.

const res = await fetch("https://products.pearlorganisation.in/api/v1/assistants/YOUR_ASSISTANT_ID/chat/completions", {
  method: "POST",
  headers: { "Authorization": "Bearer pai_YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ stream: true, messages: [{ role: "user", content: "Tell me about your plans" }] })
});
const reader = res.body.getReader(), decoder = new TextDecoder();
let buffer = "";
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  const events = buffer.split("\n\n"); buffer = events.pop();
  for (const e of events) {
    if (!e.startsWith("data: ") || e === "data: [DONE]") continue;
    const piece = JSON.parse(e.slice(6));
    if (piece.error) { console.error(piece.error.message); continue; }
    process.stdout.write(piece.choices[0].delta.content || "");
  }
}

Threads: Pearl keeps the conversation

Normally your app sends the whole conversation with every request. With a thread, Pearl remembers it for you. Send "thread_id": "new" with the first message; the answer includes a thread_id (it starts with thr_). From then on send only the newest message with that thread_id. Pearl uses the last 40 messages of the thread for each answer.

// first message
{ "thread_id": "new", "messages": [ { "role": "user", "content": "Hi, I'm Asha from Dehradun." } ] }
// every message after that - only the new one
{ "thread_id": "thr_rof6mpn5sg7wcpju5rx9rhyn", "messages": [ { "role": "user", "content": "What's my name?" } ] }

A thread belongs to the assistant that started it. Read it back with GET /v1/threads/{thread_id}/messages and delete it with DELETE /v1/threads/{thread_id}. When you use a thread, "Ask before acting" also keeps track of the conversation by itself.

Background answers

For long tasks, add "async": true. Pearl replies at once with status 202 and a job ID (it starts with job_), then writes the answer in the background, usually within a minute. Collect it with GET /v1/jobs/{job_id} (its status goes from queued to running to done or failed), or let Pearl send it to your server with a webhook. Background answers can be combined with threads and JSON answers, but not with streaming.

Assistant webhooks

A webhook is your own web address that Pearl sends a message to after each answer an assistant gives through the API, and when a background answer is ready or has failed. Set it up with the assistant's Webhook button in three steps: add your address (it must start with https://), copy the signing secret (it is shown only once), and send a test.

What Pearl sends

A POST with a JSON body. The type is assistant.reply, assistant.failed or test; the body also includes the assistant, the thread_id or job_id when there is one, and the full answer in response. These headers come with it:

Checking the signature

The signature is an HMAC-SHA256 of the time, a dot, and the raw body, made with your signing secret. Work it out yourself and compare; also refuse messages older than 5 minutes.

<?php // PHP
$body = file_get_contents('php://input');
$sig  = $_SERVER['HTTP_PEARL_SIGNATURE'] ?? '';
preg_match('/t=(\d+)/', $sig, $t);
preg_match('/v1=([a-f0-9]+)/', $sig, $v1);
$expected = hash_hmac('sha256', ($t[1] ?? '') . '.' . $body, getenv('PEARL_WEBHOOK_SECRET'));
if (!$t || !$v1 || !hash_equals($expected, $v1[1]) || abs(time() - (int) $t[1]) > 300) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);   // $event['type'], $event['response'] ...
http_response_code(200);

Delivery and retries

Answer with any 2xx status within 10 seconds. If your server does not answer or answers with an error, Pearl tries again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then stops. The Webhook panel lists recent events with their result and the next try. Lost the secret? Create a new one there; the old one stops working at once.

Credits & usage

Rather than charging by obscure technical units, Pearl AI keeps things simple: your account has a credit balance, shown in plain terms, and every question you ask uses a small amount of it.

• Checking your balance: open Subscriptions → Pearl AI to see how much you have left and a history of past usage.
• Free trial: a brand-new account gets a short free trial the very first time it sends a message — through either the chat page or the API — so you can confirm everything works before paying for anything.
• Running low: if your balance reaches zero partway through your billing cycle, further requests are politely declined until you add more credit. If you're a developer, make sure your integration shows a friendly message in this situation rather than a technical error (see Errors below).

Activity log

Every Pearl AI request on your account is recorded in one activity log, whether it came from the chat page, your API key or one of your assistants. Open it from Activity in the chat page's side panel, or from the usage card on your Pearl AI settings page.

• Each entry shows when the request was made, where it came from and the credits it used. Open an entry to see the full question and reply.
• Search the log, and export it as a CSV file for your own records.
• Your history is kept for as long as your account exists, and only you can see it.

Errors & limits

If something goes wrong with a request, the API replies with a status code explaining why. Here's what each one means and what to do about it:

What Pearl AI Chat is

Pearl AI Chat is a chat agent — often called a widget, meaning a small self-contained piece added to a page — that you place on your own website. Visitors see a chat bubble, usually in a corner of the screen, and can ask it questions about your business at any time of day.

Unlike a general AI chatbot, it only answers using information you give it — your own text, your policies, your product details, or documents you upload — so answers stay accurate to your actual business rather than guessing.

Everything about it is managed from one place: a five-tab settings screen called the configurator. The five tabs are Setup, Knowledge, Domains & Embed, Conversations, and Billing — each covered in its own section below.

Adding it to your site

1. Activate Pearl AI Chat on your account from the checkout page, if you haven't already done so.
2. Open the configurator from your dashboard: Subscriptions → Pearl AI Chat.
3. Set up your agent using the Setup and Knowledge tabs below — this only takes a few minutes and can always be changed later.
4. Copy your embed code from the Domains & Embed tab. This is a small snippet of code that tells your website to load the chat widget.
5. Paste it into your website. If you or someone who manages your website can edit its HTML, paste this snippet in, just before the closing </body> tag near the bottom of the page.

<script
  src="https://clientworkspace.pearlorganisation.in/pearl-chat-widget.js"
  data-key="YOUR_ACTIVATION_KEY">
</script>

Once this is pasted in and saved, the chat bubble appears on your site automatically within a few seconds of a page loading — there's nothing else to install. From here on, everything you change in the configurator (the welcome message, what it knows, and so on) takes effect immediately, with no need to touch your website's code again.

Setup tab

This tab controls first impressions — how the agent looks and how it opens a conversation:

• Branding — upload your logo and choose a display name for the agent, so it feels like part of your own site rather than a generic add-on.
• Welcome message — the first thing a visitor reads when they open the chat window.
• Starter questions — a handful of ready-made questions shown as clickable buttons, giving visitors an easy way to begin instead of facing a blank text box.

In plain terms: good starter questions are simply the things people already ask you most often — for example "What are your opening hours?" or "How do I book an appointment?" You can change these at any time as you learn what visitors actually ask.

Knowledge tab

This is the most important tab — it decides what the agent actually knows. It will only ever answer using what you've added here; it does not make anything up about your business.

• Written text — type or paste information directly, such as frequently asked questions, your policies, or details about what you offer.
• Document upload — upload PDF, Word or plain-text files (up to 5 MB each). Each file is safety-checked, then its text is added to what the agent knows, with no retyping.

Domains & Embed tab

This tab has two jobs. First, it's where you find the embed code described earlier. Second, it lets you list exactly which website addresses (called domains) the widget is allowed to run on — for example www.yourbusiness.com. This is a safety measure: even if someone else got hold of your embed code, the widget simply won't appear on a domain you haven't approved.

Add every domain and subdomain where you plan to actually use the widget — including a staging or test site, if you use one.

Webhook. This tab is also where each agent's Webhook block lives, for sending finished conversations, with an optional summary and your own fields, to your server. See Webhooks.

Conversations tab

Every conversation visitors have with your agent is kept in the Conversations tab of the Pearl AI Chat configurator. If you run several agents, pick one in the agent bar at the top and the list switches to that agent's conversations.

• The list shows the newest conversations first, 20 per page, with the date, the number of messages and the visitor's first question.
• Search and date filters narrow the list to a word, a phrase or a date range.
• Badges flag what needs your attention: Unanswered (the agent couldn't answer from your content), Needs reply and AI paused (see Live takeover below), and whether the conversation was delivered to your webhook.
• Click a conversation to open the full chat, with day separators and times. The expand icon opens it full screen; press Esc to close it.

The Unanswered marks are the quickest way to see what your content is missing. Add the answer on the Knowledge tab and the agent will use it from then on.

Live takeover

You can step into any conversation and reply as your team, straight from the Conversations tab.

• AI replies switch: each conversation has an on/off switch in its header. When it's off, the agent stays silent in that conversation only.
• Reply box: type at the bottom of the conversation. Enter sends, Shift+Enter starts a new line. Sending a reply switches the AI off for that conversation automatically.
• What the visitor sees: while the AI is paused, the visitor is told a team member will reply shortly. Your reply appears in their chat within a few seconds, labelled as a team reply, and a dot appears on the chat button if the window is closed.
• Handing back: use Turn AI back on in the banner, or the switch, and the agent carries on with the full conversation in view.
• Live updates: new visitor messages appear on their own while a conversation is open, and the list refreshes itself.

Team replies never use credits. Only the account owner can pause the AI or reply.

Webhooks: conversations sent to your server

A webhook sends each finished conversation to an address on your own server, with an optional summary and the details you choose to pull out, so it can go straight into your CRM, helpdesk or records. Each agent has its own webhook.

Setting it up

Open the Domains & Embed tab and find the Webhook block. If you run several agents, pick the agent in the agent bar first. Each step turns green when it's done and the next one opens:

1. Address: a full https:// address on your server, for example https://yourdomain.com/pearl-webhook, then press Save.
2. Signing secret: press Create secret. It's shown masked, with Show and Copy buttons. Copy it to your server, which uses it to check that each delivery really came from us; we store it encrypted. Create a new secret replaces it after you confirm, so update your server when you do.
3. Test: sends a sample conversation (event webhook.test) and shows your server's answer.
4. Turn on automatic sending: the switch unlocks once the address and secret are saved.

Choosing what to include

Under What to include in each delivery, the agent can read the conversation and fill in details for you before it's sent.

• Summary: switch it on for a short, neutral summary of the conversation, up to 60 words.
• Fields: add up to 8. Each field has:
  • a name, such as customer_name: lowercase letters, numbers and underscores, starting with a letter, up to 40 characters (summary is reserved);
  • a type: Text, Number, Yes/No, Email, Phone, Date (sent as YYYY-MM-DD) or One of a list (2 to 10 choices);
  • How to find it: a short instruction of up to 150 characters, for example "Customer's city, if they mention it."

Only what was actually said in the conversation is used. If something isn't mentioned, its value is null; nothing is guessed. The example delivery in the block updates to show your own fields.

Cost and limits. Pulling out a summary or fields uses the agent's normal credits, the same way a chat reply does, once per delivery. To keep it light, only the most recent part of a long conversation (about the last 8,000 characters) is read. If you haven't switched on a summary or added any fields, nothing extra runs and nothing extra is charged.

When deliveries are sent

• Automatically (conversation.ended): about 5 minutes after the visitor's last message. Each conversation is sent once. If the visitor comes back and writes again, the whole updated conversation is sent again.
• By hand (conversation.manual): the Send to webhook button on any conversation in the Conversations tab sends it straight away, even while automatic sending is off. If the agent has no webhook yet, it offers a Set up webhook button that takes you to the block.
• Automatic sending covers conversations from the last 24 hours, and only from the moment you turned the webhook on.
• A failed delivery isn't retried automatically. The conversation shows it as failed with your server's answer, and you can resend it with Send to webhook.

What your server receives

A POST with a JSON body. Messages have the role visitor, agent (the AI) or team (a reply from your dashboard), and up to 1,000 messages are included. Inside conversation, visitor_ref is an anonymous ID that stays the same for the same visitor browser, and ai_paused is true when your team has taken over.

{
  "event": "conversation.ended",
  "delivery_id": "3f6c2a9e-8d1b-4c1e-9a52-7b0e1d4f9c21",
  "sent_at": "2026-09-28T15:42:10+05:30",
  "agent": { "number": 1, "name": "Support Assistant" },
  "conversation": {
    "id": 18342,
    "started_at": "2026-09-28T15:31:02+05:30",
    "last_message_at": "2026-09-28T15:36:48+05:30",
    "message_count": 3,
    "visitor_ref": "a1b2c3d4e5f60718",
    "ai_paused": false
  },
  "messages": [
    { "role": "visitor", "text": "Hi, I'm Asha from Delhi. Do you ship to Canada? We'd order about 50 units.", "at": "2026-09-28T15:31:02+05:30" },
    { "role": "agent", "text": "Yes, we ship to Canada in 5 to 7 working days.", "at": "2026-09-28T15:31:05+05:30" },
    { "role": "team", "text": "Hi Asha, this is Priya from our team. Happy to help with your order.", "at": "2026-09-28T15:36:48+05:30" }
  ],
  "extracted": {
    "status": "ok",
    "summary": "Asha from Delhi asked about shipping to Canada for about 50 units. The team followed up to help with the order.",
    "fields": {
      "customer_name": "Asha",
      "city": "Delhi",
      "quantity": 50,
      "email": null
    }
  }
}

extracted is only included when you've switched on a summary or added fields. Its status tells you how it went:

• ok: the summary and fields were filled in (anything not mentioned is null).
• empty: the conversation had no messages to read.
• no_credits: the agent's credits had run out, so nothing was pulled out.
• skipped, or any other value: extraction didn't run this time.

Whatever the status, the rest of the delivery (the conversation and all its messages) is always complete.

Headers on every delivery

• X-Pearl-Event: the event name, the same as event in the body.
• X-Pearl-Delivery: a unique ID for this delivery.
• X-Pearl-Timestamp: when it was sent, in Unix seconds.
• X-Pearl-Signature: sha256= followed by an HMAC-SHA256 of timestamp + "." + raw body, made with your secret.

Checking the signature

Always check it before trusting a delivery. Use the raw body exactly as received, not re-encoded JSON, and reject timestamps older than 5 minutes. The same examples are in the Webhook block, under What we send and how to check it.

// Node.js (Express)
const crypto = require("crypto");

app.post("/pearl-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const ts = req.get("X-Pearl-Timestamp") || "";
  const sig = req.get("X-Pearl-Signature") || "";
  const expected = "sha256=" + crypto.createHmac("sha256", process.env.PEARL_WEBHOOK_SECRET)
    .update(ts + "." + req.body).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  if (!fresh || sig.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).end();
  }
  const event = JSON.parse(req.body);
  // save event.conversation, event.messages and event.extracted
  res.status(200).end();
});

<?php
// PHP
$body = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_PEARL_TIMESTAMP'] ?? '';
$sig  = $_SERVER['HTTP_X_PEARL_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, getenv('PEARL_WEBHOOK_SECRET'));

if (abs(time() - (int) $ts) > 300 || !hash_equals($expected, $sig)) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);
// save $event['conversation'], $event['messages'] and $event['extracted']
http_response_code(200);

# Python (Flask)
import hmac, hashlib, os, time
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/pearl-webhook")
def pearl_webhook():
    body = request.get_data()
    ts = request.headers.get("X-Pearl-Timestamp", "")
    sig = request.headers.get("X-Pearl-Signature", "")
    expected = "sha256=" + hmac.new(os.environ["PEARL_WEBHOOK_SECRET"].encode(),
                                    ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    if abs(time.time() - int(ts or 0)) > 300 or not hmac.compare_digest(expected, sig):
        abort(401)
    event = request.get_json()
    # save event["conversation"], event["messages"] and event.get("extracted")
    return "", 200

Good to know

• Answer with any 2xx status within 10 seconds. Do slow work after you've answered.
• The same conversation can arrive more than once (sent by hand, or after the visitor writes again). Use conversation.id as the key and replace what you stored before.
• Only public https addresses are accepted. Redirects aren't followed, and addresses on private or internal networks are refused.
• Changing the address or the secret clears the last test result, so send a new test afterwards.

Multiple languages

The agent automatically notices which language a visitor is writing in and replies in that same language, translating your knowledge on the fly. This means you only ever need to write your content once — typically in whichever language you're most comfortable with — and visitors elsewhere can still get an answer in their own language.

Working with several agents

Your plan includes 1 agent. You can add more for $100 each, for example one for sales and one for support, or one per website, app or CRM.

• Each agent has its own look, knowledge, allowed domains and embed code, so each can be trained on different documents.
• Your first agent uses your plan's activation key and can't be removed. Every extra agent gets its own key (it starts with agt_).
• Switch between agents with the agent bar at the top of the configurator. Every tab then shows and saves that agent's settings.

Extra agents stay active until your plan's current end date. See Plans & pricing for how extras work.

Credits & billing

Like Pearl AI, Pearl AI Chat runs on a credit balance, always shown to you in plain dollar terms rather than technical usage units. From this tab you can:

• See how much of your included credit has been used so far this billing period
• Add more credit instantly by card, if you're getting close to your limit
• Look back through your full purchase history

If your credit runs out and isn't topped up, visitors will see a brief "temporarily unavailable" notice in the chat window instead of the agent failing silently — so you'll always know to check this tab if that happens.

Top-ups can be any amount from $5 to $2,000. You can also add extra agents from here, at $100 each; they stay active until your plan's current end date.

What Pearl Workstation Agent is

Pearl Workstation Agent is a small application you install on your team's work computers. It shows how each computer is used during working hours: active time, idle time and breaks, which apps and websites are used, and regular screenshots. It works on Windows and Mac.

It is priced per computer: $200 a month (or $1,920 for 12 months) for each computer it's installed on. Each computer uses one licence, also called a seat, so ten computers need ten.

You also get an end-of-day report and instant alerts for idle time, overrunning breaks, suspicious activity and possible data leaks, sent by email to the people you choose.

Installing the agent

1. Activate Pearl Workstation Agent and choose how many computers you need to start with. You can add more at any time.
2. Copy your activation key from Subscriptions → Pearl Workstation Agent. It is a unique code tied to your account and your purchase.
3. Download and run the installer on the computer (Windows or Mac).
4. Enter your activation key when the installer asks for it. The key is checked against the computers left on your plan, and the computer then appears in your list.

After that, the agent starts with the computer and runs quietly in the background. Nothing else is needed on that computer.

Guided setup for a new computer

The Setup tab shows how many computers are connected and how many are online right now. To add one, choose Set up another computer and follow the steps. Each step turns green when it's done and the next one opens.

You don't need to type a computer ID. Each computer gets its own ID automatically when it connects. The last step waits for the new computer and turns green on its own the moment it checks in. If it doesn't, make sure the computer is online and the installer finished without errors.

Setting up your team

Open Subscriptions → Pearl Workstation Agent → Configure and go to the Team tab. This tells the system who works on which computer, so reports show real names instead of computer IDs.

1. Add your departments, for example Sales, Support or Design. Each department can have its own working hours and its own report recipients.
2. Add each person with their name and work email, and choose their department.
3. Link each person to their computer. Every computer you've installed the agent on appears in the list, ready to be assigned.
4. Choose who receives reports for each department, such as a team lead or manager. You can add more than one email address.

You can change any of this later. When someone joins, leaves or moves to another department, update the Team tab and the next reports follow the change.

Working hours & breaks

The Working hours tab tells the system what a normal working day looks like, so time outside it isn't counted as idle and breaks are judged fairly.

• Working days and hours: for example Monday to Friday, 9:30 to 18:30. Set them once for everyone, or differently for each department.
• Time zone: reports and alerts follow the time zone you choose, which helps teams working across different countries.
• Breaks: add breaks such as lunch or tea, with their usual time and how long each is allowed to last. A sensible set of breaks is filled in to start with, and you can change it.
• Idle threshold: how many minutes without keyboard or mouse activity count as idle time.

Reports & alerts

In the Reports & alerts tab, switch on the emails you want and choose who receives each one. Every email is sent under your business name, so your team sees it comes from you.

Pearl AI summaries

Switch on Pearl AI in the same tab to add a short, plain-language summary to your reports: what the day looked like, who needs attention, and what changed from usual. Pearl AI summaries and alert checks use your Pearl Workstation Agent credits.

Test email and health check

Use Send test email to check that reports reach the right inboxes before the first real one goes out. The health check on the same page shows whether emails are being delivered and whether Pearl AI is working, so you know straight away if something needs attention.

Activity logs & screenshots

The Activity logs tab lets you go from your whole team down to a single computer's day.

• Departments: one card per department with the number of computers, how many are online now, and today's active and idle time. Computers not yet placed in a department appear under Unassigned.
• Computers: inside a department, one card per computer with the employee's name and code, online status, last seen time and today's active/idle bar.
• Timeline: open a computer to see its activity hour by hour. Pick a date, and filter by apps, idle time, power events or screenshots. Long days are split into pages.
• Screenshots: each screenshot is its own line in the log, with the date, time and employee. Click the line to open it in a full-size viewer. Use next/previous or the arrow keys to move through the day, click to zoom, and press Esc to close.

Screenshots are private. They are never stored at a public address; each one opens through a link that works only for your signed-in account and expires within minutes.

Managing computers

From Subscriptions → Pearl Workstation Agent, you can see every computer currently using a seat: when it was set up, and when it last checked in. If you need to cover more computers than your current plan allows, you can purchase additional seats from the same page at any time.

Adding computers: choose Add computers on the same page. Each extra computer is a fixed $200 and stays active until your plan's current end date (see Plans & pricing).

What gets collected

In plain terms, Pearl Workstation Agent records how the computer is used during working hours, so you can see how work time is spent:

• Active and idle time, based on keyboard and mouse activity
• Which apps and websites are in use
• Power events, such as the computer starting, sleeping or shutting down
• Screenshots at regular intervals

This information belongs to your account only. Screenshots are private and open only through short-lived links for your signed-in account.

Removing a workstation

To free up a seat — for example, when someone leaves the team or a computer is retired — open Subscriptions → Pearl Workstation Agent and remove that computer from the list. The freed seat can then be used to set up a different computer. To remove the application itself from the computer, uninstall it the normal way you'd remove any other program.

Managing a subscription

Every product you turn on creates its own subscription under your account, each with its own status, its own renewal date, and — for Pearl AI Chat and Pearl Workstation Agent — its own activation key. You manage all of them in one place, your Subscriptions page.

Plans & pricing

Each product is its own subscription. Pay month by month, or for 12 months at once and save 20%.

How extras work

• Extra assistants, agents and computers are a fixed price, on monthly and 12-month plans alike, whatever day you add them.
• They stay active until your plan's current end date. Adding extras never changes that date.
• When the plan renews, it goes back to what the plan includes. Add extras again if you still need them.
• Add them from that product's settings page, or at checkout when you buy the plan.

Moving to 12 months, or adding time

Switching from monthly to the 12-month plan starts the 12 months when your current month ends, so you keep the days you've already paid for. You can also add more time to an active plan; it's added after your current end date.

Usage credits

• Each product has its own credit balance. Credits are never shared between products.
• Top up any amount from $5 to $2,000, at any time.
• Every new plan comes with credits worth 10% of its price.
• Credits are worked out from what each request actually uses, and your dashboard shows what you've used and what's left.
• If credits run out, that product's AI features pause until you top up. Credits stay on your account after a plan ends, but the AI features stay off until you renew.

Billing & invoices

Every purchase, top-up and extra is listed on your Billing page, with its invoice ready to download.

Paying through a link from our team

Prefer to speak to someone first? Our team can send you a secure payment link for any plan or extra. Once it's paid, your account is set up automatically and your login details are emailed to you.

Renewals & grace period

Plans don't charge your card automatically. A few days before a plan's end date, you'll get an email reminder with a direct link to renew for another month or another 12 months.

If the renewal isn't paid by the end date, nothing is switched off straight away: the plan gets a 3-day grace period to sort out payment. If it's still unpaid after that, the plan is cancelled.

When a plan renews, it goes back to what the plan includes. Extra assistants, agents or computers bought for the previous period need to be added again if you still need them.

Cancelling

There's no long-term lock-in. You're free to simply let a subscription lapse at its next renewal rather than paying again. If Pearl AI is cancelled, your API key and assistants stop answering once the current period ends. If Pearl AI Chat is cancelled, your agents stop responding on your site once the current period ends; if Pearl Workstation Agent is cancelled, its active seats stop reporting once the current period ends.

Security & privacy

• All traffic to and from PEARL PRODUCTS travels over an encrypted connection.
• Your API key and activation keys are unique to your account. Treat them like passwords, and generate a new one if you ever suspect one has been seen by someone else.
• Pearl AI Chat only answers using the knowledge you've explicitly added — it does not browse your website on its own or pull in anything you haven't given it.
• Pearl Workstation Agent activity is tied only to your account's own seats and computers — it is never mixed with or visible to any other customer's data.
• Two-step verification by WhatsApp or email is available on every account. Each code expires after 5 minutes.
• Pearl AI Chat webhook deliveries are signed with your secret, which we store encrypted, and are only ever sent to public https addresses.
• Workstation screenshots are never stored at a public address. Each one opens through a private link that expires within minutes.

Live system status

Want to check whether Pearl AI, Pearl AI Chat, or Pearl Workstation Agent is running normally right now — or see details of a recent issue? The system status page shows the current state of each product, a day-by-day uptime history, and a log of any past incidents, including when each one started and when it was resolved.

View live system status

Glossary

Plain-language definitions for terms used throughout this guide.

API

"Application Programming Interface" — a way for one piece of software to talk to another, used by developers to connect Pearl AI to their own website or app.

API key

A private code that proves a piece of software is allowed to use your Pearl AI account.

Activation key

A code tied to a Pearl AI Chat or Pearl Workstation Agent subscription, used to connect a website or computer to your account.

Widget

A small, self-contained piece of functionality added to a web page — in this case, the Pearl AI Chat bubble.

Agent

One Pearl AI Chat widget with its own knowledge, look and embed code. The plan includes 1; extras are $100 each.

Assistant

A saved set of Pearl AI instructions with its own address, called with your API key. Monthly plans include 1, 12-month plans 2; extras are $20 each.

Credits

Prepaid usage for a product's AI features, kept separately for each product. Top up from $5 to $2,000.

Extras

Assistants, agents or computers added on top of a plan, at a fixed price, active until the plan's current end date.

Variable

A placeholder such as {{customer_name}} in an assistant's instructions, filled from the values your code sends.

Seat

One licence for one computer under a Pearl Workstation Agent subscription.

Webhook

An address on your own server that Pearl AI Chat sends finished conversations to, signed so you can check they really came from us.

Live takeover

Pausing the AI in one conversation so someone on your team can reply to the visitor directly.

Two-step verification

An extra one-time code, sent by WhatsApp or email, needed to finish signing in.

Endpoint

A specific web address that a developer's code sends a request to.

Grace period

A short window after a missed renewal, during which a subscription keeps working while you sort out payment.

FAQ & troubleshooting

My webhook isn't receiving conversations

Open the Webhook block in the Domains & Embed tab and send a test. Your server must be on a public https address and answer with a 2xx status within 10 seconds. Automatic sending covers conversations that end after you turn the webhook on, about 5 minutes after the visitor's last message. A conversation marked failed can be resent with Send to webhook. See Webhooks.

Screenshots aren't showing in Activity logs

Check that the computer is online and the agent is running, then pick the right date and the Screenshots filter. Screenshot links expire after a few minutes for privacy, so if the viewer has been open a while, close it and click the line again.

I'm not receiving my two-step code

Check your spam folder, or that WhatsApp is working on your number. Wait a minute and resend (up to 3 times). If you're still stuck, contact support from the email address on your account.

The Pearl AI Chat widget isn't showing up on my site

Check two things: that the embed code is pasted in correctly, just before the closing </body> tag, and that the domain you're testing on is listed in the Domains & Embed tab — the widget deliberately won't load on a domain that hasn't been approved there.

My API requests keep failing with a 401 error

This means the system doesn't recognize your API key. Double-check it's included exactly as shown in Authentication, and that it hasn't been regenerated since — generating a new key immediately stops the old one from working.

A workstation isn't showing recent activity

Make sure that computer has an active internet connection, and that the agent hasn't been closed or blocked by antivirus or security software. If you need to reinstall it, use the same activation key — this will not create a duplicate seat for the same computer.

Can I use more than one product at the same time?

Yes. All three run independently under the same account, and turning one on has no effect on the others.

Do I need to already be a client of Pearl Organisation?

No — anyone can create an account and use any of these three products, regardless of any other relationship with Pearl Organisation.

Can I have more than one Pearl AI Chat agent?

Yes. Your plan includes 1 agent, and you can add more for $100 each. Each agent has its own knowledge, look and embed code, so you can have one for sales and one for support, or one per website.

My extra assistants, agents or computers disappeared after renewal

Extras last until the end date of the plan period they were bought for. When the plan renews it goes back to what it includes, so add the extras again if you still need them.

An assistant request says "Missing or invalid API key"

You have probably sent the assistant ID (it starts with asst_) as the key. The assistant ID goes in the address; your API key (it starts with pai_) goes in the Authorization header.

I'm not receiving Workstation reports or alerts

Open Subscriptions → Pearl Workstation Agent → Configure → Reports & alerts. Check the email is switched on and the right recipients are listed, then use Send test email. Also check your spam folder, and that each person is linked to a computer in the Team tab.

Getting support

If anything in this guide doesn't match what you're seeing, or you run into a problem it doesn't cover, contact support@pearlorganisation.com. Include the email address on your account and a short description of what happened — a screenshot helps too, if you can attach one.