curl -fsS "$QWRYAI_API_URL/me" \
-H "Authorization: Bearer $QWRYAI_API_KEY"
curl -fsS "$QWRYAI_API_URL/me" \
-H "X-API-Key: $QWRYAI_API_KEY"
```
## Capabilities
| Capability | Description |
| --- | --- |
| get_account_context | Show tenant, plan, auth method, scopes, and capabilities. |
| list_chatbots | List available chatbots. |
| get_chatbot | Inspect one chatbot. |
| list_conversations | List conversations. |
| create_conversation | Create a conversation. |
| get_conversation | Inspect one conversation. |
| get_conversation_messages | Read conversation messages. |
| send_message | Send a customer message and return AI stream events. |
| send_agent_message | Add a human agent reply. |
| add_internal_note | Add an internal note. |
| escalate_conversation | Escalate to human support. |
| resolve_conversation | Resolve the conversation. |
| mark_conversation_read | Mark the conversation read. |
| mark_conversation_unread | Mark the conversation unread. |
| search_knowledge | Search chatbot knowledge. |
| get_analytics_overview | View analytics overview. |
Developer access does not expose billing, user-management, destructive delete, or admin configuration tools.
## Revoke Access
Dashboard controls for revoking API keys and disconnecting OAuth clients are no longer available. To revoke the OAuth grant for your local CLI session and remove local credentials, run:
```bash
qwryai-cli auth:logout
```
## Troubleshooting
- Key is rejected: confirm the full key was copied, has not expired, and has not been revoked.
- Access stopped after plan change: Developer access follows the current active workspace subscription plan.
- Claude asks for approval: complete the QwryAI OAuth approval screen.
- OpenClaw or Cursor cannot connect: confirm the client is using remote HTTPS MCP and a bearer API-key header.
- CLI is not authenticated: run qwryai-cli auth:login again or set QWRYAI_API_KEY.
- CLI access is no longer needed: run qwryai-cli auth:logout to revoke the stored OAuth grant and remove local credentials.
- CLI command failed in CI: check error.code, error.statusCode, or error.httpStatus in the JSON output.
- A tool is missing: confirm the credential has the matching scope and the workspace is on a paid active plan.
---
# Backstage
Ask questions about your agent and workspace in a dedicated internal conversation.
## Overview
Backstage is an internal assistant for understanding your QwryAI workspace. Open Backstage from the selected agent's sidebar and ask about usage, settings, instructions, or authoring drafts. It uses the access available to your workspace account.
> **Current capabilities**: The live Backstage experience supports read-only workspace questions. Use the relevant configuration page to make changes; a suggested change in a conversation is not a saved setting.
## Start a conversation
1. Select the workspace and agent you want to inspect.
2. Open Backstage and start a new chat.
3. Ask a specific question, naming the time period or setting when relevant.
4. Read the response and use follow-up questions to clarify the result.
5. Open History to return to an earlier Backstage chat.
## Useful questions
- Which model and instructions does this agent use?
- Summarize the current usage information available for this workspace.
- What authoring drafts are available for this agent?
- Explain the configuration I should review before changing an action.
## Access and availability
Backstage follows your workspace permissions. If a session is unavailable, verify the selected agent and workspace, then start a new chat or reopen an accessible entry from History. Do not interpret an unavailable-data message as a zero usage result.
## Related guides
- [Instructions and model configuration](/docs/user-guides/agent-management/instructions)
- [Usage](/docs/user-guides/workspace-management/billing-usage)
- [Actions overview](/docs/user-guides/actions/overview)
---
# Instructions
Define your agent's behavior, guardrails, model, and response style.
## Overview
Open Build → Instructions to edit the directions your agent follows. General instructions describe its role and response behavior. Guardrails set boundaries for requests it should decline, clarify, or hand off.
## General instructions
- Describe the customers and business the agent supports.
- Specify tone, language, and the amount of detail customers need.
- Explain how to use the knowledge sources and what to do when information is missing.
- Name the situations that require an action or human handoff.
- Avoid conflicting rules or promises the connected tools cannot fulfill.
General instructions, response guardrails, and the model configuration for the QwryAI support agent.
## Guardrails
Use the Guardrails editor for clear boundaries: information the agent should not disclose, claims it should not make, and situations that need a person. Test the boundary with both a request it should accept and a closely related request it should reject or escalate.
> **Enforce permissions in your systems**: Instructions guide the AI's behavior. Your API, integrations, and approval policies must still enforce access to business data and write operations.
## Model configuration
| Control | Purpose |
| --- | --- |
| Model | Choose from the models available in the workspace selector. |
| Temperature | Adjust the Reserved-to-Creative setting from 0 to 1 in steps of 0.1. Evaluate the effect on your own support questions. |
## Compare before saving
1. Edit General, Guardrails, or Model configuration.
2. Choose Compare to evaluate the candidate settings alongside your saved settings.
3. Use representative customer questions, including missing information and handoff cases.
4. Review whether the change improves correctness and tool selection.
5. Save the settings you want to use, then retest the deployed channel.
## Channel instructions
A channel can use shared global instructions or its own configuration. When a channel is set to sync with global instructions, editing that shared text affects the other channels that sync with it. Review the channel's sync setting before saving.
- [Help Page configuration](/docs/user-guides/agent-management/help-page)
- [Playground](/docs/user-guides/agent-management/playground)
---
# Procedures
Write a repeatable customer process with instructions, conditions, and actions.
## Overview
Procedures organize a multi-step support process. The editor also uses the term Playbook for the saved document. Define when the process should run, write its steps, reference the actions it needs, and publish it when the preview is ready.
## Create a procedure
1. Open Build → Procedures and create a new procedure.
2. Describe the process to start with AI assistance, or write the instructions in the editor.
3. Set the name and When to use description.
4. Add the instructions, conditions, actions, and context values needed for the process.
5. Save the draft and test its branches in Preview.
6. Choose Publish and confirm the procedure becomes Live.
## Write the instructions
| Input | What it inserts |
| --- | --- |
| Enter | A new instruction. |
| / | Conditional structure such as If / Else. |
| @ | A referenced Action. |
| {{ | A context value, such as customer name, email, phone, customer ID, conversation ID, or channel. |
Keep each step focused on one outcome. State the condition before the action it controls, and give each branch a clear end or next step. Use the action picker so the document refers to the configured action rather than only its name in prose.
## Use actions
A procedure can reference actions that retrieve data or perform a task. Configure and test those actions first. Check their required inputs, response fields, channel support, and approval requirements before using them in a procedure.
When asking the authoring assistant to use private actions, save the procedure first so it has a saved scope to work in. Review AI edits as changes to the draft before publishing.
## Preview the process
- Test the request that should start the procedure.
- Exercise both sides of every condition.
- Try missing input, unavailable actions, and a failed external operation.
- Check that the next step uses the previous action's result correctly.
- Verify customer input and approval pauses before the process continues.
## Draft, Live, and Paused
| State or control | Meaning |
| --- | --- |
| Save | Stores the authoring draft. Published conversations keep using the existing published version. |
| Publish | Publishes and activates the current saved procedure when validation succeeds. |
| Live | The published procedure is active. |
| Paused | The deployment is disabled until resumed. |
| History | Review saved revisions and publication information from the procedure's management controls. |
> **Confirm publication**: A saved draft is not a live procedure. Resolve any publication error and confirm Live before relying on the process in customer conversations.
## Related guides
- [Action approvals](/docs/user-guides/agent-management/approvals)
- [Testing and publishing actions](/docs/user-guides/actions/testing-and-publishing)
---
# Action approvals
Review the exact input before an action performs a business write.
## Overview
Action approvals provide a review point for operations governed by an approval policy. Open Build → Approvals to inspect pending work. A decision applies to a particular request revision and its input.
## Review a request
1. Open the approval work queue and select a request. Use Search Action inputs to find a specific operation.
2. Read the Action subject and input. Check the record, values, and requested business change.
3. Review the approval policy, required decision count, and required permissions.
4. Check expiry and any earlier decisions before recording your own.
5. Enter a rationale and choose Approve Action or Reject Action.
## Understand the policy
| Policy detail | Meaning |
| --- | --- |
| Required decision count | The number of distinct approvers needed. |
| Required permissions | Permissions an eligible reviewer must have. |
| Rejection behavior | Whether any rejection stops approval or a quorum policy applies. |
| Expiry | The time after which the pending request cannot be approved. |
| Revision | The particular input version your decision covers. |
## Record a decision
Rejection requires a rationale. Explain the business reason or evidence you reviewed. An approval is recorded toward the policy; the action can continue only once the policy is satisfied. A rejection prevents execution of that input according to the policy.
> **Checks run again**: Eligibility, permissions, policy, revision, and expiry are checked when you decide. If the request changed or expired, reopen the current request rather than treating the previous decision as approval for new input.
## An empty queue
No Actions need approval means there is no pending work in the loaded queue. It does not mean every action in the workspace is automatically approved. Check the action's selected policy and enabled configuration when a workflow does not reach the expected approval step.
---
# Widget Studio
Create reusable interfaces for action results and customer interactions.
## Overview
Open Build → Widgets to manage the UI cards your agent can display. My widgets contains saved widgets; Create widgets offers starting points for a new design. A widget can be linked to an action and reused.
The saved widget contains real website setup instructions and a link to QwryAI.
## Create a widget
1. Open Create widgets and choose a template or start a new widget.
2. Use the builder to describe the interface, edit its content, and review the preview.
3. Define the values the widget expects and configure its functions where needed.
4. Check the card with representative data and each interactive state.
5. Save the widget, then link it from a compatible action's Widget section.
## Work in the builder
| Surface | Use it for |
| --- | --- |
| AI builder | Describe a new design or a change to the current widget. |
| Preview | Inspect the resulting card and its interactions. |
| Code | Edit the widget implementation and its Schema, Default data, and named examples. |
| Functions | Configure the behavior connected to widget interactions. |
| States | Choose when sections are visible, using data conditions and groups. |
## Configure widget functions
| Function type | Behavior |
| --- | --- |
| Call API | Call an API and use the returned data. |
| Run client-side code | Invoke a function implemented by the website host. |
| Send message | Send the configured message into the conversation on the visitor’s behalf. |
| Open link | Open a URL, email client, or phone dialer. |
| Open embedded page | Open an HTTPS page inside the web widget. |
| Dismiss widget | Close the widget. |
| Set variables | Update the widget’s state values. |
Review the fields shown for the selected function type, including inputs, return fields, and On execute, On success, or On failure behavior where available. Link the function to the intended control and test its result from the deployed channel.
The Visit QwryAI button uses an Open link function with the real QwryAI website URL.
## Control visibility with states
1. Open States and choose Add your first state or Add state.
2. Give the state a clear name and choose its Visibility.
3. For conditional visibility, add the data conditions and combine them with And or Or. Use groups when conditions belong together.
4. Review the Default data and named examples in Code so you can exercise each state.
5. Check both matching and non-matching values in Preview, then save the widget.
States change which widget sections appear based on data. They are separate from action triggers, which determine when an entire widget action starts.
## Check each preview surface
Use Widget, Chat bubble, and Agent page below the preview to inspect the card in its customer-facing context. Switch between light and dark preview themes and check the card’s buttons, long text, and conditional states before attaching it to an action.
## Design for real data
- Use consistent input names and types so action mappings remain understandable.
- Provide useful empty, loading, success, and error states where the interaction needs them.
- Check long text and missing optional values.
- Test keyboard operation and a narrow mobile viewport.
- Confirm that any function which changes business data follows the required action and approval workflow.
## Reuse and manage widgets
Search My widgets to reopen an existing design. Use the widget's management controls to rename or manage it. When linking an existing widget to another action, review its input schema and all existing uses before editing the shared design.
> **Linking is shared**: Changes to a reusable widget can affect more than one action. Keep its inputs compatible or update every affected action's mapping.
## Import and export
The Widget Studio options menu supports downloading and uploading widget JSON files. Uploads must be smaller than 2 MB and pass widget validation; save after upload to keep the change. The custom action's Widget section also supports a .widget file. Use this to reuse a design, then review its inputs and functions in the destination action before enabling it.
- [Widgets and response mapping](/docs/user-guides/actions/widgets)
---
# Channels
Choose where customers can reach your agent and configure each experience.
## Overview
Channels control how customers access the selected agent. Configure the website chat bubble, a hosted Help Page, and the messaging integrations available in your workspace. Each channel has its own connection, presentation, and action compatibility.
Manage the website chat bubble or set up another customer channel from the selected agent.
## Website chat
Open the chat bubble deployment settings, configure its appearance and behavior, and copy the embed script into your site. Add the site's domains to the allowed-domain settings when restrictions are enabled. Test the published page, not only the editor preview.
- [Embed and control the website widget](/docs/user-guides/agent-management/deploy)
- [Client-side actions](/docs/user-guides/actions/client-side-actions)
## Help Page
A Help Page provides a hosted customer-facing destination. Configure its content, assets, theme, capabilities, instructions, and compatible actions, then enable its visibility and open the public URL.
- [Configure a Help Page](/docs/user-guides/agent-management/help-page)
## Messaging channels
Use the integration page for the messaging provider you want to connect. Complete its authorization and account selection, then send a test message from that provider. A connected account and an enabled action are separate settings: review both.
- [Messaging platforms](/docs/user-guides/integrations/messaging-platforms)
- [WhatsApp](/docs/user-guides/integrations/whatsapp)
- [Instagram](/docs/user-guides/integrations/instagram)
- [Messenger](/docs/user-guides/integrations/messenger)
- [Telegram](/docs/user-guides/integrations/telegram)
## Action compatibility
Select each action's enabled channels in its editor. Client-side actions need a browser host; automatic widget triggers run only on website chat. Review the available channel controls and verify the action from the intended customer entry point; an editor selection alone is not proof of runtime compatibility.
## Before launch
- Verify the customer entry point on desktop and mobile.
- Confirm the right instructions, model, and welcome content.
- Test a normal answer, an action, and a human handoff.
- Check the conversation appears in the correct workspace.
- Confirm disabling a channel produces the intended customer-facing state.
---
# Help Page
Publish a branded page where customers can talk to your AI agent.
## Overview
Help Page is a hosted channel for your agent. Its editor contains Overview, Display, Voice, and Actions tabs, with a customer preview. On narrow screens, use the Preview tab to view the customer surface. The public page uses the configuration you save and publish.
## Set up the page
1. Open Channels and select Help Page.
2. Review the model and instructions, including whether they sync with global instructions.
3. Configure the Display sections and review the preview.
4. Choose the enabled actions that should be available on this channel.
5. Save any pending configuration changes. In Overview, enable Help Page visibility, or use Deploy → Enable help page.
6. Open Deploy, confirm Help Page is live, and use Copy URL or Open to test the published address as a visitor.
## Display configuration
| Section | Controls |
| --- | --- |
| General | Page title and favicon. Favicon uploads accept JPG, PNG, or SVG up to 1 MB. |
| Content | Welcome message, message placeholder, and suggested messages. |
| Assets | Select the Light or Dark scheme, then choose its logo and hero image. Each upload accepts JPG, PNG, or SVG up to 1 MB. |
| Capabilities | Voice-to-text and attachment configuration toggles. Check visitor-side availability; a toggle does not guarantee the capability is released. |
| Style | Default theme, visitor theme switch, color controls, and field glow. |
| Buttons | Enable and configure Primary, Secondary, and Link buttons. |
## Voice availability
The Voice tab currently shows Voice mode as Coming soon, with its switch disabled. Display → Capabilities also contains a Voice to text setting, but the published visitor page currently marks its voice-to-text button Coming soon and disables it even when this setting is on. Use text input and available attachment controls; do not promise voice calls or transcription based on these settings.
## Work with the preview
In Display, use Edit mode to select editable page elements in the preview. Desktop preview and Mobile preview change the preview frame, not the published configuration. On narrow editor layouts, open Preview to inspect the customer surface. Save pending changes before comparing the published page.
## Instructions and model
Choose whether this channel syncs with global instructions. When sync is on, changes to that text update the shared instructions used by other synced channels. When sync is off, edit the Help Page instructions for this channel. Review model settings before saving.
## Actions on Help Page
The Actions tab lists compatible actions by provider. An action must be enabled before its Help Page toggle can be used. Open its details to review the configuration, then test the action from the public page.
## Visibility and saved changes
Use Save changes to persist pending edits or Discard to return to the saved configuration. Wait for image uploads to finish before saving. Visibility is a separate publication control. Its switch updates the channel immediately; it is not an unsaved Display edit. The Deploy drawer reports Channel disabled, Help Page is live, or Help Page is unavailable. It provides Enable help page or Disable help page, Copy URL, Open, and Reload saved settings. Reloading with a pending draft asks whether to discard that draft.
> **Availability**: An enabled Help Page can still be unavailable if the agent or workspace is inactive. Check the status shown beside the public URL before sharing it.
## Check the published page
- Open the public URL outside the editor and send a message.
- Verify the logo, hero, colors, and contrast in both themes.
- Check suggested messages, buttons, and enabled attachments. Confirm whether a capability is available in the visitor UI before promising it.
- Test the narrow mobile layout and keyboard navigation.
- Run a compatible action and verify the conversation reaches your inbox.
---
# Developer tools
Choose the API, CLI, or MCP connection for your QwryAI workflow.
## Overview
QwryAI exposes developer and agent access through an API, CLI, and remote MCP service. Use the connection appropriate to your workflow and the access available to your workspace.
## Choose a connection
| Surface | Use case |
| --- | --- |
| REST API | Integrate QwryAI resources into your application or scripts. |
| CLI | Inspect resources and run supported commands from a terminal. |
| MCP | Connect a supported AI client to your workspace tools. |
| Website JavaScript | Control an embedded chat widget or register client-side action handlers. |
## Connection guides
- [Authentication, endpoints, CLI, and MCP setup](/docs/user-guides/agent-management/developer-agent-access)
- [Website deployment and JavaScript API](/docs/user-guides/agent-management/deploy)
- [Client-side action registration](/docs/user-guides/actions/client-side-actions)
## Workspace access
Developer access follows workspace eligibility and the permissions of the credential in use. Keep credentials in your environment or secret manager, and use placeholders in shared examples. Consult Developer & Agent Access for the current authentication flow and endpoint addresses.
---
# Guardrails
Define response boundaries and check the agent’s behavior.
## Set response boundaries
QwryAI Guardrails are instructions that describe response boundaries. Open Build → Instructions and edit Guardrails alongside the general instructions.
## Write clear boundaries
State how the agent handles missing facts, private information, unsupported promises, and requests outside its role. Keep these rules consistent with the actions and escalation paths you have actually enabled.
## Check the boundaries
1. Save the instructions.
2. Ask an ordinary supported question to confirm the rules do not prevent useful answers.
3. Ask for an unknown release date or unavailable account information.
4. Confirm the agent explains the limit and gives an appropriate next step.
## Guardrail scope
Instruction guardrails guide AI behavior. Allowed Origins, provider permissions, and action approval policies are separate controls. This page does not describe a country-blocking or rate-limit editor; those controls are not exposed in the current Guardrails interface.
- [Instructions](/docs/user-guides/agent-management/instructions)
- [Action approvals](/docs/user-guides/agent-management/approvals)
- [Agent settings](/docs/user-guides/agent-management/settings)
---
# Activity
Review customer interactions, agent actions, and answer-improvement opportunities.
## Review agent activity
Use Activity to inspect conversations and lead-form submissions. Start from an actual customer exchange when investigating an incorrect answer or an action that did not finish.
## Investigate an exchange
1. Select the agent and open its conversation activity or Inbox.
2. Find the conversation by the available search and channel controls.
3. Read the customer request, agent response, and any action messages.
4. Check whether the issue concerns missing knowledge, unclear instructions, a failed action, or a human handoff.
## Make a targeted correction
| Issue | Next step |
| --- | --- |
| Missing answer | Update the relevant Data Source and confirm training. |
| Wrong tone or scope | Revise Instructions. |
| Action failure | Review its configuration, inputs, response, and enabled channels. |
| Human support delay | Check ownership and availability. |
- [Knowledge gaps](/docs/user-guides/analytics-monitoring/knowledge-gaps)
- [Action testing](/docs/user-guides/actions/testing-and-publishing)
---
# Analytics
Understand chatbot performance, customer activity, and support trends.
## Understand performance
Analytics summarizes agent activity over a selected period. Use it to identify changes in conversation volume, sentiment, resolution, and customer feedback, then inspect the underlying conversations.
## Reports and metrics
The dashboard includes conversation volume, customer sentiment, activity by time, resolution, top issues, and knowledge gaps. Agent reports also cover Chats, Sentiment, Keywords, and Feedback.
## Review a period
1. Open Analytics for the selected agent.
2. Choose the date range before comparing results.
3. Review volume alongside resolution and feedback so a change in traffic is not mistaken for a change in quality.
4. Open the issue or knowledge-gap workflow to investigate recurring problems.
## Interpret the results
An empty report means there is no data in the selected scope, or the report has not loaded. A rating reflects submitted feedback, not every conversation. Estimated savings and automatic classifications are indicators for review, not guarantees of business outcomes.
---
# Knowledge Gaps
Find questions your chatbot could not answer confidently or correctly.
## Turn unanswered questions into knowledge
Knowledge gaps groups questions that need better source material. Review the evidence before writing an answer so the correction addresses the actual customer request.
## Find a gap
| Control | Options |
| --- | --- |
| Status | All, Pending, In Progress, Resolved |
| Priority | All Priorities, Critical, High, Medium, Low |
| Sort | Most Recent or Priority |
| Search | Find a question in the queue. |
## Review and improve
1. Select a question from the queue.
2. Read the evidence and related conversation context.
3. Review or edit its category and priority.
4. Draft the answer or generate a suggestion in the editor.
5. Check every factual statement against your real product information before saving the supported update.
6. Ask the question again in Playground and verify that the response uses the correction.
## Avoid invented fixes
Do not resolve a gap by inventing a policy, price, release date, or account-specific fact. Add an explicit limit or escalation route when the answer needs a teammate or an authenticated action.
---
# Manage
Create and organize workspaces, chatbots, and team-level resources.
## Choose the correct workspace and agent
Workspaces group your agents, team access, settings, integrations, and usage. Agent pages apply to the selected agent; workspace pages manage shared resources.
## Navigate between scopes
1. Use the workspace and agent selectors to choose where you want to work.
2. Confirm the selected agent in the breadcrumb before editing its sources, actions, or channels.
3. Open the workspace dashboard to review existing agents and create an agent when your plan allows it.
4. Use workspace settings for shared identity, members, and billing.
## Check the scope of a change
A setting described as workspace-wide can affect more than the agent currently open. Review the scope of team access, routing, integration connections, and usage before changing it.
## Workspace guides
- [Workspace settings](/docs/user-guides/workspace-management/settings)
- [Team access](/docs/user-guides/workspace-management/team-agents)
- [Usage](/docs/user-guides/workspace-management/billing-usage)
---
# Team & Agents
Invite teammates and choose the access they need to support customers.
## Team access
Manage team membership from the workspace. Use an individual login for each teammate so conversation ownership and support activity remain attributable.
## Invite a teammate
1. Open the workspace member invitation form.
2. Enter the teammate’s Email Address.
3. Choose Admin, Manager, or Agent from Role.
4. Add an optional Personal Message.
5. Review the recipient and role, then select Send Invitation.
6. After the invitation is accepted, confirm the teammate can access the work they need.
## Choose a role
| Role | Workspace experience |
| --- | --- |
| Owner | The workspace owner has administrative access. |
| Admin | Access to workspace and agent settings and administration. |
| Manager | Manage agent content, actions, deployment, and support work. Administrative settings are restricted to owners and admins. |
| Agent | Handle conversations and tickets, with access to Backstage and their profile. |
The invitation form offers Admin, Manager, and Agent. Choose the role that matches the teammate’s work; a support agent does not need administrative access to respond to customers.
## Prepare the support team
1. Set up the teammate’s availability and schedule.
2. Review routing and assignment with the team.
3. Confirm the teammate can open an assigned conversation and ticket.
4. Review membership when responsibilities change or someone leaves.
- [Scheduling](/docs/user-guides/help-desk/scheduling)
- [Takeover](/docs/user-guides/help-desk/takeover)
---
# Usage
This tab displays the usage details of all AI agents in the selected workspace. You can also filter usage data for a specific workspace.
## Track workspace usage
Open workspace Usage to review credit consumption and agent usage. The sidebar shows available credits, consumed credits, and the next reset date.
## Choose the scope
1. Select one agent, All agents, or Deleted or unattributed.
2. Choose the date range.
3. Review Credits used in selected range and Agents used in your workspace.
4. Inspect Usage history and Credits used per agent.
## Understand the reset
The next reset is displayed for the current billing period and uses UTC. Usage for a selected historical range is different from the current available balance. If the balance or usage is unavailable, retry the request; an unavailable value is not zero.
## Plans and billing
Use the plan and billing pages to inspect current limits, subscription details, and available invoices. Check the displayed price and terms before making a change. A trial banner is an invitation to start a trial, not evidence that a paid trial is already active.
---
# Settings
Edit your workspace identity and conversation media preferences.
## Open workspace settings
Open Settings for the selected workspace and choose General. Workspace settings apply to the team; the Settings link inside an agent configures that individual agent.
## Workspace identity
| Field | Purpose |
| --- | --- |
| Workspace Name | The name displayed to your team. |
| Workspace URL | The workspace URL slug. |
| Description | A short description of the workspace. |
1. Select the workspace you want to update.
2. Edit its name, URL, or description.
3. Choose Save Changes and wait for confirmation. Reset discards unsaved edits.
## Preferences
| Control | Purpose |
| --- | --- |
| Public Workspace | Allow others to discover the workspace. |
| AI Media Processing | Let AI analyze enabled images and transcribe enabled voice messages before replying. |
AI Media Processing is in Conversation Media. Review which attachments and voice features are enabled on each customer channel. Choose Save Preferences to apply preference changes or Reset to discard them.
## Related settings
- [Team & Agents](/docs/user-guides/workspace-management/team-agents)
- [Usage](/docs/user-guides/workspace-management/billing-usage)
- [Agent settings](/docs/user-guides/agent-management/settings)
---
# Two-factor authentication (2FA)
Check the availability of two-factor authentication for your account.
## Availability
The current QwryAI profile interface does not expose a self-service two-factor authentication setup control. There is no authenticator QR-code or recovery-code workflow to follow in this interface.
Contact QwryAI support about availability if your organization requires two-factor authentication before granting team access.
## Account controls
Open your profile to manage Basic Info, Sessions, Password, and Social Accounts. Review active sessions and workspace membership regularly. Keep account credentials and any provider recovery codes out of screenshots and shared support messages.
- [Team & Agents](/docs/user-guides/workspace-management/team-agents)
---
# Website Platforms
Deploy QwryAI on website builders, storefronts, and hosted web apps.
## Add QwryAI to a website
Use the embed code generated by your agent’s website deployment panel. The same code can be installed on a site builder, storefront theme, or custom web application that permits scripts.
## Install the widget
1. Open Channels → Chat bubble and choose Deploy → Website widget.
2. Copy the generated script without changing its agent or embed identifier.
3. Add it to your site’s shared HTML layout or supported custom-code area.
4. Add the actual website origin to the agent’s Allowed Origins settings.
5. Publish the website and confirm that one launcher appears.
## Choose the installation location
| Website type | Installation location |
| --- | --- |
| Custom HTML | The page or shared layout that should display the widget. |
| React or Next.js | A shared client-side script loader or application layout, avoiding duplicate insertion. |
| Site builder | Its supported custom-code or embed settings; script access may depend on the builder’s plan. |
| Storefront | The theme or approved script integration for the intended storefront. |
## Check the published website
Test the published page, not only the site-builder editor. Check desktop and mobile, send a customer question, and verify any client action on the page where its handler is installed.
- [Deployment guide](/docs/user-guides/agent-management/deploy)
- [Client-side actions](/docs/user-guides/actions/client-side-actions)
---
# Messaging Platforms
Connect customer messaging channels such as WhatsApp, Instagram, Messenger, Slack, Telegram, and Email.
## Connect messaging channels
Messaging integrations connect external accounts; Channels controls how your agent behaves on those connections. Configure both before expecting customer replies.
## Supported connection guides
- [WhatsApp](/docs/user-guides/integrations/whatsapp)
- [Instagram](/docs/user-guides/integrations/instagram)
- [Facebook Messenger](/docs/user-guides/integrations/messenger)
- [Telegram](/docs/user-guides/integrations/telegram)
- [Slack](/docs/user-guides/integrations/slack)
- [Email](/docs/user-guides/integrations/email)
## Verify each channel
1. Authorize the intended account or bot through Integrations.
2. Confirm Connected, then open its Channels configuration.
3. Review channel-specific instructions and compatible actions.
4. Send a message from an account you control and verify the full reply path.
## Availability
Provider authorization and permissions must be configured in the deployment. A Coming soon badge means the connector is not available there. Browser-based widgets and client-side code are not supported equally across messaging channels.
---
# Business Tools
Connect QwryAI with ecommerce, scheduling, notification, and automation tools.
## Connect tools to actions
A business integration makes an external account available to the agent. An action defines when and how the agent uses that account.
## Choose a workflow
| Tool | Workflow |
| --- | --- |
| Shopify | Store and catalog context for commerce actions. |
| Calendly | Connected scheduling account used by booking actions. |
| Slack | Messaging channel and supported notification workflows. |
| Zapier | External app directory; use supported webhooks for an automation you configure. |
| HubSpot | Coming soon in the current integration catalog. |
## Configure the action
1. Connect the provider from Integrations.
2. Open Actions and select the relevant action type.
3. Describe when it should run and configure required inputs.
4. Enable compatible channels and verify a real result in the connected service.
## Related guides
- [Action overview](/docs/user-guides/actions/overview)
- [Testing and publishing](/docs/user-guides/actions/testing-and-publishing)
---
# Email
Enable AI-assisted email support with forwarding, authenticated domains, and connected inbox behavior.
## Connect a support mailbox
Email connects a mailbox to your agent. Open Integrations and select Email. You can use the available Gmail or Outlook authorization flow, IMAP/SMTP credentials, or the Forward-only configuration.
## Choose a connection method
| Method | Required information |
| --- | --- |
| Gmail or Outlook | An authorized mailbox and an enabled provider connection in this QwryAI deployment. |
| IMAP/SMTP | Mailbox address, incoming and outgoing hosts, ports, logins, and passwords. |
| Forward-only | Mailbox address, forward recipient, and webhook bearer secret. |
1. Choose the method your mail administrator supports.
2. Enter the mailbox configuration or complete the provider authorization.
3. Select Connect Email and confirm the connection succeeds.
4. Open Channels → Email to choose reply addresses, visibility, instructions, signature, and actions.
## Troubleshooting
A disabled Gmail not configured or Outlook not configured button means that connection is unavailable in the current deployment. For IMAP/SMTP, use the host, port, and credentials supplied by your mail provider. Custom SMTP requires correct SPF, DKIM, and DMARC records. Never include mailbox passwords in agent instructions.
- [Email settings](/docs/user-guides/agent-management/email-settings)
---
# Instagram
Connect Instagram messaging so customer conversations can be handled from QwryAI.
## Connect Instagram
Use an Instagram professional account that you can authorize for messaging.
## Set up the connection
1. Select the agent, open Integrations, and choose Instagram.
2. Complete the Meta authorization and select the Instagram account offered by the account picker.
3. Confirm the integration shows Connected.
4. Open Channels and manage this channel to configure its visibility, instructions, and compatible actions.
5. Send a message from an account you control and verify the reply in both the channel and QwryAI Inbox.
## Troubleshooting
If authorization does not finish, check the selected provider account and its access to the intended resource. A Connected integration is not the same as an enabled channel. Confirm the channel configuration and its action compatibility before investigating the agent instructions.
- [Channel settings](/docs/user-guides/agent-management/channels)
---
# Messenger
Connect Facebook Messenger so customer messages can route into QwryAI workflows.
## Connect Facebook Messenger
Use a Facebook account with access to the Page whose messages your team handles.
## Set up the connection
1. Select the agent, open Integrations, and choose Facebook.
2. Complete the Meta authorization and select the Facebook Page offered by the account picker.
3. Confirm the integration shows Connected.
4. Open Channels and manage this channel to configure its visibility, instructions, and compatible actions.
5. Send a message from an account you control and verify the reply in both the channel and QwryAI Inbox.
## Troubleshooting
If authorization does not finish, check the selected provider account and its access to the intended resource. A Connected integration is not the same as an enabled channel. Confirm the channel configuration and its action compatibility before investigating the agent instructions.
- [Channel settings](/docs/user-guides/agent-management/channels)
---
# Telegram
Connect Telegram for bidirectional bot conversations.
## Connect Telegram
Have the token for the Telegram bot your team owns.
## Set up the connection
1. Select the agent, open Integrations, and choose Telegram.
2. Enter the integration name and Bot token in the Telegram connection form, then connect.
3. Confirm the integration shows Connected.
4. Open Channels and manage this channel to configure its visibility, instructions, and compatible actions.
5. Send a message from an account you control and verify the reply in both the channel and QwryAI Inbox.
## Troubleshooting
If authorization does not finish, check the selected provider account and its access to the intended resource. A Connected integration is not the same as an enabled channel. Confirm the channel configuration and its action compatibility before investigating the agent instructions.
- [Channel settings](/docs/user-guides/agent-management/channels)
---
# Shopify
Connect Shopify store context with QwryAI support workflows.
## Connect your store
Shopify supplies store and catalog context for commerce actions. Connect the store to the agent that will support its customers.
## Authorize Shopify
1. Open Integrations and choose Shopify.
2. Enter the Shop name: the subdomain before .myshopify.com.
3. Select Connect Shopify and review the requested access in Shopify.
4. Return to QwryAI after authorization and inspect the catalog sync status.
5. Configure the required Shopify actions and enable them on supported channels.
## Check catalog readiness
A successful authorization starts the connection; catalog synchronization is a separate process. Wait for the catalog status to finish before checking product recommendations. If a product is missing, compare its current store publication state with the sync status.
## Verify with real store information
Use an actual product URL or SKU to check product answers. For order-specific actions, use your store’s supported customer-verification flow. Confirm availability and permissions before enabling actions that change orders, carts, or customer details.
- [Shopify actions](/docs/user-guides/actions/shopify)
---
# Slack
Send QwryAI notifications or support events into Slack channels.
## Connect Slack
Use a Slack workspace where you can authorize the QwryAI integration.
## Set up the connection
1. Select the agent, open Integrations, and choose Slack.
2. Complete Slack authorization, return to QwryAI, and select the relevant channel when the picker appears.
3. Confirm the integration shows Connected.
4. Open Channels and manage this channel to configure its visibility, instructions, and compatible actions.
5. Send a message from an account you control and verify the reply in both the channel and QwryAI Inbox.
## Troubleshooting
If authorization does not finish, check the selected provider account and its access to the intended resource. A Connected integration is not the same as an enabled channel. Confirm the channel configuration and its action compatibility before investigating the agent instructions.
- [Channel settings](/docs/user-guides/agent-management/channels)
---
# WhatsApp
Connect WhatsApp messaging so customers can reach your team through QwryAI.
## Connect WhatsApp
Have access to the Meta business account and phone number intended for customer support.
## Set up the connection
1. Select the agent, open Integrations, and choose WhatsApp.
2. Complete WhatsApp Embedded Signup with Meta, select the business and number, then return to QwryAI and complete the displayed webhook configuration.
3. Confirm the integration shows Connected.
4. Open Channels and manage this channel to configure its visibility, instructions, and compatible actions.
5. Send a message from an account you control and verify the reply in both the channel and QwryAI Inbox.
## Troubleshooting
If authorization does not finish, check the selected provider account and its access to the intended resource. A Connected integration is not the same as an enabled channel. Confirm the channel configuration and its action compatibility before investigating the agent instructions.
- [Channel settings](/docs/user-guides/agent-management/channels)
---
# WhatsApp Templates
Create and manage approved WhatsApp templates for automated or provider-required WhatsApp messages.
## WhatsApp message templates
WhatsApp templates are managed and approved through Meta. The current QwryAI dashboard does not expose a template creation, approval, or outbound campaign composer.
## Available workflow
Connect WhatsApp through Embedded Signup, configure its channel, and verify inbound customer conversations. Do not assume that connecting a number enables an outbound template or campaign workflow.
- [Connect WhatsApp](/docs/user-guides/integrations/whatsapp)
- [Channels](/docs/user-guides/agent-management/channels)
---
# Zapier
Use Zapier to move QwryAI events into other business tools.
## Zapier and webhooks
The Zapier entry in Integrations opens Zapier’s app directory. It does not run a QwryAI OAuth connection or configure a Zap inside the dashboard.
## Connect a workflow you control
1. Define the event and destination for your workflow.
2. Create the receiving webhook or workflow in your automation service.
3. Configure the appropriate QwryAI lead-form completion webhook or custom API action with that endpoint.
4. Send a controlled request and inspect both the QwryAI result and the receiving workflow.
## Check the receiving service
Provider plans, webhook availability, and task limits are controlled by your automation service. A link to its directory does not establish a connection or guarantee a free allowance.
- [Custom API actions](/docs/user-guides/actions/custom-action)
- [Lead forms](/docs/user-guides/agent-management/lead-forms)
---
# Response Quality
Improve how accurately and helpfully your chatbot answers customers.
## Improve response quality
Good answers depend on accurate sources, clear instructions, a suitable model, and working actions. Change one of these at a time so you can tell what improved.
## Choose the right correction
| Observed problem | Correction |
| --- | --- |
| Missing or outdated fact | Update the source and confirm it is trained. |
| Wrong tone or answer scope | Clarify the agent instructions. |
| Missing account or order information | Use an authenticated action with the necessary data. |
| A failed action | Check the action result, inputs, provider connection, and channel. |
| Invented detail | Tell the agent how to handle unknown information and give it a supported escalation path. |
## Compare real scenarios
1. Write representative questions from your actual support workflow.
2. Record the expected facts and the source that supports each one.
3. Test the same questions before and after a change in a fresh conversation.
4. Check correctness, completeness, useful links, action results, and the point where a human is needed.
## Use reliable links
Include the actual page title and canonical URL in your source material when a customer should be directed to a specific page. Check that the link opens the intended public page. Do not train a made-up URL or use a placeholder as a live destination.
---
# Models Comparison
Choose the model behavior that best fits your support use case.
## Choose a model for your workflow
Select a model from the current model picker in Instructions or Settings. Model availability and limits depend on the deployment and plan; the picker is the current source of available choices.
## Compare on the same questions
| Criterion | Check |
| --- | --- |
| Accuracy | Does the answer match the source and avoid invented details? |
| Actions | Does the model select the correct action and collect the required inputs? |
| Latency | Measure the complete customer-visible response. |
| Credits | Compare actual usage for the same set of tasks. |
| Style | Check tone, length, and language against your instructions. |
## Run a comparison
1. Use a representative set of product questions, follow-ups, unknowns, and action requests.
2. Run each set in fresh conversations with the same sources and instructions.
3. Change the model and repeat the same scenarios.
4. Compare outcomes and usage before selecting the model for production.
## Token limits and instructions
Keep the response token limit large enough for the expected answer or tool result. A more capable model cannot supply a missing policy or repair a disconnected action. Correct the source or workflow first.
- [Agent settings](/docs/user-guides/agent-management/settings)
- [Response quality](/docs/user-guides/ai-performance/response-quality)
---
# Overview
Manage customer support tickets and conversations from a central help desk.
## Support workspace
Use Inbox for conversations and Tickets for follow-up work. Open either destination from the agent sidebar. Each workspace keeps the selected agent in the breadcrumb so you can confirm which customers you are supporting.
## Choose a ticket view
| View | Purpose |
| --- | --- |
| 3 Panels | Browse tickets, read the selected conversation, and inspect details side by side. |
| Board | Review tickets grouped by status. |
| List | Scan tickets in a compact table. |
Search tickets or use Filter tickets to narrow the results. Select a ticket to load its linked conversation and details. An empty panel means no ticket has been selected.
## Work on a request
1. Read the customer request and linked conversation.
2. Check the assignee, priority, and status in ticket details.
3. Reply with the next concrete step.
4. Update the status as ownership moves between your team and the customer.
## Continue
- [Ticket statuses](/docs/user-guides/help-desk/tickets)
- [Filters](/docs/user-guides/help-desk/filters)
- [Conversation takeover](/docs/user-guides/help-desk/takeover)
---
# Conversations
Monitor and respond to customer chats from one support inbox.
## Review conversations
Open Inbox from the agent sidebar. Select a conversation to read its messages and customer context. Conversation history includes exchanges from connected channels and the website widget.
## Handle a conversation
1. Choose Your inbox, Open, Unassigned, a Support Desk state, or a channel from the Inbox navigation.
2. Read the recent messages and customer context before replying.
3. Check the AI/human handling state and assignee.
4. Choose Reply for customer-facing text or Note for internal collaboration.
5. Send only after checking the composer mode, then confirm the message appears in the conversation.
## Replies and notes
Replies are customer-facing. Notes keep investigation context inside the support workspace. Use an internal note for a handoff summary, ownership decision, or information another teammate needs.
## Related guides
- [Takeover](/docs/user-guides/help-desk/takeover)
- [Contacts](/docs/user-guides/contacts/overview)
- [Tickets](/docs/user-guides/help-desk/tickets)
---
# Tickets
Track customer issues that need ownership, investigation, or follow-up.
## Track follow-up work
Tickets keep a support request and its linked conversation together. Open Tickets from the selected agent. Search for a request, then select it to see its details.
## Review the queue
1. Choose 3 Panels, Board, or List.
2. Use Filter tickets to select a status.
3. Open a ticket and review its customer, source, assignee, and priority.
4. Send a reply and update the status when the next step changes.
## Ticket statuses
| Status | Use |
| --- | --- |
| Open | A ticket needs attention. |
| In progress | A teammate is working on the request. |
| Waiting on customer | Your team needs a reply or information from the customer. |
| Resolved | The request has been addressed. |
| Closed | The ticket is no longer active. |
## Priority and source
Ticket priorities are Low, Medium, High, and Urgent. Sources include Email, Chat, Lead form, API, and Manual. Priority describes urgency; status describes progress. Keep the two fields separate when triaging.
## An empty queue
No tickets found can mean the agent has no tickets or that your search and status filter exclude them. Clear the search and select All before concluding that a request is missing.
---
# Filters
Use filters to narrow the support inbox to the conversations that need attention.
## Find tickets
Ticket filtering is available from the funnel button labeled Filter tickets beside the ticket search box.
## Available filters
| Status | Use |
| --- | --- |
| Open | A ticket needs attention. |
| In progress | A teammate is working on the request. |
| Waiting on customer | Your team needs a reply or information from the customer. |
| Resolved | The request has been addressed. |
| Closed | The ticket is no longer active. |
All removes the status restriction. The menu shows a count beside each status. Search tickets narrows the visible results further.
## Combine search and status
1. Open Tickets for the correct agent.
2. Choose the status you need from Filter tickets.
3. Enter your search text in Search tickets.
4. Clear the search and choose All to return to the complete queue.
## Filter scope
The current ticket menu is a status filter. It does not expose Chatbase’s general-purpose condition builder, saved views, or date/operator rule editor.
---
# Email Settings
Configure email behavior for tickets and help desk replies.
## Email channel settings
Open Channels, then manage Email. Connect a mailbox first, then configure how the agent reads and replies to email. The channel has Overview, Configuration, Signature, and Actions tabs.
## Configure replies
| Control | Purpose |
| --- | --- |
| Visibility | Enable or disable the email channel. |
| Reply addresses | Choose the connected sender addresses used for replies. |
| Deliverability alert contact | Select a teammate to receive delivery alerts. |
| Blocked senders | Exclude specified email senders. |
| Email display name | Set the sender name customers see. |
| Spam detection and whitelisted senders | Control spam handling and allowed senders. |
| Reply delay | Set how long the channel waits before responding. |
## Signature
Open Signature to edit the content appended to outgoing replies. Keep it short enough to leave the answer easy to read. Save the changes and check a message received by a mailbox you control.
## Model, sources, and actions
Overview controls the email model, data sources, and instructions. Choose whether instructions stay synchronized with the global agent instructions. Open Actions to enable only the actions suitable for email. Browser-only client actions require a website context and cannot run in a recipient’s mailbox.
## Check delivery
A connected address and a visible channel are separate settings. If mail is missing, check the mailbox connection and inbound forwarding. For failed outgoing mail, check the SMTP settings and the sending domain’s SPF, DKIM, and DMARC configuration.
- [Connect Email](/docs/user-guides/integrations/email)
---
# Ticket Assignment
Route tickets to the right teammate or queue.
## Assign ownership
Use the assignment controls in a conversation or ticket to choose the teammate responsible for the next response. Agent availability also affects automatic human-support routing.
## Manual assignment
1. Open the conversation or ticket.
2. Open its assignee control.
3. Search for an agent and choose the responsible teammate.
4. Confirm the selected assignee before leaving the request.
## Automatic routing
Open agent Settings and find the human-support routing controls. Choose the routing strategy and priority, wait time, retry interval, and confidence threshold appropriate for your team. Save the routing strategy using its own save control. Routing settings can apply across the workspace; review their scope before changing them.
- [Routing controls](/docs/user-guides/agent-management/settings)
## Availability
Check the teammate’s availability from the account and assignment controls before promising a live response. A configured escalation action does not by itself guarantee that a human is available. The current application does not expose the separate Balanced/Round Robin scheduling page described in some other help desks.
---
# Scheduling
Define support availability and handoff timing.
## Plan support availability
Set realistic expectations for human support in your agent instructions and escalation behavior. Availability and routing determine whether a live teammate can accept a conversation.
## Current controls
QwryAI exposes agent availability and routing settings. It does not currently expose a Help Desk Scheduling page with Add shift, agent shift assignments, or time-off calendars. There is no shift-creation workflow to complete in the current dashboard.
## Configure the supported workflow
1. Add your actual support hours and response expectations to agent Instructions.
2. Choose your human-support routing strategy in Settings.
3. Configure Escalate to Human with the details your team needs.
4. Check the customer experience while your team is available and unavailable.
## Related guides
- [Instructions](/docs/user-guides/agent-management/instructions)
- [Agent settings](/docs/user-guides/agent-management/settings)
- [Escalate to Human](/docs/user-guides/actions/escalate-to-human)
---
# Takeover
Let a human agent take over a conversation from the AI chatbot.
## Move from AI to human support
Takeover lets a teammate handle a conversation that needs human judgment. Review the current handling state before sending a reply, and use the conversation’s takeover or AI-reply control to change who is responding.
## Take over a conversation
1. Open Inbox and select the conversation.
2. Review its recent messages, customer context, and assigned teammate.
3. Open More conversation actions, choose Pause AI, and confirm the menu changes to Resume AI.
4. Reply to the customer with a clear next step.
5. Leave an internal Note when another teammate needs context.
6. Choose Resume AI from More conversation actions when the request can return to automated support.
## Check both sides
Keep the customer widget open while testing takeover. Confirm the customer receives the human reply and that the AI does not respond at the same time. A successful click in the dashboard is not enough to verify the customer experience.
## Related guides
- [Live Chat](/docs/user-guides/actions/live-chat)
- [Escalate to Human](/docs/user-guides/actions/escalate-to-human)
---
# Priority
Rank support requests by urgency.
## Prioritize tickets
Priority expresses the urgency of a support request. Open Tickets, select a ticket, and inspect its priority in the details.
## Priority levels
| Priority | Typical use |
| --- | --- |
| Low | A routine question without time pressure. |
| Medium | Normal support work. |
| High | A customer is blocked and needs prompt attention. |
| Urgent | An issue requires immediate team attention. |
## Triage consistently
Choose the priority according to your support policy and the actual impact. Keep the status aligned with progress: raising urgency does not mean the request has been resolved.
- [Tickets](/docs/user-guides/help-desk/tickets)
- [Assignment](/docs/user-guides/help-desk/ticket-assignment)
---
# Tags
Label conversations with consistent support topics.
## Label conversations
Tags organize support conversations by topic or business context. Open Inbox, select a conversation, and find Tags in the Details panel.
## Add a tag
1. Review the conversation to identify its main topic.
2. Select Add beside Tags.
3. Use the available tag control to choose or enter the relevant label.
4. Confirm the tag appears on the conversation before moving on.
## Keep labels useful
Use a small, consistent vocabulary such as Deployment, Data sources, or Billing. Avoid putting customer secrets or full message text in tags. Tags describe context; they do not replace assignee, status, or priority.
- [Conversations](/docs/user-guides/help-desk/conversations)
---
# Translation
Configure language detection and conversation translation.
## Support conversations across languages
Agent Settings provides a default language, automatic translation, and language detection. The conversation header also exposes the agent conversation language.
## Configure translation
1. Open Settings → General for the agent.
2. Choose Default Language.
3. Enable Auto-translate Conversations when visitor and team languages differ.
4. Choose Auto-detect visitor language or Use visitor locale only.
5. Save Configuration and check an exchange in the languages your team supports.
## Review important details
Check names, dates, product terms, and technical instructions in both the customer and team view. Translation helps communication; it does not verify the accuracy of the original answer or the customer’s identity.
- [General settings](/docs/user-guides/agent-management/settings)
---
# Actions overview
Give your AI agent tools to retrieve information, complete tasks, and show interactive experiences.
## Overview
Actions extend a conversation beyond an answer. Your agent can call a business API, run a function on your website, offer a booking, collect details, or display a widget. Configure actions for the selected chatbot from AI Actions.
> **Choose the outcome first**: Use a built-in action for a supported integration. Choose Custom actions when you need your own endpoint, website behavior, or widget.
## Available actions
| Action | What it does |
| --- | --- |
| Custom actions | Call an API, run client-side code, call an API and show a widget, or show a widget without an API. |
| Cal | Offer a Cal.com event and configure its time display. |
| Calendly | Offer scheduling with your connected Calendly configuration. |
| Web search | Search public information, optionally restrict domains, and include images. |
| Escalations | Route a request to a configured human support workflow. |
| Collect leads | Capture customer details for follow-up. |
| Custom form | Collect a structured set of fields inside the conversation. |
| Shopify | Use the store actions available to your connected Shopify account. |
| Stripe | Shown as Coming soon in the create-action catalog; it cannot be connected there yet. |
## Create an action
1. Open your chatbot and go to Build → Actions.
2. Choose Create action and select the action you want to configure.
3. Give it a clear name and explain when the agent should use it.
4. Complete its inputs, integration settings, request, or widget, as applicable.
5. Test the action and select the channels where it should be available.
6. Save the draft, then use Save & enable when it is ready for conversations.
## When actions run
When to use describes the customer intent that should cause the AI to select an action. For example: use the order lookup when a customer asks for delivery progress and supplies an order reference. Be specific about the outcome and any information that must be collected first.
Show widget actions can also use automatic website triggers: Visit, Delay, Scroll, and Chat opened. These structured triggers are configured separately from the instructions the AI reads.
- [Configure automatic triggers](/docs/user-guides/actions/automatic-triggers)
## Manage actions
My actions contains your saved actions. Reopen an action to update its configuration, check its status, or disable it. Saving a draft and enabling an action are separate steps: confirm its enabled state before expecting it in a customer conversation.
Choose distinct instructions for actions with similar purposes. If two actions both claim every support request, the agent has less information to choose between them.
## Next steps
- [Custom Action](/docs/user-guides/actions/custom-action)
- [Client-side actions](/docs/user-guides/actions/client-side-actions)
- [Widgets and response mapping](/docs/user-guides/actions/widgets)
- [Testing and publishing](/docs/user-guides/actions/testing-and-publishing)
---
# Calendly
Connect your Calendly account and offer scheduling from a conversation.
## Overview
Calendly actions let your agent offer a meeting when a customer is ready to book. QwryAI connects to Calendly through OAuth and can open its hosted scheduling experience inside the website widget.
## Connect Calendly
1. Open Build → Actions and select Calendly from Create action.
2. Choose Connect Calendly to open connection settings.
3. Authorize the Calendly account that owns the events you want to offer.
4. Select the event type in the integration settings and return to Calendly actions.
5. Confirm the connection and available actions load successfully.
## Configure an action
1. Open Customize for the Calendly action you want to use.
2. Review its action name and When to use instructions. Describe the requests that should lead to scheduling.
3. Review the action's inputs and any widget settings available for that action.
4. Choose the connected channels where it should be available.
5. Save the draft, then enable or publish the action using its editor controls.
## Test scheduling
- Ask for a meeting using the wording a customer would use.
- Check that the correct Calendly event opens.
- Review the displayed timezone and available slots.
- Complete a test booking and check Calendly for the confirmation.
- Try cancelling the scheduler and continuing the conversation.
> **Calendar availability**: Manage event duration, availability, and scheduling rules in Calendly. A successful connection alone does not confirm that the selected event has bookable times.
## Troubleshooting
| What you see | What to check |
| --- | --- |
| Connect Calendly | Complete the account connection for this chatbot. |
| Actions unavailable | Resolve the displayed connection or loading error before assuming there are no actions. |
| The wrong event opens | Review the selected event in connection settings. |
| The agent does not offer scheduling | Check the action's enabled state, channel, and When to use instructions. |
## Related guides
- [Testing and publishing](/docs/user-guides/actions/testing-and-publishing)
- [Cal.com scheduling](/docs/user-guides/actions/cal)
---
# Live Chat
Move from an AI conversation to a response from your support team.
## Overview
Live chat is the customer-facing part of a human support workflow. Configure Escalations to control how a conversation requests help, then manage the conversation and takeover in the support inbox.
## Prepare the handoff
1. Choose the support destination for escalated conversations.
2. Configure the Escalations action with clear When to use and When not to use instructions.
3. Decide when customer confirmation and contact details are needed.
4. Enable the action on the channels your team monitors.
5. Review assignment and scheduling with the team that will respond.
## Respond as a teammate
Open the conversation in the support inbox, read the previous AI messages and collected details, and use the available takeover controls before replying. Check the conversation's current ownership and status so teammates can see who is handling it.
## Set customer expectations
Describe your support hours and expected response in the messages customers see. Do not promise an immediate reply when the queue is unattended. For requests outside those hours, collect the information your team needs to follow up.
## Test both sides
- Request a human from the customer channel.
- Confirm the request appears in the support workspace with conversation context.
- Take over and send a test reply from the teammate interface.
- Check that the customer receives it in the same conversation.
- Verify the conversation status after the support interaction ends.
## Related guides
- [Escalate to Human](/docs/user-guides/actions/escalate-to-human)
- [Conversation takeover](/docs/user-guides/help-desk/takeover)
- [Scheduling](/docs/user-guides/help-desk/scheduling)
---
# Collect Leads
Ask for customer details at the point where follow-up is useful.
## Overview
Collect leads creates a customer-details action. Define when the agent should ask for information, the message shown with the form, and the fields the customer needs to complete.
## Set up the request
1. Open Build → Actions, choose Create action, then Collect leads.
2. In General, enter an Action name and Description.
3. Write When to use instructions that explain the customer intent for this form.
4. Write the Customer prompt that introduces the request for details.
5. Continue to Details collection and review each field.
## Choose the fields
The starting fields are Name and Email address, both required. Review their names, input types, descriptions, and Required settings. Add only the information needed for the follow-up and keep field names distinct.
> **Customer prompt**: Explain why you need the information and what the customer can expect next. Do not promise a response time unless your team can meet it.
## Save and publish
Select the connected channels where the action should run. Save the draft, review its preview, and publish it when the configuration is complete. Check the resulting enabled state before testing a live conversation.
## Test as a customer
1. Start a conversation with a request that matches When to use.
2. Check the customer prompt and field labels.
3. Try submitting without a required field, then enter valid test details.
4. Submit and confirm the conversation continues with the expected result.
5. Review the resulting customer details and conversation in the workspace.
## Related guides
- [Custom forms](/docs/user-guides/actions/custom-form)
- [Testing and publishing](/docs/user-guides/actions/testing-and-publishing)
---
# Custom Action
Call your API, run code on your website, or display a widget during a conversation.
## Overview
A custom action connects your agent to functionality you control. Use it to look up a record, pass a request to your own service, read a customer's cart on your website, or present a structured result in chat.
### Best for
Business-specific workflows that need your own data, website functions, or interactive interface.
## Action types
| Type | Runs where | Result |
| --- | --- | --- |
| Call API | QwryAI server | The agent uses the permitted API response data in its reply. |
| Run client-side code | Your website | A registered JavaScript function returns a result to the conversation. |
| Call API + show widget | Server and chat interface | An API response supplies data for a linked widget. |
| Show widget | Chat interface | A linked widget displays fixed or supplied data; automatic website triggers are available. |
The QwryAI custom action editor offers four action types. This saved action runs code on the visitor’s page.
## Create a custom action
1. Open Build → Actions, choose Create action, then Custom actions.
2. Select the action type and choose Save and continue.
3. Complete General with the action name and When to use instructions.
4. Define the data inputs the action needs. For API actions, configure the request; for client actions, register the website function.
5. Run the API test when applicable, then choose what response data the AI may access.
6. For a widget action, add or select a widget and connect its inputs.
7. Select the supported channels, save your configuration, and use Save & enable.
8. Test a realistic conversation in the channel where customers will use it.
## General
Use an action name that describes one task, such as Look up delivery status. In When to use, describe the customer's request, the inputs needed, and the expected outcome. Avoid instructions that overlap with unrelated actions.
Use When not to use (optional) to describe requests that should be excluded. This helps distinguish the action from other tools that have similar purposes.
> **Automatic activation**: Only Show widget supports Visit, Delay, Scroll, and Chat opened triggers. These run in website chat and require Chat bubble to stay enabled.
- [All trigger and display settings](/docs/user-guides/actions/automatic-triggers)
## Collect inputs
Add one input per value the action needs. Each row has a name, type, description, default, and Required setting. The supported scalar types are text, number, boolean, date, and email; Array collects multiple values. Use descriptive names that match your request variables or website handler.
| Setting | How to use it |
| --- | --- |
| Name | The variable passed to the request, widget, or client handler. Keep it unique. |
| Type and Array | Match the value expected by your destination. Review the default again after changing a type. |
| Description | Explain what to collect and any expected format. Client-side input descriptions are required. |
| Default | Provide a correctly typed fallback only when using it is appropriate for this task. |
| Required | Mark values that must be available for the action to proceed. |
## API request
Enter a public HTTPS endpoint and choose GET, POST, PUT, PATCH, or DELETE. Configure query parameters and headers in their respective rows. The body editor is available for POST, PUT, and PATCH; GET and DELETE do not use a body in this editor.
Use the variable picker to insert collected inputs, static conversation variables, or values from a connected integration. Ensure every input referenced in the request is defined. Put service authentication in the server request configuration, never in a browser registration snippet.
```http
GET https://api.example.com/orders/{{order_id}}
Accept: application/json
```
> **Your own endpoint**: The example domain illustrates the request format. Replace it with your service and its authentication requirements. Localhost and private network endpoints are not supported targets.
## Test response
Provide sample input values and run the API test. Inspect the returned status and response before continuing. Example JSON can help you configure response fields, but it does not replace a successful live API test for the current request.
If you change request-related settings after a passing test, run it again before enabling. Changing channels or response exposure does not itself change the HTTP request.
- [Test and publish an action](/docs/user-guides/actions/testing-and-publishing)
## Data access
Choose Full access to make the available response data accessible to the AI, or Limited access to select the fields it needs. Limited access requires at least one selected field. Prefer a small response that directly answers the user's request.
Review the response tree and output mapping after changing your API response. A widget's bindings and the data the AI can read serve different purposes: check both before launch.
## Channels
Select at least one supported channel. Client-side actions need a browser host and offer Chat bubble and Help page. Automatic widget triggers run only on website Chat bubble. Other action types show their supported channels in the editor.
> **Test the actual destination**: An editor preview does not register a function on your website or confirm a messaging channel's rendering. Finish your test in the customer-facing channel.
## Related guides
- [Client-side actions and a complete HTML example](/docs/user-guides/actions/client-side-actions)
- [Widgets and response mapping](/docs/user-guides/actions/widgets)
- [Automatic triggers](/docs/user-guides/actions/automatic-triggers)
---
# Custom Button
Give visitors a clear next step with a Help Page link or an interactive widget.
## Overview
QwryAI supports buttons in Help Page and in interactive widgets. Choose Help Page buttons for fixed navigation links, or create a widget when a button belongs to a conversational action.
## Add Help Page buttons
1. Open Channels → Help Page and choose Display.
2. Open Buttons and enable Primary button, Secondary button, or Link button.
3. Enter a label and destination URL for each enabled button.
4. For link buttons, add an optional description. You can add up to two link buttons.
5. Review the preview, save changes, and open the public Help Page to test the destinations.
| Field | Editor limit |
| --- | --- |
| Button label or link title | 120 characters. |
| Destination URL | 2,048 characters. |
| Link description | 200 characters. |
## Show a button in a conversation
Use Widget Studio to create the interface, then link it to a Show widget or Call API + show widget custom action. Configure when the action should run and test the button inside the target channel. For a button that needs your website's JavaScript, use a registered client-side action handler.
- [Widgets and response mapping](/docs/user-guides/actions/widgets)
- [Client-side actions](/docs/user-guides/actions/client-side-actions)
## Check the visitor experience
- Use a label that describes the destination or result.
- Open every link on desktop and mobile.
- Check keyboard focus and activation.
- Check both themes and avoid labels that truncate.
- Verify the published page after saving; an editor preview alone does not confirm the destination.
## Related guides
- [Help Page](/docs/user-guides/agent-management/help-page)
- [Widget Studio](/docs/user-guides/agent-management/widget-studio)
---
# Escalate to Human
Configure when the agent should ask for consent, collect details, and queue a human handoff.
## Overview
The Escalations action defines how a conversation reaches the configured support destination. It combines selection instructions, customer confirmation, optional details collection, and channel availability.
## Configure General
1. Open Build → Actions and choose Escalations.
2. Enter an Action name and review the Escalation destination shown for this workspace.
3. Describe the requests that require a handoff in When to use.
4. Describe the cases the AI should continue handling in When not to use.
5. Review the confirmation and Playbook controls, then save and continue.
## Handoff controls
| Control | Behavior |
| --- | --- |
| Only use in Playbooks | Makes the action available to Playbooks while excluding it from general action selection and intent routing. |
| Confirm explicit requests | Asks for confirmation when the customer directly requests a human. |
| Confirm AI recommendations | Requires customer consent when the AI recommends a handoff. |
## Collect details
Use Details collection to decide whether the handoff needs customer information. Review each field's name, description, type, and required status. The initial configuration includes name, email, subject, and description. Use Skip when no details are needed for your flow.
## Publish to channels
Choose at least one connected channel. With direct selection enabled, use Publish to make the configuration available. With Only use in Playbooks enabled, use Save for Playbooks and reference the action from the relevant procedure.
## Verify the handoff
- Test a direct request for a human and a request where the AI recommends escalation.
- Check the enabled confirmation prompt and try both consent and cancellation.
- Verify required details are collected before queueing.
- Confirm the handoff reaches the configured support destination.
- Have a support associate take over and verify the customer sees the expected reply.
> **Destination**: Use the destination actually displayed in your workspace. This editor does not establish a connection to an arbitrary external ticketing system.
## Related guides
- [Live Chat](/docs/user-guides/actions/live-chat)
- [Testing and publishing](/docs/user-guides/actions/testing-and-publishing)
---
# Shopify Actions
Connect store data and customer workflows to your AI agent.
## Overview
Shopify actions provide store-specific tools for products, carts, orders, customer profiles, addresses, and account access. Connect the correct store before configuring which tools your agent can use.
## Connect the store
1. Open Build → Actions and select Shopify.
2. Choose Connect Shopify and authorize the store connection.
3. Return to QwryAI and confirm the connected store.
4. Add the action you need from the Shopify action picker.
## Available actions
| Action | Purpose |
| --- | --- |
| Retrieve and display products | Search and display the synced store catalog. |
| Get cart | Retrieve the customer's cart contents. |
| Retrieve and display orders | Retrieve orders and their status. |
| Update Shopify customer profile | Update customer profile values such as name, email, or phone. |
| Update Shopify customer billing address | Update the customer's billing address. |
| Check account & send activation email | Check account access and send an activation link when applicable. |
## Configure and publish
1. Open the action and review its Action name.
2. Write When to use instructions that explain the data it returns or changes and give an example customer request.
3. For products, sync the catalog and wait until it is ready.
4. Use Edit product cards to change the product reply layout in Widget Studio when needed.
5. Choose the supported channels, save the configuration, and Publish.
## Maintain product results
The Products section shows sync status and counts for products, variants, and collections. Use Re-sync products after store catalog changes. Changes saved in the product-card builder apply to new product replies.
## Verify customer workflows
- Ask for a known product and check the displayed price, variant, and destination.
- Test cart behavior from the connected storefront with a test cart.
- Test order lookup with the appropriate signed-in customer context.
- For profile and address updates, review the proposed values and verify the saved result.
- Test unavailable data and connection failures so the agent provides a useful next step.
> **Customer context**: Private order and account operations depend on the connected store and customer context. Do not treat a visitor's typed email address alone as proof of account ownership.
## Manage availability
Use each action's enabled control to manage availability. Deleting a saved Shopify action makes that configuration unavailable immediately; disconnecting the store affects the connected Shopify workflows. Review the confirmation shown by the platform before making either change.
---
# Slack
Make compatible actions available through your connected Slack channel.
## Overview
Slack is a connected conversation channel in QwryAI. Connect the workspace and select a channel, then enable compatible actions for Slack in each action's Channels settings.
## Connect and choose a channel
1. Open the chatbot's Slack connection from Channels or Integrations.
2. Connect the intended Slack workspace using the authorization flow.
3. Choose the channel QwryAI should use. Search by name or filter the channel list by public or private.
4. Save the selected channel and verify the connection status.
## Enable compatible actions
Open the action you want to use, expand Channels, and select Slack when it is available and connected. Save and enable the action, then test the matching request in Slack. Website-only triggers and client-side website handlers do not run inside a Slack conversation.
## Send a custom Slack notification
For an outbound notification workflow, configure a Custom action against an endpoint you control that sends the permitted message to Slack. Keep credentials on the server, define the notification payload explicitly, and test with a dedicated channel before enabling it.
- [Configure a custom API action](/docs/user-guides/actions/custom-action)
## Test in Slack
- Confirm the workspace and selected channel before sending a test message.
- Check the agent's response in Slack, including any action result.
- Verify the action is enabled for Slack, rather than only for Chat bubble.
- Review what conversation information is visible to channel members.
- If the channel list fails to load, resolve the displayed connection error and retry.
---
# Web Search
Let your agent search public information when its answer needs a current source.
## Overview
Web search gives the agent a way to retrieve public information during a conversation. Use When to use to explain the questions that should trigger it.
## Configure web search
1. Choose Web search in Create action.
2. Enter the Action name and When to use instructions.
3. Choose whether to Include images.
4. Optionally enter Included domains, one public HTTP or HTTPS URL per line.
5. Select channels, save, and enable the action.
## Limit search scope
Leave Included domains empty to search the public web, or enter up to 300 public URLs to restrict the search. Use sources appropriate for your customer's question and avoid private or local addresses.
## Test the result
- Ask a question that matches your instructions and check the cited sources.
- If domains are restricted, verify the response uses the intended sources.
- Test a question with no useful result and check that the agent explains the limitation.
- Check image rendering in the selected channel when images are enabled.
---
# Client-side actions
Connect an AI action to a JavaScript function on the page hosting your chat widget.
## Overview
Run client-side code lets an action use functionality on your own website. Your page registers a named handler, and the chat widget calls that handler when the agent selects the action. This is useful for reading a cart or updating a page interface.
> **Browser channels**: Client-side actions are configured for Chat bubble or Help page. The page hosting the widget must register the function; a registration on another page does not apply to it.
## Configure the action
1. Create a Custom action and choose Run client-side code.
2. Enter the action name and When to use instructions.
3. Add the inputs and a description for each. Match the names your function expects.
4. In Connect your website, copy the registration snippet. Use the exact function name shown there.
5. Add your implementation to each page that embeds the widget, after the embed script.
6. Check I've added this code to my website, save, and enable the action on a browser channel.
Copy the exact generated function name from Inputs, implement the handler on your website, and confirm installation before enabling.
## Read the current page
A support assistant can read the page a visitor is viewing before explaining the next step. This example returns the page's actual title and headings. Save it as an HTML file on a permitted domain, replace the embed URL with your Deploy snippet, and replace Read_current_page with the exact function name generated by your action. Configure the action with no inputs and describe when page context is needed.
```html
QwryAI deployment guide
Deploy your QwryAI agent
Add the widget to your website
Copy your agent's embed script from Deploy and add it to your website.
Check the customer experience
Open your website, send a message, and review the conversation in QwryAI.
Page context has not been requested.
```
The embedded QwryAI agent invokes the registered handler and answers with the actual page title and headings. The page confirms that context was shared.
## Handler contract
| Value | Meaning |
| --- | --- |
| args | The input values supplied to the action, addressed by your configured field names. |
| user | The visitor context supplied by the widget. Treat browser-provided values as untrusted at your server. |
| { status: "success", data } | Return JSON-compatible data the action can use. |
| { status: "error", error } | Return a useful error message when the operation cannot complete. |
> **Register together**: One registerTools call replaces the previous registry. Register every client action in the same object so a later call does not remove an earlier handler.
## Connect your application
Read the information your website actually displays, or call your own authenticated backend when an action needs account-specific data. Keep private API credentials on that backend, validate action arguments there, and check that the signed-in user can perform the requested operation.
If you rename the action, copy the current function name again and update your registration. Keep the script order shown in the example so registration runs after the widget script.
## Troubleshooting
| Symptom | Check |
| --- | --- |
| The widget does not load | Use the exact Deploy snippet and a permitted domain. |
| The action cannot run | Check that its generated name matches the registered property exactly, and the registration executes on this page. |
| One client action stopped working | Combine the handlers into one registerTools call. |
| The action runs with missing data | Review input names, Required settings, defaults, and descriptions. |
| It works in a demo but not your site | Check script loading order, browser errors, and whether page navigation removes or replaces the registration. |
---
# Automatic triggers
Show a widget when a visitor arrives, waits, scrolls, or opens the chat.
## Overview
Automatic triggers start a Show widget action from activity on your website. Add structured trigger chips in General → When to use. You can still write instructions describing when the AI should use the action during a conversation.
> **Availability**: Automatic triggers apply to Show widget actions on website Chat bubble. Call API, Run client-side code, and Call API + show widget do not support automatic activation.
## Add triggers
1. Create or open a Show widget action and complete its widget configuration.
2. In General, open the trigger picker in When to use.
3. Add a Visit, Delay, Scroll, or Chat opened chip and configure its value.
4. Add up to four trigger chips and choose AND or OR between adjacent triggers.
5. Review display settings, keep Chat bubble enabled, save, and enable the action.
6. Visit the website with the embedded widget to test the rule.
## Trigger types
| Trigger | Configuration | Use case |
| --- | --- | --- |
| Visit | First visit, every visit, a specific visit number, or every N visits. Number values: 1–1,000. | Welcome first-time visitors or offer help on a return visit. |
| Delay | Wait 1–86,400 seconds. | Give the visitor time to read before offering help. |
| Scroll | Wait until 1–100% page progress. | Offer a related widget after a visitor explores a page. |
| Chat opened | No numeric value. | Show useful content when the visitor opens chat. |
## What counts as a visit
The website widget keeps the current visit for the lifetime of a browser tab session. Reloading the same tab does not create another visit or reset its display cap. The visit count and dismissal history are retained in that browser for the website origin. A separate new tab session can count as a later visit; some browsers copy a tab session when a page opens another tab.
To check first-visit behavior, use a fresh browser profile or private browsing session without earlier visits. To check returning-visit behavior, retain that browser’s site history and open the website in a new tab session. Do not treat a refresh as a return visit.
## Combine conditions
AND requires the connected conditions together. OR offers an alternative. AND takes precedence when a rule contains both: Visit AND Delay OR Scroll means either the Visit-and-Delay group or the Scroll condition can qualify.
> **Display settings still apply**: Visit eligibility, frequency limits, dismissal rules, and placement belong to the whole activation rule. An OR condition does not bypass these display settings.
## Display settings
| Setting | Options |
| --- | --- |
| Eligible visits | First, every, a specific visit, or an interval of visits. |
| Total displays | 1–1,000, or unlimited. |
| Displays per visit | 1–10. |
| After dismissal | Wait until the next visit, snooze for 1–365 days, or dismiss permanently. |
| Placement | Popup only, popup and chat, or inside chat. |
The default display settings target the first visit, allow one total display and one display per visit, use next-visit dismissal, and place the widget in a popup. A Chat opened condition needs a placement that includes chat; the editor adjusts popup-only placement for that condition.
> **Repeat displays**: A one-total-display limit can prevent a widget from reappearing even when its dismissal period has ended. Increase the total limit when you intend to test repeat visits.
The setup-assistance draft combines four triggers. Shared visit eligibility, display limits, snooze, and placement still apply to the whole rule.
## Examples
| Goal | Rule and settings |
| --- | --- |
| First-visit welcome | Visit: first AND Delay: 15 seconds. Use popup placement and a low display limit. |
| Help after browsing | Scroll: 50% AND Delay: 30 seconds. Choose eligible visits and frequency deliberately. |
| Chat introduction | Chat opened, inside chat, with one display per visit. |
## Verify on your website
Test each condition independently, then the combined rule. Check the visitor's first and later visits, closing the popup, reopening chat, and the maximum display counts. Use a fresh visitor context for first-visit checks and a later tab session in the same browser for returning-visitor checks. Reload the current tab to verify that per-visit caps and dismissal persist.
- [Testing and publishing](/docs/user-guides/actions/testing-and-publishing)
Real setup cards from separate eligible visits remain in the QwryAI conversation history. The last card appeared after opening chat on the embedded deployment guide.
---
# Widgets and response mapping
Attach a reusable widget and connect the values it needs to display.
## Overview
Widgets turn an action result into an interactive card. Choose Call API + show widget when the card needs an API response, or Show widget when it can use fixed values and supplied inputs.
## Attach a widget
1. Open the Widget section of a compatible custom action.
2. Choose Add widget to create or select a widget, or upload a .widget file.
3. Review the selected widget and its declared input fields.
4. Connect the action data to those fields and check the preview.
5. Save and continue, then select channels and enable the action.
> **Shared widgets**: A selected widget is linked, not an independent copy. Editing a shared widget can affect every action using it. Review those actions before changing its inputs or layout.
## Connect data
For API widgets, first run a successful API test so you can inspect the response structure. Map the response values to the widget inputs, paying attention to field names, types, nested objects, and arrays. For Show widget, define any inputs the agent should supply and keep them aligned with the widget schema.
```json
{
"page": {
"title": "QwryAI deployment guide",
"headings": ["Deploy your QwryAI agent", "Add the widget to your website", "Check the customer experience"]
}
}
```
A page-help card can map its title and headings inputs from the page object. These values reflect the deployment guide used in the client-side action walkthrough. Use the actual response shape from your own API when mapping an API widget.
## Collect fields before showing a widget
For a conversational Show widget action, use Collect widget fields before showing it when the agent should obtain required information first. An action with automatic triggers displays immediately: the input-collection switch is disabled, so the widget must work with the data already available. Give optional fields useful defaults and check the empty-data state.
## Manage the linked widget
| Control | Purpose |
| --- | --- |
| Edit | Open the linked widget for changes. |
| Replace | Choose a different widget for the action. |
| Download | Export the widget for reuse. |
| Unlink | Remove the widget association from this action. |
| Upload widget | Import a .widget file from the empty widget section. |
## Check the customer experience
- Test with a complete response and with missing optional values.
- Check long labels, arrays with multiple items, and an empty result.
- Verify buttons and form controls on the deployed website.
- Check the narrow mobile layout and keyboard focus order.
- If the action is automatic, test its placement and dismissal settings too.
- [Automatic triggers](/docs/user-guides/actions/automatic-triggers)
- [Custom Action](/docs/user-guides/actions/custom-action)
---
# Testing and publishing
Move from a saved draft to an enabled action with a verified customer workflow.
## Overview
A draft stores your configuration. Enabling publishes the action for the selected channels. Complete the checks for your action type before enabling, then verify the result from the customer's channel.
## Before enabling
| Action type | Requirements to review |
| --- | --- |
| Call API | Valid inputs and request, a passing test for the current request, response access, and supported channels. |
| Run client-side code | Input descriptions, the exact host registration, the website setup acknowledgment, and browser channels. |
| Call API + show widget | API requirements plus a linked widget and valid data bindings. |
| Show widget | A linked widget, any necessary inputs, supported channels, and valid automatic rules if used. |
## Run an API test
1. Save the request configuration you intend to use.
2. Open Test and supply representative values for the inputs.
3. Run the test and review its final status and response.
4. Resolve authentication, request, or response problems and repeat the test.
5. Select the fields the AI may read in Data access.
> **Tests can perform real work**: A test calls your configured endpoint. Use a test record or sandbox endpoint when a request creates or updates data.
A successful test is tied to the request configuration. If the editor asks you to retest after a change, do so before enabling. Example JSON is a configuration aid, not proof that the endpoint responds successfully.
## Enable the action
Use Save & enable after completing the required sections. If QwryAI asks for an approval policy for a write action, select a published policy that applies to the operation. Resolve any field or test errors and confirm the action's enabled state in My actions.
After Save & enable, My actions shows Read current page as Live on one channel.
## Test as a customer
| Scenario | Expected check |
| --- | --- |
| Matching request | The agent selects the intended action and shows the correct result. |
| Missing required input | The conversation obtains the needed information before proceeding. |
| Unrelated request | The action does not take over an unrelated conversation. |
| Unavailable service or failed handler | The customer receives a useful failure or next step without a false success claim. |
| Client action | The registered function runs on your embedded test page and returns data. |
| Widget action | The card shows the right values and its interactions work. |
| Automatic widget | Conditions, display limits, dismissal, and placement behave as configured. |
| Disabled action | A new matching conversation no longer uses the disabled action. |
## Troubleshooting
| Problem | Next step |
| --- | --- |
| Save & enable is blocked | Review all required fields, selected channels, website acknowledgment, widget association, and API test status. |
| Behavior policy must compile before publishing | Save the draft and reopen it after processing. If the error remains, contact support with the action name and the displayed error. A saved draft is not enabled. |
| The AI does not select the action | Check that it is enabled on this channel and give When to use a precise, relevant instruction. |
| The API responds but the AI lacks data | Review Full or Limited access and the selected response fields. |
| The widget is empty | Compare its input schema with the latest test response and bindings. |
| An automatic widget does not reappear | Check first-visit rules, total and per-visit caps, and dismissal state. |
---
# Cal
Offer a Cal.com event from a customer conversation.
## Overview
The Cal action connects a booking experience to the event URL you configure. The event's availability and scheduling rules remain in Cal.com.
## Set up the action
1. Choose Cal in Create action.
2. Enter the action name and When to use instructions.
3. Provide the Cal.com Event URL for the event customers should book.
4. Choose the time display format.
5. Select channels, save, and enable the action.
## Test booking
- Ask the agent for the meeting described in your instructions.
- Check that the intended event opens and the displayed timezone is appropriate.
- Complete a test booking and verify it in your scheduling system.
- Check what customers see when no time is available.
---
# Custom form
Collect structured information with a form inside the conversation.
## Overview
A custom form asks for a defined set of customer details. Configure when it should appear, the prompt customers see, and the fields they need to complete.
## Create a form
1. Choose Custom form in the create-action catalog.
2. Set the Action name, Description, and When to use instructions.
3. Write the Customer prompt shown with the form.
4. Configure field names, types, descriptions, and required values.
5. Choose the supported channels and save the action.
6. Review the preview, then enable and test it in a conversation.
## Preview and submission
The editor preview lets you check the form experience. A preview submission does not save customer data. Verify the real submission from a customer conversation before relying on it for follow-up.
## Best practices
- Ask only for details needed for the stated purpose.
- Use clear labels and mark required fields deliberately.
- Test incomplete and invalid values as well as a valid submission.
- Check that the completed information reaches the intended workflow.
---
# Suggested Messages
Configure simple and nested starting questions in the channel editor.
## Offer useful starting questions
Suggested messages help a visitor start a conversation with a question your agent can answer. In QwryAI they are configured in the channel editor, rather than as a separate Create action card.
## Configure Help Page suggestions
1. Open Channels → Help Page and its display/content settings.
2. Enable Suggested messages.
3. Choose Add message and select Simple or Nested.
4. Set a label and optional icon. For Simple, enter the message sent to the agent; for Nested, add the options visitors can choose.
5. Reorder suggestions with the drag handle or its Up/Down arrow keys.
6. Save and check each suggestion in the actual Help Page.
## Suggestion fields
| Field | Meaning |
| --- | --- |
| Label | The short text displayed on the suggestion. |
| Message | The request sent when a Simple suggestion is selected. |
| Options | The choices shown after selecting a Nested suggestion. |
| Icon | A visual cue for the topic. |
## Verify the conversation
Choose topics supported by your real sources, such as adding the website widget or connecting help pages. Check that selecting each option sends the intended request and gives a useful answer.
- [Help Page](/docs/user-guides/agent-management/help-page)
---
# Contacts Overview
Use contacts to keep customer identity, conversation history, and attributes connected.
## Contacts
Contacts brings together people and anonymous visitors captured by your agent. Open Contacts from the agent sidebar to review names, email addresses, phone numbers, external IDs, and the last time each visitor was seen.
## Find a contact
1. Confirm the Chatbot filter is set to the agent you want to review.
2. Search by email, name, or ID.
3. Use Status to choose All, Anonymous, Lead, Customer, or Archived.
4. Open the contact name or Open contact. Use Open conversations to go directly to their conversation history.
## Review the profile
The contact detail shows the identifier, lifecycle, account, first and last seen timestamps, and any stored custom attributes. A visitor can remain Anonymous when they have not supplied identifying details. Missing information is displayed as No email or Not set; it is not inferred from the conversation.
## Adding and importing contacts
The current Contacts toolbar displays Import and Add contact, but these controls do not yet open an import or creation workflow. Use the supported widget and lead-collection flows to capture visitor information. Do not treat an email address entered in chat as proof of account ownership.
- [Collect Leads](/docs/user-guides/actions/collect-leads)
- [Conversations](/docs/user-guides/help-desk/conversations)