Knowledge Base & FAQ

1. Getting started

What can I do in the Perxona console?

The console is your control center for managing AI avatar, customizing avatars and voices, uploading documents, tracking usage, and accessing billing and support.

How do I create an AI avatar?

Two ways, both from the AI avatar page:

• Build by chatting — pick the “Customize your AI avatar” card. A guided conversation collects the avatar’s role and goal, lets you pick 1–4 supported languages, and optionally attach knowledge (upload up to 10 files, or scrape up to 30 web pages). Confirm, and the profile plus a starter storyboard are generated for you.
• Get started with a template — pick a card from the template carousel, review it in the Choose a template dialog, and press Apply. You get a ready-made avatar and storyboard you can edit freely.

2. Storyboard editing

How do I add and connect panels?

A storyboard is a series of panels, each representing one stage of the conversation.

• Add — drag a blank panel from the Panel drawer onto the canvas.
• Connect — draw a line between panels to define how the conversation can flow.
• An unconnected panel shows “Inactive”, with a hint that it activates once connected — an unconnected panel never takes effect.
• Click a panel to edit its goal and instruction on the right; badges on the panel show how many functions, knowledge files, media items, and surveys are attached.

For how to design the panels themselves — where to split scenes, how to write goals — see the Storyboard manual.

What is the “Global settings” panel?

The entry panel of every storyboard is shown as Global settings. It holds the storyboard-wide instruction, plus everything under Client display content: the Disclaimer, Suggested questions, Follow-up questions, and the Privacy Pop-up toggle. Whatever you put here applies to the whole conversation, not just one scene.

How do motions work — and what does the orange exclamation mark mean?

Drag a motion set from the Motion drawer onto a panel. Each motion set has a When (trigger timing) setting:

• Time — plays on an avatar state: idle, talking, listening, or loading.
• Intent: through a prompt — you describe in a short prompt when it should play, and the LLM decides.
• Match: specify a sentence — plays when the specified sentence matches.

An orange exclamation mark on a motion means: “Some motions in this set are incompatible with the selected AI avatar.” The motion’s skeleton doesn’t match the current avatar model, so those motions are filtered out automatically at conversation time and will not play. The rest of the set and your published avatar are unaffected — there’s nothing you need to edit.

How do I add knowledge or media to a scene — and unlink them?

Drag a file from the Knowledge base or Media drawer onto a panel.

• Knowledge: linked files show as chips under Knowledge(n) in the panel editor. To unlink one, click its minus (−) button — the file stays in your library, only the link is removed. Storyboard-wide knowledge lives in storyboard settings → global knowledge tab.
• Media: dropping a media file opens its Intent Description — a short note (max 64 characters) telling the avatar when to show it. Leaving it empty means the avatar has no cue to show the file.
• Media Global Settings (the gear icon in the Media section): turn on Display most relevant media only to show a single best-matching item per reply, storyboard-wide.

How do I add functions (tools)?

Open the Function drawer, press + Function to define one, then drag it onto a panel. Functions call an external API endpoint; the dialog has no type to choose. External API endpoints call hosts you registered under Management → Integration → External service. Editing a function updates every panel that uses it. See the Tools manual for schema-writing tips.

How do I switch storyboards, and what’s in storyboard settings?

In the storyboard toolbar, click the storyboard name to rename it inline, or click the chevron to open the picker (search, sort, and a + to create a blank storyboard). Each entry’s ⋮ menu offers Settings, Duplicate, and Delete (you can’t delete the storyboard currently in use).

Settings contains: storyboard name, description, icon and cover color, LLM-selectable (choose the language model), Chat mode (Free chat or Precise chat), AI avatar initiation mode (avatar-initiated or user-initiated) with the greeting prompt (max 1,000 characters), and AI avatar panel switching logic (guide panel switching by goal or by flow).

3. Avatar look, voice & publishing

What can I edit in the Avatar editor?

Switch the left rail from Storyboard to Avatar. The sidebar has three tabs:

• Profile — avatar model, name, personality description, and Voice: pick 1–4 supported languages, one voice per language, and a main language.
• Space — the background scene.
• Theme — how the widget looks and behaves: Input Mode (Text or Voice), camera angle and field of view, light/dark mode, bubble color, chat thumbnail and size, and the loading screen.

The preview mode dropdown switches between Full screen, Chat bubble, and Built-in presentation.

What’s the difference between Text and Voice mode?

The Input Mode setting on the Avatar editor’s Theme tab (Text or Voice) decides what a visitor sees when the widget opens:

• Text — a chat input box with suggested questions; visitors type. This is the default.
• Voice — a push-to-talk circle with live captions; visitors speak.

Visitors can switch between the two at any time (the speech view has a back-to-keyboard button, the chat view has a microphone button). Every message records which one was used, and appears as Text input or Voice input in Conversation history.

How do I publish, share — and unpublish?

• Publish applies your avatar so visitors can reach it. After changing anything under Theme, re-publish (and refresh embedded code) so the changes go live.
• Share opens a dialog with two parts: an Embed code card — open it to set up embedding (with Mobile Deployment enabled, Web Embed Code and Mobile Deployment appear as tabs) — and a share section where you generate a live link + QR code and share it (generating a link publishes the avatar automatically; changing the link key invalidates the old link).
• Unpublish: click the ⋯ button next to Publish and choose Unpublish. Once unpublished, this AI avatar won’t be visible on your website.

4. Knowledge base

What are the file format and size limits?

• Supported formats: DOC / DOCX / CSV / TXT / PDF.
• Up to 20 files per upload.
• Storage capacity is shared between Knowledge base and Media, and depends on your plan (e.g. 5 MB on Free, 50 MB on Core; custom for enterprise plans). The Limits tab under Subscription shows usage.
• Website scraping counts each captured page as one file against your storage.

What do the file statuses mean, and what can I do in each?

To delete an Active file, first unlink it from every storyboard (the status popover lists where it’s linked), then delete it.

Can I add a description to a file?

Yes — during upload or later via Edit description (up to 200 words for knowledge files — words are split on spaces, so Chinese and Japanese text rarely reaches the limit). The description is a note for yourself; it is not used when the avatar searches your documents. It does make the file easier to find in the file list.

5. Media

What are the media limits and rules?

• Supported formats: JPG / PNG / MP4 / PDF.
• Up to 20 items per upload; storage is shared with the Knowledge base (same plan quota).
• Statuses work the same way as knowledge files, and an item used by a storyboard cannot be deleted until unlinked.
• Descriptions are supported and help the system match media to the conversation.

6. Conversation history

What do the columns mean?

The History button opens the full transcript; each message is tagged Text input or Voice input.

How does search work?

• The text search box matches message content — what visitors and the avatar actually said.
• To filter by avatar, use the AI avatar dropdown filter. It filters by the avatar itself (its internal ID), so results include all conversations of that avatar — including those from before a rename. The list always displays the avatar’s current name.
• Date range and device filters can be combined with both.

Can I download the raw data?

Yes. Press Generate CSV, pick a date range (up to 30 days per export), and a zipped CSV downloads automatically when ready. Columns: session ID, customer ID, agent ID and name, speaker, input type, message content, attachments, and timestamp.

7. Profile & account

How do I change the console language?

Click your profile picture (top right) → My profile → Settings tab → Default language. English, Traditional Chinese, and Japanese are available.

How do I reset my password?

Once logged into the console, click your profile in the top right corner, select “My Profile,” and click “Reset Password” to update it.

I forgot my password. What should I do?

Click “Forgot Password” on the console login page and follow the instructions to verify your email and reset your password.

What should I do if I can’t access my account?

Please check your login credentials and internet connection. If the issue persists, contact our support team for assistance.

8. Management — General

What’s the difference between Display name and Workspace ID?

• Display name — the friendly name shown in the console header and in invitation emails. You can change it anytime; it never affects URLs.
• Workspace ID — the identifier used in your public live link URLs (…/{region}/{workspace ID}/…). It is chosen once during onboarding and cannot be changed afterwards — existing live links would stop working otherwise.

What are the idle time settings?

Under Management → General:

• Idle session time (5–60 minutes, default 5): if a visitor stays inactive in a conversation longer than this, the session is closed automatically.
• Storyboard editor inactive time (10–30 minutes, default 10): if a storyboard editor is idle past this, a confirmation dialog appears; with no response the edit lock is released so a teammate can take over.

What is the Landing page (showcase page)?

A hosted page listing your published AI avatars. Toggle it on under General → Feature toggles → Landing page, copy the link, and press Edit to select your featured AI avatars. Only avatars that already have a live link can be shown; if you toggle the feature off and on, re-publish to refresh the list.

What is Behavior AI? Can I turn it off, and what does it affect?

Behavior AI is a library of pre-trained motion styles that lets the avatar pick expressive motions matching the emotional tone of each reply. The switch lives in General → Feature toggles.

• On — motion suggestions also consider motion descriptions and the avatar’s personality (advanced mode).
• Off — motions still play, but only based on each motion set’s trigger conditions (basic mode).

Turning it off only affects how motions are chosen — it never changes the text of the avatar’s answers.

9. Management — Subscription & billing

How do the plans compare?

• Free — 1 user seat, 1 published AI avatar, 20 credits/month, 5 MB knowledge & media, live link sharing (no website embed).
• Core — 14-day free trial, then $25/month (or $250 billed annually): 150 credits/month, 50 MB knowledge & media, deploy the widget to your own website.
• Enterprise — custom credits, storage, seats, and onboarding. Press Let’s talk to contact sales.

One credit corresponds to roughly 6 seconds of conversation time; credits reset each billing cycle.

Will I be charged during the free trial?

No, you won’t be charged during free trial. Billing only starts after the trial ends, unless you cancel beforehand.

How do I view payments and purchase history — and get a receipt?

Management → Subscription has three tabs: Limits (seat, publish and knowledge usage plus Credits), Payment (cards on file), and Purchase history (invoices). For receipts:

1. Check your email inbox (a receipt is automatically sent after purchase)
2. Click [View Order] in the email
3. Select [Generate Receipt]
4. Fill in your billing details and download the receipt

How do I cancel my subscription?

On the Your current plan card, open the gear menu → Cancel subscription. Your subscription will end after your billing period on the shown date — you keep full access until then, and you can resume before it ends.

How do I buy extra credits and check usage?

Extra credits are a monthly budget billed by usage: in the Limits tab, press Edit budget on the Credits row and set a monthly amount (about $0.095 per credit, up to 10× your plan quota). The same tab shows used vs. available credits, storage, and seats at any time.

10. Management — Team

How do I invite teammates?

You can invite team members by email through the console under the “Team” and “Member” section. Enter up to 10 email addresses per invitation; if you’re out of user seats, the console prompts you to upgrade first. New members join with the Operator role by default.

What do the member statuses mean?

• Activated — the member accepted the invite and can sign in.
• Pending — invited, not yet accepted.
• Inactivated — the invitation expired or failed; press Resend email.

Is there a limit on members?

Yes — user seats are part of your plan (e.g. 1 seat on Free and Core; more via enterprise plans). The Limits tab shows seats used vs. available.

How do roles and permissions work?

Built-in roles: Owner (full control, one per workspace, cannot be reassigned), Admin (full management), and Operator (the everyday builder: edits anything in the workspace that hasn’t been restricted in its Share settings, but can only delete the AI avatars, storyboards and media assets they created themselves). To change a member’s role, use the role dropdown in the Member tab.

You can also create custom roles in the Role tab: name the role (max 30 characters), tick View / Edit / Delete per area (General, Integration management, Security management, Billing information, Knowledge, Conversation history), and choose the Edit Scope — all AI avatars & storyboards, or only the member’s own.

11. Management — Integration

How do I deploy the widget to my website?

The embed code lives in each avatar’s Share dialog → Embed code card:

1. Add your site’s Domain under Deployment access control (mobile apps use a Bundle ID instead) — this creates the deployment key.
2. Copy the three snippets: import the Perxona SDK script, place the <sv-agent> element, or use the full sample page.

Management → Integration → Widget deployment lists every deployed key across the workspace. Each avatar can hold up to 3 keys; deleting a domain also deletes its key.

Who can configure external services and API keys?

Configuration of external services and API keys is restricted to users with Admin or Owner roles, as well as the creator of the respective storyboard, in order to ensure data security.

What are External service, API keys, and Data spec for?

• External service — register the API hosts (endpoint + Bearer token / API key / no auth) that your storyboard functions may call.
• API keys — organization-level keys for calling Perxona’s data APIs (conversations, messages, customers) from your backend, sent as the X-Inbound-Key header. Never expose them in browser code; revoking a key cannot be undone.
• Data spec — an OpenAPI-style schema describing the customer data you push into Perxona, which the avatar can then reference as variables in storyboards.

12. Privacy, data & terms

Does the avatar remember a returning visitor?

Yes — with one important condition. Your character can carry facts across separate conversations, but only for visitors your own website identifies: the embed code must pass a customer ID (customerRefId). For anonymous visitors nothing is remembered, and each conversation starts fresh.

Two more things worth knowing:

• What was learned is saved after a conversation goes idle, not mid-conversation — so it shows up in the next conversation, not the current one.
• There is no on/off switch, either per avatar or in workspace settings.

This is separate from Conversation history, which records every session regardless (see section 6).

Is my conversation data stored?

Yes. Perxona stores end-user conversation history to help AI avatar understand past context and deliver more personalized interactions. You can configure data retention settings based on your compliance needs.

How is memory data stored?

Conversation data is securely stored and encrypted. You can manage storage preferences in your organization settings.

Where are the Terms of Service and Privacy Policy?

Both are linked on every console sign-in page: Platform Terms of Service and Privacy Policy. For end users of your widget, enable the per-storyboard Disclaimer and Privacy Pop-up under Global settings → Client display content.

Where is the SDK documentation?

The sidebar’s SDK doc entry opens the developer documentation portal (docs.perxona.ai), covering the widget attributes, session tokens, and data APIs.