# Tirver, full text
---
Source: https://tirver.com/index.md
[New: an MCP server for AI assistants](https://tirver.com/help/mcp.md)
# Customer support that works when you can’t.
A smart AI agent that resolves customer questions and guides users through your product, with chat, help center, feedback, roadmap and changelog.
[Create a workspace](https://app.tirver.com/signup) [Read the docs](https://tirver.com/help/api.md)
Monthly, yearly or 3-year plans. The AI agent is billed per resolution.
- **Resolves questions**: Works from your help center, documents and website.
- **Guides users**: Walks customers through steps in your product.
- **Hands over**: Passes to a person on request or when unsure.
## See each module at work.
### Inbox
- **Views**: Yours, unassigned, team and AI-handled conversations.
- **Notes and tags**: Internal notes, mentions, tags and the saved reply picker.
- **Customer details**: Profile, a short summary and past conversations beside every chat.
### AI agent
- **Resolves questions**: Works from your help center, documents and website.
- **Guides users**: Walks customers through steps in your product.
- **Hands over**: Passes to a person on request or when unsure.
### Help center
- **Your domain**: A public knowledge base customers can search.
- **In the widget**: Customers search articles before they write to you.
- **Article ratings**: See which articles helped and which did not.
### Feedback
- **Ideas and votes**: Customers post ideas and vote on them.
- **From a chat**: Turn a conversation into a feedback post.
- **Your reply**: Comment as the team and set a status.
### Roadmap
- **Public roadmap**: Planned, in progress and shipped.
- **Fed by feedback**: Posts move here when you set a status.
- **Vote counts**: See demand on every card.
### Changelog
- **Release notes**: Write an entry and publish it to your changelog.
- **Linked feedback**: Publishing marks the post as shipped.
- **Announcements**: Voters hear by email and in the widget.
### Widget settings
- **Your brand**: Accent color, theme and launcher position.
- **Tabs**: A tab shows only when its module is on.
- **Live preview**: See the widget as customers will.
## A support agent at your disposal.
It resolves customer questions and guides users through your product, including when nobody on your team is online.
- **It resolves**: It works a question through to an answer from your help center, documents and website, and links what it used.
- **It guides**: It walks users through setup and how-to steps, right inside the widget.
- **It covers for you**: It keeps helping outside business hours and hands over when a person is needed.
### Try the widget yourself.
This is the messenger your customers see. Ask a question, ask for a person, search the help articles or vote on an idea. The company and answers are made up, but the behavior is the product’s.
- [How the AI agent answers](https://tirver.com/help/how-the-ai-agent-answers.md)
- [Install the widget](https://tirver.com/help/install-the-widget.md)
- [Customize the widget](https://tirver.com/help/customize-the-widget.md)
- [Handoff rules](https://tirver.com/help/handoff-rules.md)
## From a chat to the changelog.
1. **A customer asks**: The request arrives in your inbox from the widget.
2. **You file it**: Turn the conversation into a feedback post others can vote on.
3. **It moves**: Set a status and the post appears on your public roadmap.
4. **Everyone hears**: Publish a changelog entry and every voter is told.
## One workspace instead of four tools.
| The job | Usually a separate | In Tirver |
|---|---|---|
| Talk to customers | Live chat and help desk tool | Widget and shared inbox |
| Resolve questions around the clock | AI chatbot add-on | A support agent, billed per resolution |
| Document the product | Knowledge base tool | Help center on your domain |
| Collect ideas and announce | Feedback board and changelog tools | Feedback, roadmap and changelog |
## One plan. AI billed per resolution.
- **Tirver suite**: Chat, inbox, help center, feedback, roadmap and changelog.
- **AI agent**: Charged per resolved conversation. Handoffs to your team are free.
- **Credit packs**: Extra resolutions for busy months, bought when you need them.
## Questions teams ask first
**How much does Tirver cost?**
One suite on a monthly, yearly or 3-year plan, plus a charge for each conversation the AI agent resolves. Handoffs to your team are free. Prices are not published yet, so the billing page in the app shows them as to be set. [Billing, plans and AI credits](https://tirver.com/help/billing-and-credits.md)
**How long does setup take?**
The Get started checklist has five steps: create the workspace, install the widget, add knowledge sources, switch on the AI agent and invite your team. It counts about three minutes a step. [Create your workspace](https://tirver.com/help/create-your-workspace.md)
**How does the AI agent answer?**
It answers only from the sources you give it and links each source it used. If no source answers, or the customer asks for a person, it hands the conversation to your team. [How the AI agent answers](https://tirver.com/help/how-the-ai-agent-answers.md)
**What can I add as knowledge sources?**
Upload PDF, Word, Markdown, text and HTML files of up to 25 MB, or point the agent at a sitemap or a page on your website and re-crawl when it changes. [Add knowledge sources](https://tirver.com/help/add-knowledge-sources.md)
**Can a person take over a conversation?**
Yes. The agent hands over when the customer asks for a person, when no source answers, on billing disputes and on phrases you choose. Your team sees why in a note, and the agent stops replying. [Handoff rules](https://tirver.com/help/handoff-rules.md)
**Which languages does it support?**
The Tirver app and widget are in English. The AI agent answers from the sources you add, so it works best when they are in the language your customers write in. [How the AI agent answers](https://tirver.com/help/how-the-ai-agent-answers.md#languages)
**What happens to our customers’ data?**
Each workspace is separate, and only its members can see its conversations. The AI agent uses only the sources you add, and you can delete any source at any time. [Security and your customers’ data](https://tirver.com/help/security-and-data-privacy.md)
**How secure is the widget?**
Sign customers in with a hash from your server so nobody can read another customer’s chats, and limit the widget to your own domains. [Control the widget](https://tirver.com/help/security-and-data-privacy.md#control-the-widget)
**Is there an API or an MCP server?**
Yes. The REST API is for your own code, and the MCP server lets an assistant such as Claude search articles, read conversations and draft replies. The MCP server never messages a customer: its write tools leave an internal note or a draft that a person reviews. [API docs](https://tirver.com/help/api.md)
**Can I cancel or change my plan?**
To change your plan or cancel, write to hello@tirver.com. Paid plans are not on sale yet, so there is nothing to cancel today. [Cancel or change plan](https://tirver.com/help/billing-and-credits.md#cancel-or-change-plan)
**Can I use only chat and the AI agent?**
Yes. Each module has its own switch, and modules that are off stay out of your widget. [Switch modules on and off](https://tirver.com/help/switch-modules-on-and-off.md)
## Paste one snippet and go live.
```html
```
1. Create your workspace and invite your team.
2. Add the widget script to your app.
3. Add knowledge sources and switch on the AI agent.
---
Source: https://tirver.com/help.md
# Tirver help center
> Guides for every part of Tirver: the widget, the inbox, the AI agent, the help center, feedback, the roadmap, the changelog, billing and the developer docs.
## [Getting started](https://tirver.com/help/collection/getting-started.md)
Set up a workspace and go live.
- [What Tirver is and what is in it](https://tirver.com/help/what-is-tirver.md): A tour of the Tirver modules and how customers and your team use them.
- [Create your workspace](https://tirver.com/help/create-your-workspace.md): Sign up, name your workspace and follow the Get started checklist.
- [Install the widget](https://tirver.com/help/install-the-widget.md): Add the Tirver messenger to your product with one script tag.
- [Identify signed-in customers](https://tirver.com/help/identify-signed-in-customers.md): Tell the widget who is signed in, with a hash from your server, so nobody can read another customer's conversations.
- [Limit the widget to your domains](https://tirver.com/help/allowed-domains.md): Choose which websites may load your widget.
- [Invite your team](https://tirver.com/help/invite-your-team.md): Invite teammates as admins or agents and manage who has access.
- [Switch modules on and off](https://tirver.com/help/switch-modules-on-and-off.md): Turn Tirver features on or off for your workspace and widget.
## [Inbox](https://tirver.com/help/collection/inbox.md)
Answer conversations as a team.
- [Views, search and assignment](https://tirver.com/help/views-and-assignment.md): Find the conversations that need you and assign them to the right person.
- [Replies, notes, mentions and tags](https://tirver.com/help/reply-notes-and-tags.md): Answer customers, keep internal notes for the team and label conversations.
- [Saved replies](https://tirver.com/help/saved-replies.md): Insert a prepared answer from the reply box in one keystroke.
- [Snooze, close and reopen conversations](https://tirver.com/help/snooze-and-close.md): Pause a conversation until later, finish it, or bring it back.
- [Customer details and history](https://tirver.com/help/customer-details.md): See who you are talking to and what they asked before.
- [Resize and collapse inbox panels](https://tirver.com/help/resize-and-collapse-inbox-panels.md): Shape the five-column inbox to your screen, with the mouse or the keyboard.
## [AI agent](https://tirver.com/help/collection/ai-agent.md)
Teach it, set its limits, track its cost.
- [Set up the AI agent](https://tirver.com/help/set-up-the-ai-agent.md): Name it, choose its tone and decide when it answers.
- [Add knowledge sources](https://tirver.com/help/add-knowledge-sources.md): Upload documents or crawl your website so the AI agent has something to answer from.
- [How the AI agent answers](https://tirver.com/help/how-the-ai-agent-answers.md): What the agent looks at, what it says, and when it steps back.
- [Handoff rules](https://tirver.com/help/handoff-rules.md): Decide when the AI agent passes a conversation to a person.
- [What counts as a resolution](https://tirver.com/help/what-counts-as-a-resolution.md): How Tirver decides that the AI agent resolved a conversation, and what it costs.
- [Test the AI agent](https://tirver.com/help/test-the-agent.md): Try questions on the agent before customers do, without using credits.
- [AI usage and credits](https://tirver.com/help/ai-usage-and-credits.md): Read the usage page and see how many credits are left.
## [Help center](https://tirver.com/help/collection/help-center.md)
Write and publish articles.
- [Write your first article](https://tirver.com/help/write-your-first-article.md): Write, preview and publish a help article.
- [Organise articles in collections](https://tirver.com/help/collections.md): Group articles into collections so customers can browse them.
- [How customers find your articles](https://tirver.com/help/how-customers-find-articles.md): The widget Help tab, search, and the public feeds you can use on your own site.
- [Article ratings](https://tirver.com/help/article-ratings.md): See which articles helped and which need work.
## [Feedback, roadmap and changelog](https://tirver.com/help/collection/feedback-roadmap-changelog.md)
Collect ideas and announce what ships.
- [Feedback boards and posts](https://tirver.com/help/feedback-boards-and-posts.md): Collect ideas, let customers vote, and decide what happens to each one.
- [The roadmap](https://tirver.com/help/the-roadmap.md): Show customers what is planned, in progress and shipped.
- [Publish a changelog entry](https://tirver.com/help/publish-a-changelog-entry.md): Announce what shipped, link the ideas behind it and tell the people who asked.
## [Messenger](https://tirver.com/help/collection/messenger.md)
Make the widget yours and set your hours.
- [Customize the widget](https://tirver.com/help/customize-the-widget.md): Set the accent colour, theme, position, greeting and tabs of your messenger.
- [Business hours and the away message](https://tirver.com/help/business-hours-and-away-message.md): Tell Tirver when your team is online and what customers see when it is not.
## [Team, billing and reports](https://tirver.com/help/collection/team-billing-reports.md)
People, plans, credits and numbers.
- [Team roles and permissions](https://tirver.com/help/team-roles.md): What owners, admins and agents can do.
- [Billing, plans and AI credits](https://tirver.com/help/billing-and-credits.md): How the Tirver suite and AI resolutions are billed, and where to see your balance.
- [Redeem a code](https://tirver.com/help/redeem-a-code.md): Apply a lifetime deal or promotional code to your workspace.
- [Your profile and account menu](https://tirver.com/help/your-profile.md): Set your name and picture, switch between light and dark, and log out.
- [Conversation volume and response times](https://tirver.com/help/conversation-reports.md): Read the Reports page for conversation volume, AI resolutions and article ratings.
## [Security and privacy](https://tirver.com/help/collection/security-privacy.md)
Keep customer data safe.
- [Security and your customers' data](https://tirver.com/help/security-and-data-privacy.md): How Tirver keeps conversations separate, who can see what, and the controls you hold.
## For developers
- [REST API](https://tirver.com/help/api.md): Read conversations and reply, look up customers, read and draft articles, file feedback and read the changelog from your own code.
- [MCP server](https://tirver.com/help/mcp.md): Let an AI assistant such as Claude search articles, read conversations and draft replies.
---
Source: https://tirver.com/help/customize-the-widget.md
# Customize the widget
> Set the accent colour, theme, position, greeting and tabs of your messenger.
Make the messenger look like part of your product. Open **Settings, Messenger**. A live preview beside the form shows exactly what customers will see.
Only admins and owners can change these settings.
## Appearance
| Setting | Choices |
|---|---|
| Accent color | Blue, Teal, Amber or Ink, or your own colour as six hex digits after a `#`, for example `#2f6fed`. |
| Theme | Match the visitor, Light or Dark. |
| Launcher position | Bottom right or Bottom left. |
| Greeting | The welcome line customers see when they open the widget. |
The launcher picks readable text on top of your colour automatically.
## Tabs in the widget
| Tab | Shows | Needs module |
|---|---|---|
| Messages | Live chat and the AI agent | Live chat |
| Help | Search and read help articles | Help center |
| Ideas | Vote on ideas and see the roadmap | Feedback |
| News | Latest changelog entries | Changelog |
A tab shows only when its module is on. Use the **Visible** switch to hide a tab even when its module is on. See [switch modules on and off](https://tirver.com/help/switch-modules-on-and-off.md).
## Save
Select **Save**. Customers see the change on their next page load, with no new snippet to install.
## On phones
On narrow screens the messenger opens full screen, so customers have room to type.
Source: https://tirver.com/help/customize-the-widget
---
Source: https://tirver.com/help/feedback-boards-and-posts.md
# Feedback boards and posts
> Collect ideas, let customers vote, and decide what happens to each one.
Feedback gives customers a place to tell you what they want, and gives you a way to show you listened.
## Create a board
Boards group ideas, for example Integrations or Mobile app.
1. Open **Feedback**.
2. In the **Boards** column, type a name under **New board**.
3. Add it.
## Posts
Add ideas yourself with **New post**, for example after a customer asks for something in a chat. You can also file posts from code with the [API](https://tirver.com/help/api/feedback-posts.md) or from an assistant with the [MCP server](https://tirver.com/help/mcp/triage-feedback.md). Customers cannot post new ideas from the widget yet. A post has a title, a description, votes and comments.
Search posts, filter by board and sort the list to find what matters most.
## Votes and comments
Customers vote for the ideas they want, and you can see who voted. Comment as the team to ask a question or give an update. Replies show on the post.
## Statuses
Set a status as the idea moves along.
| Status | Meaning |
|---|---|
| In review | New. You have not decided yet. |
| Planned | You intend to build it. |
| In progress | You are working on it. |
| Shipped | It is live. |
| Declined | You decided not to build it. |
A post can move forward or back along In review, Planned, In progress and Shipped. Any post in review can be declined. A declined post can only be reopened, and a shipped post cannot be declined unless you move it back first.
## Merge duplicates
When two posts ask for the same thing, open one and choose **Duplicate of another post**, then pick the original. Votes come together on the post you keep.
## Delete a post
Use **Delete post** on the post's page.
Planned, in progress and shipped posts appear on your [roadmap](https://tirver.com/help/the-roadmap.md).
Source: https://tirver.com/help/feedback-boards-and-posts
---
Source: https://tirver.com/help/security-and-data-privacy.md
# Security and your customers' data
> How Tirver keeps conversations separate, who can see what, and the controls you hold.
Support conversations hold your customers' words and sometimes their personal details. This article explains the controls that protect them and the ones you manage.
## Your workspace is separate
Everything you create, such as conversations, customers, articles, ideas and settings, belongs to your workspace. Teammates see it only when they are members, and each request in the app is checked against the workspace it belongs to.
## Control who gets in
- **Roles.** Owners, admins and agents have different access. Agents never see settings or billing. See [team roles](https://tirver.com/help/team-roles.md).
- **Invitations.** People join only by invitation to their own email address.
- **Passwords.** Accounts use a password of at least 8 characters.
## Control the widget
- **Identity verification.** Sign the customer id on your server so nobody can read another customer's conversations. See [identify signed-in customers](https://tirver.com/help/identify-signed-in-customers.md).
- **Allowed domains.** Limit the widget to your own sites. See [allowed domains](https://tirver.com/help/allowed-domains.md).
- **Your secret stays yours.** The identity secret is shown once and stored so that it cannot be read back. Rotate it if it leaks.
## What the AI agent can see
The agent answers from the knowledge sources you add, and from the conversation it is in. It does not browse the wider internet, and it only discusses topics you allow. You can stop it using a source at any time by deleting the source. See [how the AI agent answers](https://tirver.com/help/how-the-ai-agent-answers.md).
## Developer access
API keys, which also work for the MCP server, are secrets. Treat them like passwords, give each one only the scopes it needs, set an expiry where you can, and revoke any you no longer use under **Settings, API keys**. See the [API docs](https://tirver.com/help/api.md) and the [MCP docs](https://tirver.com/help/mcp.md).
## Questions about privacy or a security issue
Write to [security@tirver.com](mailto:security@tirver.com) for security reports, or [hello@tirver.com](mailto:hello@tirver.com) for anything else.
Source: https://tirver.com/help/security-and-data-privacy
---
Source: https://tirver.com/help/set-up-the-ai-agent.md
# Set up the AI agent
> Name it, choose its tone and decide when it answers.
The AI agent answers customer questions in the widget from the material you give it, and guides people through your product. It works around the clock, and it hands over to your team when a person is needed.
Only admins and owners can change the agent.
## Before you start
The agent needs something to answer from. [Add knowledge sources](https://tirver.com/help/add-knowledge-sources.md) first. Without them it has nothing to cite and will hand most conversations over.
## Settings
Open **AI agent**, then **Behavior**.
| Setting | What it does |
|---|---|
| On or off | Switch the agent on for your workspace. It is off until you turn it on. |
| Name shown to customers | Up to 40 characters. The default is Tirver AI. |
| Tone | Friendly and brief, Neutral, or Formal. |
| When it answers | Answer at any time, or only outside business hours. |
| Extra instructions | Up to 4,000 characters of guidance, for example "always offer the mobile app link when someone asks about notifications". |
| Topics it may help with | Leave empty to let it answer anything your sources cover. |
| Topics to stay away from | For example legal advice or competitor comparisons. |
Select **Save changes** to apply them.
## Outside business hours only
If you choose to answer only outside business hours, the agent steps aside while your team is online. It uses the hours you set under [business hours](https://tirver.com/help/business-hours-and-away-message.md). With no hours set, every hour counts as outside them, so the agent answers all the time.
## The agent never talks over your team
When a conversation is assigned to a person, the agent stops replying to it. It also stops once it has handed a conversation over.
Next: [test the agent](https://tirver.com/help/test-the-agent.md), then set your [handoff rules](https://tirver.com/help/handoff-rules.md).
Source: https://tirver.com/help/set-up-the-ai-agent
---
Source: https://tirver.com/help/team-roles.md
# Team roles and permissions
> What owners, admins and agents can do.
Every person in a workspace has one role.
| Role | Conversations | Help center and feedback | Settings and billing |
|---|---|---|---|
| Owner | All | Write and publish | Everything, including billing |
| Admin | All | Write and publish | Everything except billing |
| Agent | Assigned and unassigned | Write drafts | None |
## What agents see
An agent works the inbox: their own conversations and the unassigned queue. In settings they see **Team** and their own **Profile**, and nothing else.
## Who can do what
- **Messenger, Modules and Billing** settings are for admins and owners. Only an owner can redeem codes.
- Only admins and owners can change the AI agent, its knowledge sources and its handoff rules.
- Only an owner can make someone an owner or change an owner's role.
## Keep an owner
A workspace always has at least one owner. Make someone else an owner before you leave or step down.
See [invite your team](https://tirver.com/help/invite-your-team.md).
Source: https://tirver.com/help/team-roles
---
Source: https://tirver.com/help/views-and-assignment.md
# Views, search and assignment
> Find the conversations that need you and assign them to the right person.
The inbox is where customer conversations from the widget arrive. Views are ready-made lists, so everyone can see what is theirs and what is waiting.
## Views
| View | What it shows |
|---|---|
| Your inbox | Open conversations assigned to you. |
| Unassigned | Open conversations nobody owns yet. New chats start here. |
| All open | Every open conversation. |
| AI agent | Conversations the AI agent is handling or has handled. |
| Snoozed | Conversations you paused until later. |
| Closed | Finished conversations. |
Below these you also get a view per teammate and a view per tag, so you can see everything one person owns or everything tagged `bug`.
## Search and sort
Type in **Search conversations** to filter the list. Sort by **Newest**, **Oldest** or **Waiting longest**, which puts the customers who have waited the most at the top.
## Assign a conversation
Open a conversation and use the **Assignee** dropdown in the details panel, or select **Assign to me**. Choose **Unassigned** to give it back to the queue.
While a conversation is assigned to a person, the AI agent stays out of it.
## Counts
The Inbox item in the navigation shows how many conversations need attention.
Related: [reply, notes and tags](https://tirver.com/help/reply-notes-and-tags.md), [snooze and close](https://tirver.com/help/snooze-and-close.md).
Source: https://tirver.com/help/views-and-assignment
---
Source: https://tirver.com/help/what-is-tirver.md
# What Tirver is and what is in it
> A tour of the Tirver modules and how customers and your team use them.
Tirver is customer support for SaaS teams. One workspace holds a messenger widget for your product, a shared inbox, an AI agent that answers from your own material, a help center, a feedback board, a roadmap and a changelog.
## The modules
Every module has its own switch, so you only run what you need.
| Module | What it does |
|---|---|
| Live chat and inbox | The widget in your product and the shared inbox where your team answers. |
| AI agent | Answers customer questions from the sources you give it and hands over to a person when needed. |
| Help center | Articles customers can search in the widget. |
| Feedback | Boards for ideas, with votes and comments. |
| Roadmap | A public view of planned, in progress and shipped ideas. |
| Changelog | Release notes customers see in the widget and on a changelog page. |
| Reports | Conversation volume, response times and AI resolutions. |
## Two sides
Your team works in the Tirver app at app.tirver.com. Your customers meet Tirver as a launcher in the corner of your product. Opening it shows tabs for Messages, Help, Ideas and News, depending on which modules are on.
## Where to go next
1. [Create your workspace](https://tirver.com/help/create-your-workspace.md).
2. [Install the widget](https://tirver.com/help/install-the-widget.md) in your product.
3. [Add knowledge sources](https://tirver.com/help/add-knowledge-sources.md) and [switch on the AI agent](https://tirver.com/help/set-up-the-ai-agent.md).
4. [Invite your team](https://tirver.com/help/invite-your-team.md).
Source: https://tirver.com/help/what-is-tirver
---
Source: https://tirver.com/help/write-your-first-article.md
# Write your first article
> Write, preview and publish a help article.
Help articles give customers an answer before they write to you. They appear in the widget's Help tab, where customers can search them.
## Create an article
1. Open **Help center**.
2. Select **New article**.
3. Enter a title in **Article title**.
4. Write the text under **Body in Markdown**. The formatting bar adds headings, bold, lists and links for you.
5. Pick a collection under **Article settings**, or leave it as **No collection**.
6. Check the **Preview** tab to see how it will look.
## Publish
New articles start as drafts, which only your team can see. Select **Publish** when it is ready. Publishing needs a title and some text. Later you can switch an article back to draft to take it off the widget, and publish it again when it is fixed.
Once published, the editor shows **Found helpful** and **Rated helpful** figures. See [article ratings](https://tirver.com/help/article-ratings.md).
## Edit and delete
Select an article in the list to edit it. Changes to a published article go live when you select **Update published article**. Use **Delete article** to remove it for good.
## View as Markdown
**View as Markdown** shows the article's Markdown, which is handy for pasting into other tools.
## Who can write
Owners and admins can write and publish. Agents can write drafts for an admin to publish. See [team roles](https://tirver.com/help/team-roles.md).
## Writing tips
- Start with the customer's question, in their words, as the title.
- Give the answer in the first sentence or two, then the steps.
- Use short numbered steps for tasks.
- Link to related articles.
Source: https://tirver.com/help/write-your-first-article
---
Source: https://tirver.com/help/add-knowledge-sources.md
# Add knowledge sources
> Upload documents or crawl your website so the AI agent has something to answer from.
The AI agent answers only from the sources you list. That is what keeps its answers accurate and lets it link to where an answer came from.
Open **AI agent**, then **Knowledge**. Only admins and owners can add or change sources.
## Upload documents
1. Select **Choose files to upload**.
2. Pick up to 10 files at a time.
3. Upload them.
Accepted types are Markdown (`.md`, `.markdown`, `.mdx`), plain text (`.txt`), HTML (`.html`, `.htm`), PDF and Word (`.docx`). Each file can be up to 25 MB and must not be empty. A file that fails a check is listed with the reason, and the others still upload.
## Crawl a website
1. In **Crawl a website**, enter a sitemap address, such as `https://example.com/sitemap.xml`, or the address of a single page.
2. Set **Most pages to index**. The default is 100 and the limit is 500.
3. Select **Start crawl**.
A sitemap crawls each page it lists. Tirver respects your robots.txt and crawls at a polite rate, then turns each page into text with its title and address.
## Source status
| Status | Meaning |
|---|---|
| Pending | Waiting its turn. |
| Indexing | Being read and prepared. |
| Indexed | Ready. The agent can answer from it. |
| Failed | Something went wrong. The reason is shown. |
| Skipped | Left out, for example blocked by robots.txt. |
For a website, the status summarises its pages, and a few failed or skipped pages are listed with their reasons.
## Keep sources fresh
- **Re-crawl** fetches a website again. Pages that have not changed are skipped, changed pages are updated, and pages that disappeared are removed.
- **Re-index** processes a source again without fetching it.
- **Refresh** updates the list.
- Delete a source, after confirming, to stop the agent using it.
The **Last synced** column shows when each source was last updated.
## Tips for good answers
- Prefer clear, current pages over long archives.
- Put each topic in its own page or section.
- Test with real customer questions. See [test the agent](https://tirver.com/help/test-the-agent.md).
Your help articles are for customers to read in the widget. To let the agent use their content too, point a crawl at your published help pages or upload the articles as documents.
Source: https://tirver.com/help/add-knowledge-sources
---
Source: https://tirver.com/help/billing-and-credits.md
# Billing, plans and AI credits
> How the Tirver suite and AI resolutions are billed, and where to see your balance.
Open **Settings, Billing** (owners and admins) to see the plan, seats and credits.
## The Tirver suite
The suite covers chat, inbox, help center, feedback, roadmap and changelog. It is offered on three billing periods: monthly, yearly and every 3 years. Switch the period at the top of the plan section to compare them.
Prices for each period have not been set yet, so the Billing page shows a placeholder. Nothing is charged until prices are published. A workspace with no paid plan shows **No paid plan is active on this workspace yet**.
## Seats
The seats line shows how many people are in the workspace and how many invitations are pending. A seat limit has not been set yet.
## AI credits
The AI agent is billed per resolved conversation, using credits. Handoffs to your team are free. The credits section shows your balance, how many credits were granted and how many were spent.
Credit packs, for buying more, come in three sizes. Their sizes and prices have not been set, so buying opens once they are decided. For how a resolution is counted, see [what counts as a resolution](https://tirver.com/help/what-counts-as-a-resolution.md).
## Redeem a code
Lifetime deal and promotional codes are applied under **Redeem a code**. See [redeem a code](https://tirver.com/help/redeem-a-code.md).
## Invoices
The Invoices section lists invoices once you have some. For now it reads **No invoices yet**.
## Cancel or change plan
To change your plan or cancel, write to [hello@tirver.com](mailto:hello@tirver.com) from your account email and we will help. Include the workspace name.
Source: https://tirver.com/help/billing-and-credits
---
Source: https://tirver.com/help/business-hours-and-away-message.md
# Business hours and the away message
> Tell Tirver when your team is online and what customers see when it is not.
Business hours tell Tirver when a person is likely to answer. They drive the away message and the AI agent's coverage.
## Set your hours
1. Open **Settings, Messenger, Hours**.
2. Choose your **Time zone**.
3. For each day, switch **Open** on and set **Opens** and **Closes** times. A day that is off is shown as Closed.
4. Select **Save**. Use **Discard** to go back to what was saved.
A closing time earlier than the opening time means the day runs past midnight.
## The away message
Under **When the team is away**, write the message customers see outside your hours, for example when you will be back.
## Let the AI agent keep answering
Switch on **Let the AI agent keep answering outside these hours** so customers still get help when nobody is online.
## How the AI agent uses your hours
In [the agent's settings](https://tirver.com/help/set-up-the-ai-agent.md) you can choose to answer at any time, or only outside business hours. With no days set, every hour counts as outside business hours.
Source: https://tirver.com/help/business-hours-and-away-message
---
Source: https://tirver.com/help/create-your-workspace.md
# Create your workspace
> Sign up, name your workspace and follow the Get started checklist.
A workspace is the home for one product or company: its inbox, articles, ideas and settings. Your team and your data live inside it.
## Sign up
1. Go to [app.tirver.com/signup](https://app.tirver.com/signup).
2. Enter your work email address.
3. Choose a password of at least 8 characters.
4. Enter a workspace name, for example your company name.
5. Create the workspace. You become its owner.
If you already have an account, [log in](https://app.tirver.com/login) instead.
## The Get started checklist
After signing up you land on **Get started**. It has five steps, and each one is checked against what is really set up, so a step is never marked done by mistake.
| Step | Done when |
|---|---|
| Create your workspace | Your workspace has a name. |
| Install the widget | You copied the install snippet, or a customer has written through the widget. |
| Add knowledge sources | At least one source is indexed or one help article is published. |
| Switch on the AI agent | The agent is turned on. |
| Invite your team | Someone else has joined or been invited. |
The page also shows roughly how many minutes are left, counting about three minutes a step, so a fresh workspace is ready in around fifteen minutes. You can leave and come back at any time.
Next: [install the widget](https://tirver.com/help/install-the-widget.md).
Source: https://tirver.com/help/create-your-workspace
---
Source: https://tirver.com/help/collections.md
# Organise articles in collections
> Group articles into collections so customers can browse them.
Collections are the groups customers see in the widget, for example Getting started or Billing.
## Create a collection
1. Open **Help center**.
2. In the **Collections** column, enter a name in **New collection**. For example Billing.
3. Add it.
The list shows each collection with the number of articles in it. **All articles** shows everything, and **No collection** shows articles you have not filed yet.
## Put an article in a collection
Open the article and choose the collection under **Article settings**.
## Rename or delete a collection
Select a collection, then use **Rename collection** or **Delete collection**.
## Filter the list
Within a collection, switch between **All**, **Published** and **Drafts** to find what needs attention. The table shows each article's status, views, how many readers found it helpful and when it was updated.
## What customers see
In the widget's Help tab, customers see collections with their article counts and can open one to browse. Collections with no published articles are not shown to them.
Source: https://tirver.com/help/collections
---
Source: https://tirver.com/help/reply-notes-and-tags.md
# Replies, notes, mentions and tags
> Answer customers, keep internal notes for the team and label conversations.
At the bottom of every conversation is the composer. It has two modes, and the difference matters.
## Reply or note
- **Reply** goes to the customer, in the widget.
- **Note** stays with your team. Customers never see it.
Switch between them with the message type control above the text box. The placeholder tells you which one you are in.
## Mention a teammate
In a note, type `@` and pick a teammate. Use notes to ask a colleague for help or leave context for whoever picks the conversation up next.
## Tags
Tags label conversations so you can find them later. In the details panel, type in **Add tag** and press enter. Existing tags are suggested as you type. Every tag also gets its own view in the inbox sidebar.
## Saved replies
Start a reply with `/` to pick from your [saved replies](https://tirver.com/help/saved-replies.md).
## The AI agent in a thread
AI answers appear in the thread marked as the AI agent, with links to the sources they used. If the agent hands a conversation over, a note records why. See [handoff rules](https://tirver.com/help/handoff-rules.md).
Source: https://tirver.com/help/reply-notes-and-tags
---
Source: https://tirver.com/help/the-roadmap.md
# The roadmap
> Show customers what is planned, in progress and shipped.
The roadmap is a board with three columns: **Planned**, **In progress** and **Shipped**. It is built from your feedback posts, so there is nothing separate to maintain.
## Put a post on the roadmap
Open a post in **Feedback** and set its status to Planned, In progress or Shipped. It appears in the matching column right away.
You can also open **Roadmap** and drag a post into a column. Dragging changes its status in Feedback, so the two always agree.
## Vote counts
Each card shows how many customers voted for it, so you can see demand at a glance.
## Filter
Use the filter above the board to narrow it, for example to one board of ideas.
## What customers see
Customers see the roadmap in the widget's Ideas tab, where they can also vote. The roadmap is public to your customers. Ideas that are In review or Declined do not appear on it.
## Requirements
The roadmap needs the Feedback module. See [switch modules on and off](https://tirver.com/help/switch-modules-on-and-off.md).
## When something ships
Publishing a [changelog entry](https://tirver.com/help/publish-a-changelog-entry.md) that links a post marks the post as shipped and moves it to the Shipped column.
Source: https://tirver.com/help/the-roadmap
---
Source: https://tirver.com/help/how-customers-find-articles.md
# How customers find your articles
> The widget Help tab, search, and the public feeds you can use on your own site.
## In the widget
When the Help center module is on, the widget has a **Help** tab. Customers can search your published articles or open a collection. Searching happens before they write to you, so many questions never reach the inbox.
If you have no published articles yet, the tab says **No articles yet**.
## On your own site
Every published article is also available from a public address, so you can show it on your own website or feed it to other tools. Replace `WORKSPACE` with your workspace address name.
| Address | Returns |
|---|---|
| `https://app.tirver.com/api/public/WORKSPACE/help` | JSON with your collections and published articles. Add `?q=` to search and `?collection=` to filter. |
| `https://app.tirver.com/api/public/WORKSPACE/help/ARTICLE` | One article as JSON. |
| `https://app.tirver.com/api/public/WORKSPACE/help/ARTICLE.md` | The same article as Markdown. |
These addresses return only published articles and are cached for a short time. They answer with an error when the Help center module is off.
## For the AI agent
Articles are read by customers. The AI agent answers from [knowledge sources](https://tirver.com/help/add-knowledge-sources.md), so add your articles there as documents, or crawl a page that shows them.
Source: https://tirver.com/help/how-customers-find-articles
---
Source: https://tirver.com/help/how-the-ai-agent-answers.md
# How the AI agent answers
> What the agent looks at, what it says, and when it steps back.
Understanding the steps helps you set it up well and trust what it says.
## What happens to a customer message
1. A customer writes in the widget.
2. If the agent is on, nobody is assigned and the conversation has not been handed over, the agent considers it. If you chose to answer only outside business hours, it also checks the hours.
3. It checks your [handoff rules](https://tirver.com/help/handoff-rules.md). If the customer asks for a person, or a handoff phrase matches, the conversation goes to your team.
4. Otherwise it looks across your knowledge sources, using the recent messages in the conversation, and writes an answer in the tone you chose.
5. The reply appears in the widget with links to the sources it used.
6. If no source supports the answer and **No source answers the question** is on, the conversation is handed over instead.
## Citations
Each answer lists the pages or documents it drew on. Customers can open them, and your team can see them in the thread.
## What it will not do
- Answer from outside your sources. It does not use the wider internet.
- Discuss topics you excluded, or go beyond topics you limited it to.
- Reply while a person is assigned to the conversation.
- Keep going after a handoff.
## When something goes wrong
If the AI service has a problem, the conversation is handed to your team with a note, so no customer is left without a reply. If many questions arrive at once, the customer sees that their message is saved and that you will reply shortly.
## Languages
The agent answers from your sources, so it works best when they are in the language your customers write in. Answers are only as good as the material behind them, so add sources in the languages your customers use. Tirver does not translate answers for you.
Related: [set up the AI agent](https://tirver.com/help/set-up-the-ai-agent.md), [what counts as a resolution](https://tirver.com/help/what-counts-as-a-resolution.md).
Source: https://tirver.com/help/how-the-ai-agent-answers
---
Source: https://tirver.com/help/install-the-widget.md
# Install the widget
> Add the Tirver messenger to your product with one script tag.
The widget is a small launcher that opens the messenger. Once it loads, customers can write to you, search your help articles and vote on ideas, depending on which modules are on.
## Add the script
1. In Tirver open **Settings, Messenger, Install**.
2. Choose your language: HTML, React, Vue or Next.js.
3. Select **Copy snippet**.
4. Paste it before the closing `body` tag on every page where the widget should appear.
The HTML version is a single tag. It carries your public widget id, which is safe to show in page source.
```html
```
The React, Vue and Next.js snippets do the same thing from a component, so the script loads once and is removed when the component goes away.
## Check that it works
1. Open your product in a new tab.
2. Look for the launcher in the bottom corner. Its colour and side come from [your widget settings](https://tirver.com/help/customize-the-widget.md).
3. Open it and send a test message.
4. In Tirver, open the inbox. The message appears under **Unassigned**, and the install page shows **Receiving data**.
Until the first visitor arrives, the install page says **Waiting for the first visitor**.
## Control the widget from code
The script adds a `Tirver` object to the page.
```js
Tirver.open(); // open the messenger
Tirver.close(); // close it
Tirver.toggle(); // open or close
Tirver.shutdown(); // remove the widget, for example on sign out
```
## If the launcher does not appear
- Check that the script is on the page and the widget id is yours.
- If you set [allowed domains](https://tirver.com/help/allowed-domains.md), the page's domain must be on the list.
- Make sure a content security policy on your site allows scripts and frames from app.tirver.com.
Next: [identify signed-in customers](https://tirver.com/help/identify-signed-in-customers.md) so conversations follow them across devices.
Source: https://tirver.com/help/install-the-widget
---
Source: https://tirver.com/help/publish-a-changelog-entry.md
# Publish a changelog entry
> Announce what shipped, link the ideas behind it and tell the people who asked.
Your changelog is a list of release notes your customers see in the widget's News tab and on your changelog page.
## Write an entry
1. Open **Changelog** and select **New entry**.
2. Give it a title in **Entry title**.
3. Add tags such as `New` or `Integrations`, separated by commas.
4. Write the notes under **Body in Markdown**. Check them in the **Preview** tab.
5. Under **Linked feedback**, pick the feedback posts this release delivers.
Entries start as drafts, visible only to your team.
## Publish
Select **Publish**. Three things happen:
- The entry appears on your changelog and in the widget.
- Every linked post is marked **Shipped** and moves to the Shipped column of your roadmap.
- A notification is queued for each customer who voted for a linked post.
The notification is queued but not emailed yet, so customers do not receive an email for now.
## Take it back
You can move a published entry back to draft. The entry disappears from the widget and the changelog page. Linked posts stay shipped.
## Public feeds
Published entries are also available as JSON, without a key, at `https://app.tirver.com/api/public/WORKSPACE/changelog`, with `WORKSPACE` replaced by your workspace address name. With an API key you can read entries, drafts included, at `/api/v1/changelog`. See [changelog entries](https://tirver.com/help/api/changelog-entries.md).
## Writing good release notes
- Lead with what changed for the customer, not how you built it.
- Keep each entry about one change.
- Link to the help article that explains it.
Source: https://tirver.com/help/publish-a-changelog-entry
---
Source: https://tirver.com/help/redeem-a-code.md
# Redeem a code
> Apply a lifetime deal or promotional code to your workspace.
If you bought a lifetime deal or were given a promotional code, apply it to your workspace.
1. Sign in as the workspace owner. Only an owner can redeem codes.
2. Open **Settings, Billing**.
3. In **Redeem a code**, paste your code.
4. Select **Redeem**.
When it works, the page confirms that your workspace now has the lifetime plan. The plan section changes to **Lifetime plan** with the note that it was redeemed with a code and does not renew.
## If it does not work
| Message | What it means |
|---|---|
| That code is not valid | Check for typos or extra spaces and try again. |
| That code has already been used | Each code works once. |
| This workspace already has a lifetime plan | A workspace can hold one lifetime plan. |
| Only an owner can redeem codes | Ask an owner of the workspace to do it. |
Still stuck? Write to [hello@tirver.com](mailto:hello@tirver.com) with the code and the workspace name.
Source: https://tirver.com/help/redeem-a-code
---
Source: https://tirver.com/help/saved-replies.md
# Saved replies
> Insert a prepared answer from the reply box in one keystroke.
A saved reply is a prepared message with a name and an optional shortcut. Use them for answers you give again and again, such as how to reset a password.
## Use a saved reply
1. Open a conversation and make sure the composer is in **Reply** mode.
2. Type `/`. A list of saved replies opens.
3. Keep typing a name or shortcut to narrow the list. For example `/thanks`.
4. Pick one. Its text fills the box so you can edit it before sending.
Saved replies are shared by the whole workspace. Tirver has no screen yet for creating or editing them, so the list shows only the replies already set up for your workspace.
## What a saved reply holds
| Field | Meaning |
|---|---|
| Name | How the reply appears in the list. |
| Shortcut | An optional short word to find it quickly. |
| Body | The message text. |
Saved replies are only offered in replies, not in internal notes.
Source: https://tirver.com/help/saved-replies
---
Source: https://tirver.com/help/article-ratings.md
# Article ratings
> See which articles helped and which need work.
At the end of an article, customers can say whether it helped. Those ratings tell you where to spend your writing time.
## How a customer rates
Each identified customer gives one rating per article, helpful or not helpful. If they rate again, the new rating replaces the old one. Ratings need an [identified customer](https://tirver.com/help/identify-signed-in-customers.md), which is how Tirver keeps one vote per person.
## Where you see ratings
- In **Help center**, the **Found helpful** column shows the share of readers who rated an article helpful.
- Inside an article, the editor shows the same figures.
- In **Reports**, the **Article ratings** section lists helpful and not helpful counts for the range you pick, and the summary shows how many articles were rated helpful.
## Using the figures
An article with many views and a low helpful share is the best one to rewrite first. If customers of the AI agent are handed over on the same topic, add the missing answer to the article and to your [knowledge sources](https://tirver.com/help/add-knowledge-sources.md).
Source: https://tirver.com/help/article-ratings
---
Source: https://tirver.com/help/handoff-rules.md
# Handoff rules
> Decide when the AI agent passes a conversation to a person.
A good agent knows when to stop. Handoff rules tell it when a person should take over.
Open **AI agent**, then **Behavior**, and find **Hand over to a person when**. Only admins and owners can change them.
## The rules
| Rule | When it applies |
|---|---|
| The customer asks for one | The customer asks to talk to a person, for example "can I speak to a human". On by default. |
| No source answers the question | The agent's answer cites no source, so it is not trusted. On by default. |
| The topic is a billing dispute or refund | The customer mentions a refund, a chargeback or being charged twice. On by default. |
## Your own phrases
Under **Always hand over when the customer writes**, add phrases, one per line. If a message contains one, the conversation goes straight to your team. For example `legal` or `enterprise plan`. You can add up to 20 phrases of up to 80 characters each.
## What the customer sees
Write your own text under **Message to the customer when handing over**, or leave it empty to use the default.
> I am passing this to our team. Someone will reply here as soon as they can.
## What your team sees
The conversation stays in the inbox. A private note records the reason, for example that the customer asked for a person, or that no source answered. The agent then stays out of that conversation, so your team can reply without being interrupted.
A handed-over conversation is not billed as an AI resolution. See [what counts as a resolution](https://tirver.com/help/what-counts-as-a-resolution.md).
Source: https://tirver.com/help/handoff-rules
---
Source: https://tirver.com/help/identify-signed-in-customers.md
# Identify signed-in customers
> Tell the widget who is signed in, with a hash from your server, so nobody can read another customer's conversations.
Without identification, the widget treats each browser as an anonymous visitor. When you pass who the customer is, conversations follow them across devices and your team sees their name and email beside every chat.
To stop one customer pretending to be another, the identity is signed on your server with a secret only you hold.
## 1. Generate your identity secret
1. Open **Settings, Messenger, Install**.
2. In **Identify signed-in customers**, select **Generate secret**.
3. Copy the secret straight away. It is shown only once.
Keep it on your server. Never put it in browser code. You can **Rotate secret** at any time, but hashes made with the old secret stop working immediately, so deploy the new secret first.
## 2. Sign the customer id on your server
The hash is the HMAC-SHA256 of the customer id, written as lowercase hex.
```js
// Node.js
import { createHmac } from 'node:crypto';
const hash = createHmac('sha256', process.env.TIRVER_IDENTITY_SECRET)
.update(String(user.id))
.digest('hex');
```
```python
# Python
import hashlib, hmac, os
user_hash = hmac.new(
os.environ["TIRVER_IDENTITY_SECRET"].encode(),
str(user.id).encode(),
hashlib.sha256,
).hexdigest()
```
## 3. Pass it to the widget
Set the details before the script loads, or call `Tirver.identify` after sign-in.
```html
```
```js
// after the customer signs in
Tirver.identify({ user_id: user.id, user_hash: hashFromServer, email: user.email, name: user.name });
```
When the customer signs out, call `Tirver.shutdown()` so the next person on that browser starts fresh.
## Require a valid hash
Turn on **Require a valid hash before showing past conversations**. The switch is available once a secret exists. With it on, a customer whose hash does not match sees no history. Turn it on as soon as every page that loads the widget passes a hash.
Source: https://tirver.com/help/identify-signed-in-customers
---
Source: https://tirver.com/help/snooze-and-close.md
# Snooze, close and reopen conversations
> Pause a conversation until later, finish it, or bring it back.
Use the buttons in the thread header to move a conversation through its life.
## Snooze
Snooze hides a conversation until a time you choose. Select **Snooze**, then pick **1 hour**, **Tomorrow** or **Next week**. The conversation moves to the **Snoozed** view and comes back when the time is up.
Snooze is useful when you are waiting on the customer or on a colleague.
## Close
Select **Close** when the customer is helped. The conversation moves to **Closed**. Closing does not send the customer a message.
A conversation the AI agent answered and that nobody else touched, then closed, can count as an [AI resolution](https://tirver.com/help/what-counts-as-a-resolution.md).
## Reopen
Select **Reopen** on a closed conversation to make it open again.
Source: https://tirver.com/help/snooze-and-close
---
Source: https://tirver.com/help/your-profile.md
# Your profile and account menu
> Set your name and picture, switch between light and dark, and log out.
Everyone in the workspace, whatever their role, can edit their own profile.
## Your name and picture
1. Open **Settings, Profile**.
2. Change your **Display name**. Customers and teammates see it on your replies.
3. Choose a profile picture. PNG, JPEG, WebP or GIF, up to 5 MB. It is cropped to a centred square.
4. Remove the picture at any time with **Remove picture**. Your initials show instead.
Your **Email** is shown for reference.
## The account menu
At the bottom of the sidebar, your name opens the account menu. From there you can:
- Open your profile.
- Switch between light and dark colour mode.
- Log out.
The sidebar also shows your remaining AI credits in a compact form, and you can collapse the sidebar to icons to gain room.
Source: https://tirver.com/help/your-profile
---
Source: https://tirver.com/help/conversation-reports.md
# Conversation volume and response times
> Read the Reports page for conversation volume, AI resolutions and article ratings.
Open **Reports** in the app to see how support is going. Pick a date range with the range picker.
## Summary figures
| Figure | Meaning |
|---|---|
| Conversations | Conversations started in the range. |
| Resolved by AI | Conversations where the AI agent recorded a resolution. |
| Median first reply by a person | How long customers waited for a human reply, typically. |
| Articles rated helpful | Helpful ratings on help articles. |
## Charts and tables
**Conversations per day** charts volume over the range, and **By week** gives a table with conversations, AI resolutions and median first reply per week. **Article ratings** lists helpful and not helpful counts.
Days are in UTC.
## Empty ranges
Until customers use your widget there is nothing to show. A longer range may help. The page explains when no data exists yet.
## About resolutions
The AI resolution figure follows the working rule described in [what counts as a resolution](https://tirver.com/help/what-counts-as-a-resolution.md). That rule is not final.
This page needs the Reports module. See [switch modules on and off](https://tirver.com/help/switch-modules-on-and-off.md).
Source: https://tirver.com/help/conversation-reports
---
Source: https://tirver.com/help/customer-details.md
# Customer details and history
> See who you are talking to and what they asked before.
The details panel sits to the right of every conversation. It gives you context without leaving the thread.
## What it shows
| Section | Contents |
|---|---|
| Customer | Name, email, when they were last seen and when they became a customer. |
| User id | The id your product passed when you [identified the customer](https://tirver.com/help/identify-signed-in-customers.md). |
| Assignee and tags | Who owns the conversation and its labels. |
| Summary | A short extract of the conversation so far. |
| Other conversations | Earlier conversations with the same customer. |
| Feedback | Feedback posts linked to this conversation. |
Each section is a collapsible group, so you can keep open the ones you use.
## Anonymous visitors
If you do not identify customers, you will see little more than the conversation itself. [Identify signed-in customers](https://tirver.com/help/identify-signed-in-customers.md) to get names and emails automatically.
## Hide the panel
Select the panel icon in the thread header to collapse the details panel. See [resize and collapse inbox panels](https://tirver.com/help/resize-and-collapse-inbox-panels.md).
Source: https://tirver.com/help/customer-details
---
Source: https://tirver.com/help/allowed-domains.md
# Limit the widget to your domains
> Choose which websites may load your widget.
By default the widget loads on any site that has your snippet. Allowed domains let you restrict that to the sites you own, so nobody can copy your snippet onto another page.
## Add a domain
1. Open **Settings, Messenger, Install**.
2. In **Allowed domains**, type a domain such as `app.example.com` or `staging.example.com`.
3. Select **Add domain**.
Add every domain where the widget should run, including staging and preview sites you test on.
## Remove a domain
Select **Remove** beside it in the list.
## Leave it empty while you set up
With no domains listed, the widget loads on any site. That is convenient while you are getting started. Add your domains before you go live.
If the widget stays invisible on a page, the page's domain is probably missing from the list.
Source: https://tirver.com/help/allowed-domains
---
Source: https://tirver.com/help/what-counts-as-a-resolution.md
# What counts as a resolution
> How Tirver decides that the AI agent resolved a conversation, and what it costs.
The AI agent is billed per resolution, not per message and not per handoff. This article explains how a resolution is counted today.
## The working rule
A conversation counts as resolved by the AI agent when all of these are true:
1. The AI agent replied at least once.
2. No person on your team replied.
3. The conversation was not handed over to a person.
4. The conversation is now closed.
Each conversation is counted once, however many messages it took.
## What does not count
- A conversation your team answered, even if the AI agent helped first.
- A conversation handed over, for any reason.
- A conversation still open.
- Replies in the **Test the agent** box on the AI agent page. They never cost credits.
## What a resolution costs
A resolution uses AI credits from your balance. See [billing and credits](https://tirver.com/help/billing-and-credits.md) and [AI usage and credits](https://tirver.com/help/ai-usage-and-credits.md).
## This rule may change
The rule above is the one in use now, and it is not final. Changes are announced in the [changelog](https://tirver.com/changelog.md). The Reports page notes the same.
Source: https://tirver.com/help/what-counts-as-a-resolution
---
Source: https://tirver.com/help/invite-your-team.md
# Invite your team
> Invite teammates as admins or agents and manage who has access.
Your team answers conversations, writes articles and runs the AI agent together. People join your workspace by invitation.
## Invite someone
1. Open **Settings, Team**.
2. Under **Invite a teammate**, enter their email address.
3. Choose a role, **Admin** or **Agent**. You can invite owners only by promoting someone after they join.
4. Send the invitation.
The invitation appears in the list with its status. It expires after 7 days; an expired invitation is marked **Invite expired**, and you can remove it and invite again.
If email is not connected for your workspace, Tirver shows an invitation link instead. Copy it and share it with your teammate yourself.
## Accept an invitation
The person opens the link, signs in or creates an account with the invited email address, and accepts. They then see the workspace.
## Change a role or remove someone
In the members list, change the role from the dropdown or select **Remove**. Admins and owners can do this. A workspace always needs at least one owner, so make someone else an owner before you leave or demote the last one.
## Leave a workspace
Select **Leave workspace** on the Team page. You lose access until someone invites you again.
See [team roles](https://tirver.com/help/team-roles.md) for what each role can do.
Source: https://tirver.com/help/invite-your-team
---
Source: https://tirver.com/help/resize-and-collapse-inbox-panels.md
# Resize and collapse inbox panels
> Shape the five-column inbox to your screen, with the mouse or the keyboard.
The inbox has five columns: the app rail, the views sidebar, the conversation list, the thread and the details panel. You can adjust most of them.
## Resize
Drag the edge between two panels. The thread takes the remaining space and never gets narrower than 320 pixels.
| Panel | Narrowest | Widest | Default |
|---|---|---|---|
| Views | 180 | 320 | 220 |
| Conversation list | 260 | 480 | 320 |
| Details | 260 | 440 | 300 |
## Use the keyboard
Focus an edge with Tab. Press the left or right arrow to move it 16 pixels at a time. Double-click an edge to reset it to the default.
## Collapse
The list icon in the thread header hides the views sidebar. The panel icon hides the details panel. Both buttons report whether they are expanded to screen readers.
## Small screens
Below 960 pixels wide only the conversation list shows. Opening a conversation takes you to the thread at full width, with a back button to return to the list.
Source: https://tirver.com/help/resize-and-collapse-inbox-panels
---
Source: https://tirver.com/help/test-the-agent.md
# Test the AI agent
> Try questions on the agent before customers do, without using credits.
Test before you switch the agent on for everyone. Testing does not use credits.
1. Open **AI agent**.
2. Find **Test the agent**.
3. Type a question a customer might ask, then send it.
The answer comes from your saved sources, the same way a customer's answer would.
## What to try
- Questions your support team gets every week.
- Questions you expect the sources to answer, and a few they should not.
- A request to talk to a person, to check your [handoff rules](https://tirver.com/help/handoff-rules.md).
## If the answer is wrong or missing
1. Check **Knowledge** for the right source and make sure it is **Indexed**.
2. Add the missing page or document.
3. Adjust the [extra instructions](https://tirver.com/help/set-up-the-ai-agent.md) if the tone or scope is off.
4. Test again.
Only admins can test the agent.
Source: https://tirver.com/help/test-the-agent
---
Source: https://tirver.com/help/ai-usage-and-credits.md
# AI usage and credits
> Read the usage page and see how many credits are left.
The agent's cost follows its resolutions. The **Usage** tab under **AI agent** shows where you stand.
## What the page shows
| Figure | Meaning |
|---|---|
| Credits left | What you can still spend. |
| Used this month | Credits spent on resolutions this month. |
| Resolved by AI this month | Conversations the agent resolved. |
| Handed to the team this month | Conversations the agent passed to a person. |
| Resolution rate | The share the agent resolved without help. |
A chart shows resolutions per day for the last 30 days, and a table gives usage by month with resolved, handed off and credits used.
## Credits
Each resolution uses credits. Handoffs do not cost anything. When your balance is low, you can **Buy extra credits**. Credit pack sizes and prices have not been set yet, so buying opens later. See [billing and credits](https://tirver.com/help/billing-and-credits.md).
## Reading the numbers
A high resolution rate usually means your sources cover your questions well. A high handoff count points to topics your sources miss. Open the handed-over conversations, then add what was missing under **Knowledge**.
Source: https://tirver.com/help/ai-usage-and-credits
---
Source: https://tirver.com/help/switch-modules-on-and-off.md
# Switch modules on and off
> Turn Tirver features on or off for your workspace and widget.
You do not have to use everything. Each module has a switch under **Settings, Modules**, and only admins and owners can change it.
| Module | What the switch controls |
|---|---|
| Live chat | The messenger widget and the shared inbox. |
| AI agent | Answers and guidance from the agent. |
| Help center | Articles and search in the widget. |
| Feedback | Boards for ideas, votes and comments. |
| Roadmap | The public view of planned, in progress and shipped ideas. |
| Changelog | Release notes in the widget and on your changelog. |
| Reports | The Reports page. |
## What happens when a module is off
An off module disappears from your team navigation and from the widget. Its public pages are not served either. Nothing is deleted, so switching it back on restores everything.
## Roadmap needs Feedback
The roadmap is built from feedback posts. Switching Feedback off also switches Roadmap off, and switching Roadmap on turns Feedback on.
## Widget tabs follow modules
A widget tab shows only when its module is on: Messages needs Live chat, Help needs Help center, Ideas needs Feedback and News needs Changelog. See [customize the widget](https://tirver.com/help/customize-the-widget.md).
Source: https://tirver.com/help/switch-modules-on-and-off
---
Source: https://tirver.com/help/api.md
# Introduction
> What the Tirver REST API is for, the base address and a first request.
The Tirver REST API lets your own code work with your workspace: read conversations and reply to them, look up customers, read and draft help articles, file feedback, read the changelog and ask the AI agent a question. It is for servers and scripts you write. To let an AI assistant such as Claude work with your workspace, use the [MCP server](https://tirver.com/help/mcp.md) instead. Both use the same API key.
## Base address
All requests go to one address and use HTTPS.
```
https://app.tirver.com/api/v1
```
Every endpoint on these pages is shown with its full path, for example `/api/v1/conversations`, so you can add it after `https://app.tirver.com`.
An OpenAPI 3.1 description of every endpoint is published at [https://app.tirver.com/api/v1/openapi.json](https://app.tirver.com/api/v1/openapi.json). It needs no key.
## How it behaves
- Requests and responses are JSON. Send `Content-Type: application/json` with a body.
- Every request is made on behalf of one workspace, the workspace that owns the API key.
- Field names are `snake_case`. Times are ISO 8601 in UTC, for example `2026-11-14T09:02:00.000Z`. Ids are strings: treat them as opaque.
- Lists are paged with a cursor. See [pagination](https://tirver.com/help/api/pagination.md).
- Each key can make 120 requests a minute. See [rate limits](https://tirver.com/help/api/rate-limits.md).
- No CORS headers are sent, so call the API from a server, not from a browser.
## Your first request
Create an API key as described in [authentication](https://tirver.com/help/api/authentication.md), then list your open conversations.
**curl**
```bash
curl "https://app.tirver.com/api/v1/conversations?status=open&limit=5" \
-H "Authorization: Bearer $TIRVER_API_KEY"
```
**JavaScript**
```js
const res = await fetch('https://app.tirver.com/api/v1/conversations?status=open&limit=5', {
headers: { Authorization: `Bearer ${process.env.TIRVER_API_KEY}` },
});
if (!res.ok) throw new Error(`Tirver ${res.status}`);
const { data, next_cursor, has_more } = await res.json();
console.log(data.length, 'open conversations', has_more ? next_cursor : 'no more');
```
**Python**
```python
import os, requests
res = requests.get(
"https://app.tirver.com/api/v1/conversations",
params={"status": "open", "limit": 5},
headers={"Authorization": f"Bearer {os.environ['TIRVER_API_KEY']}"},
timeout=10,
)
res.raise_for_status()
body = res.json()
print(len(body["data"]), "open conversations", body["next_cursor"])
```
A successful response looks like this.
```json
{
"data": [
{
"id": "8c1f0d52",
"status": "open",
"customer_id": "3b7a91e4",
"assignee_id": null,
"handled_by": "ai",
"channel": "widget",
"subject": "Cannot log in",
"tags": ["bug"],
"snoozed_until": null,
"last_message_at": "2026-11-14T09:05:00.000Z",
"created_at": "2026-11-14T09:02:00.000Z",
"updated_at": "2026-11-14T09:05:00.000Z"
}
],
"next_cursor": null,
"has_more": false
}
```
## Other endpoints
Besides the resource pages, the API has a few small endpoints.
| Endpoint | Scope | What it does |
|---|---|---|
| `GET /api/v1/workspace` | none | Your workspace, and the name, prefix and scopes of the key you used. |
| `POST /api/v1/ask` | `ai:ask` | Ask the AI agent a question. Returns `answer` and `citations`. Stores nothing and uses no credits. Limited to 10 a minute per key. |
| `GET /api/v1/credits` | `credits:read` | `balance`, `granted` and `spent`, the same numbers as Settings, Billing. |
| `GET /api/v1/knowledge/sources` | `knowledge:read` | The files, pages and sitemaps the AI agent learns from, with their status. Read only. |
| `GET /api/v1/search` | `help-center:read` | Keyword search over published articles. See [articles](https://tirver.com/help/api/articles.md). |
## What the API does not do
You cannot create or update customers, assign or snooze conversations, publish anything, change knowledge sources, move roadmap items or manage webhooks, and nothing can be edited or deleted. The only writes are replies and notes, closing a conversation, article drafts and feedback posts.
## Where to go next
1. [Authentication](https://tirver.com/help/api/authentication.md) explains keys and how to keep them safe.
2. [Permissions](https://tirver.com/help/api/permissions.md) lists the scopes a key can hold.
3. [Errors](https://tirver.com/help/api/errors.md) and [rate limits](https://tirver.com/help/api/rate-limits.md) tell you how to handle trouble.
4. The resource pages list every endpoint: [conversations](https://tirver.com/help/api/conversations.md), [customers](https://tirver.com/help/api/customers.md), [articles](https://tirver.com/help/api/articles.md), [feedback posts](https://tirver.com/help/api/feedback-posts.md) and [changelog entries](https://tirver.com/help/api/changelog-entries.md).
Source: https://tirver.com/help/api
---
Source: https://tirver.com/help/api/authentication.md
# Authentication
> Create an API key and send it as a bearer token.
Every request carries a secret API key in the `Authorization` header. A key belongs to one workspace and works only for that workspace. The same key works for the REST API and the [MCP server](https://tirver.com/help/mcp.md).
## Create a key
Only owners and admins can create keys.
1. Sign in to [app.tirver.com](https://app.tirver.com).
2. Open **Settings, API keys** and create a key.
3. Give it a name, choose its scopes and choose when it expires: 30 days, 90 days, 1 year or never. See [permissions](https://tirver.com/help/api/permissions.md).
4. Copy the key straight away. It is shown once. Afterwards only a short prefix, such as `trv_live_a1b2c3`, is shown so you can tell keys apart.
Tirver stores only a fingerprint of the key, so a lost key cannot be recovered. Create a new one and revoke the old one. Revoking takes effect at once. When you create a key, Tirver emails you a notice with the key name and the time, never the key itself.
## Send the key
Put the key in the `Authorization` header as a bearer token. Keys start with `trv_live_`.
**curl**
```bash
curl https://app.tirver.com/api/v1/workspace \
-H "Authorization: Bearer $TIRVER_API_KEY"
```
**JavaScript**
```js
const headers = { Authorization: `Bearer ${process.env.TIRVER_API_KEY}` };
const res = await fetch('https://app.tirver.com/api/v1/workspace', { headers });
```
**Python**
```python
headers = {"Authorization": f"Bearer {os.environ['TIRVER_API_KEY']}"}
res = requests.get("https://app.tirver.com/api/v1/workspace", headers=headers, timeout=10)
```
`GET /api/v1/workspace` is a good first call: it needs a valid key but no scope, and it shows the name, prefix and scopes of the key you used.
A request with no key gets `401` with the code `missing_api_key`. An unknown, revoked or expired key gets `401` with `invalid_api_key`. A key without the scope an endpoint needs gets `403` with `insufficient_scope`. See [errors](https://tirver.com/help/api/errors.md).
## Keep keys safe
- Keep keys on your server. Never put one in a web page, a mobile app or a public repository.
- Load keys from environment variables or a secret manager, not from source code.
- Use one key per integration, so you can revoke one without breaking the others.
- Give each key only the scopes it needs. Most reporting scripts need read scopes only.
- Set an expiry for keys that are only needed for a while, and revoke keys you no longer use. Revoke a key at once if you think it leaked.
## Not for the widget
The widget does not use API keys. It identifies customers with a hash signed by your identity secret. See [identify signed-in customers](https://tirver.com/help/identify-signed-in-customers.md).
Source: https://tirver.com/help/api/authentication
---
Source: https://tirver.com/help/api/permissions.md
# Permissions
> The scopes an API key can hold and what each one allows.
Each API key has an explicit list of scopes, chosen when you create it. Nothing is implied: a write scope does not include the matching read scope, so a key that replies to conversations and also reads them needs both `conversations:write` and `conversations:read`.
| Scope | Allows |
|---|---|
| `conversations:read` | List and read conversations and messages, internal notes included. |
| `customers:read` | List and read customers, including their email address. |
| `help-center:read` | List and read collections and articles (drafts too), and search published articles. |
| `feedback:read` | List and read boards, posts and comments. |
| `changelog:read` | List and read changelog entries. Drafts only when you ask for them. |
| `knowledge:read` | List the knowledge sources the AI agent learns from. |
| `credits:read` | Read the AI credit balance. |
| `ai:ask` | Ask the AI agent a question. |
| `conversations:write` | Reply to customers, add internal notes and close conversations. |
| `help-center:write` | Create article drafts. Never publishes. |
| `feedback:write` | Create feedback posts. |
## What each endpoint needs
| Endpoint | Scope |
|---|---|
| `GET /api/v1/workspace` | none, a valid key is enough |
| `GET /api/v1/conversations`, `/conversations/{id}`, `/conversations/{id}/messages` | `conversations:read` |
| `POST /api/v1/conversations/{id}/messages`, `/conversations/{id}/close` | `conversations:write` |
| `GET /api/v1/customers`, `/customers/{id}` | `customers:read` |
| `GET /api/v1/help-center/collections`, `/help-center/articles`, `/help-center/articles/{id}`, `/search` | `help-center:read` |
| `POST /api/v1/help-center/articles` | `help-center:write` |
| `GET /api/v1/feedback/boards`, `/feedback/posts`, `/feedback/posts/{id}` | `feedback:read` |
| `POST /api/v1/feedback/posts` | `feedback:write` |
| `GET /api/v1/changelog`, `/changelog/{id}` | `changelog:read` |
| `GET /api/v1/knowledge/sources`, `/knowledge/sources/{id}` | `knowledge:read` |
| `POST /api/v1/ask` | `ai:ask` |
| `GET /api/v1/credits` | `credits:read` |
## Two things to remember
- A key with `conversations:write` can send a message that customers read. When an action might reach a customer, the endpoint page says so. Give that scope only to code you trust.
- Articles you create through the API are always drafts. A person publishes them in Tirver.
If a key lacks the scope an endpoint needs, the API answers `403` with the code `insufficient_scope`, and the message names the scope. If a workspace has switched a module off, such as the help center, its endpoints answer `404` with `module_disabled`. See [errors](https://tirver.com/help/api/errors.md).
Source: https://tirver.com/help/api/permissions
---
Source: https://tirver.com/help/api/errors.md
# Errors
> The error format, status codes and how to handle them.
The API uses ordinary HTTP status codes. A response in the 200s means success. Anything else, including `401` and `500`, carries a JSON body that explains what went wrong.
## Error format
```json
{
"error": {
"code": "validation_failed",
"message": "Must be one of: reply, note.",
"fields": { "type": "Must be one of: reply, note." },
"request_id": "req_3f9c0a1b22d4e5f6"
}
}
```
| Field | Meaning |
|---|---|
| `code` | A short, stable word for the problem. Branch on this, not on the message. |
| `message` | A sentence for people. It can change, so do not match on it. |
| `fields` | Present on validation errors. Maps each field to what is wrong with it. |
| `request_id` | Identifies the request. It is also in the `X-Request-Id` response header. Include it when you write to support. |
## Status codes
| Status | Code | What it means |
|---|---|---|
| 400 | `invalid_json` | The body is not valid JSON. |
| 401 | `missing_api_key` | There is no `Authorization` header. |
| 401 | `invalid_api_key` | The key is unknown, revoked or expired. A `WWW-Authenticate: Bearer` header is sent. |
| 403 | `insufficient_scope` | The key is valid but lacks the scope. The message names it. See [permissions](https://tirver.com/help/api/permissions.md). |
| 404 | `not_found` | No such endpoint or record. Ids from another workspace also give this. |
| 404 | `module_disabled` | The workspace has switched that module off. |
| 405 | `method_not_allowed` | The path exists but not for this method. The `Allow` header lists the methods that work. |
| 409 | `conflict` | A duplicate slug, or the conversation already has a feedback post. |
| 413 | `payload_too_large` | The body is over 256 KB. |
| 422 | `validation_failed` | A query parameter or body field is wrong. See `fields`. Unknown body fields are rejected. Unknown query parameters are ignored. |
| 429 | `rate_limited` | Too many requests, or the AI agent is busy. Wait for the time in `Retry-After`. See [rate limits](https://tirver.com/help/api/rate-limits.md). |
| 500 | `internal_error` | Something broke on our side. Retry with backoff. |
| 502 | `upstream_error` | The AI backend could not answer an `ask` request. Retry with backoff. |
## Handling errors
Retry only what can succeed on a second try: `429`, `500` and `502`. Do not retry other `4xx` errors, because the same request will fail the same way.
**JavaScript**
```js
async function tirver(path, init = {}) {
for (let attempt = 0; attempt < 5; attempt++) {
const res = await fetch(`https://app.tirver.com/api/v1${path}`, {
...init,
headers: { Authorization: `Bearer ${process.env.TIRVER_API_KEY}`, 'Content-Type': 'application/json', ...init.headers },
});
if (res.ok) return res.json();
const retryable = res.status === 429 || res.status >= 500;
if (!retryable || attempt === 4) {
const { error } = await res.json().catch(() => ({ error: { code: 'unknown', message: res.statusText } }));
throw Object.assign(new Error(error.message), { status: res.status, code: error.code, requestId: error.request_id });
}
const wait = Number(res.headers.get('Retry-After')) || 2 ** attempt;
await new Promise((r) => setTimeout(r, wait * 1000));
}
}
const open = await tirver('/conversations?status=open');
```
**Python**
```python
import os, time, requests
def tirver(method, path, **kwargs):
for attempt in range(5):
res = requests.request(
method,
f"https://app.tirver.com/api/v1{path}",
headers={"Authorization": f"Bearer {os.environ['TIRVER_API_KEY']}"},
timeout=10,
**kwargs,
)
if res.ok:
return res.json()
retryable = res.status_code == 429 or res.status_code >= 500
if not retryable or attempt == 4:
res.raise_for_status()
time.sleep(float(res.headers.get("Retry-After", 2 ** attempt)))
open_conversations = tirver("GET", "/conversations", params={"status": "open"})
```
When you contact support about an error, include the `request_id`, the time of the request and the path. Never include your key.
Source: https://tirver.com/help/api/errors
---
Source: https://tirver.com/help/api/pagination.md
# Pagination
> Walk through long lists with a cursor.
List endpoints return a page of results and a cursor for the next page.
## Parameters
| Parameter | Type | What it does |
|---|---|---|
| `limit` | integer | Page size, 1 to 100. Defaults to 25. |
| `cursor` | string | The `next_cursor` from the previous response. Leave it out for the first page. |
## Response
```json
{
"data": [ { "id": "8c1f0d52" }, { "id": "5d2e7a10" } ],
"next_cursor": "WzE3OTQ...",
"has_more": true
}
```
When `has_more` is `false` and `next_cursor` is `null`, you have reached the end.
Lists are newest first, by creation time, except articles, which are ordered by last update, and the messages of a conversation, which are oldest first. A malformed cursor starts again from the first page.
Treat a cursor as an opaque string. Do not build or edit one, and keep the same filters while you page. A few lists are not paged and always return every row with `next_cursor` set to `null`: help center collections, feedback boards and knowledge sources.
## Fetch everything
**JavaScript**
```js
async function* allConversations(status = 'open') {
let cursor = null;
do {
const url = new URL('https://app.tirver.com/api/v1/conversations');
url.searchParams.set('status', status);
url.searchParams.set('limit', '100');
if (cursor) url.searchParams.set('cursor', cursor);
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.TIRVER_API_KEY}` } });
if (!res.ok) throw new Error(`Tirver ${res.status}`);
const body = await res.json();
yield* body.data;
cursor = body.has_more ? body.next_cursor : null;
} while (cursor);
}
for await (const conversation of allConversations()) console.log(conversation.id);
```
**Python**
```python
import os, requests
def all_conversations(status="open"):
cursor = None
while True:
params = {"status": status, "limit": 100}
if cursor:
params["cursor"] = cursor
res = requests.get(
"https://app.tirver.com/api/v1/conversations",
params=params,
headers={"Authorization": f"Bearer {os.environ['TIRVER_API_KEY']}"},
timeout=10,
)
res.raise_for_status()
body = res.json()
yield from body["data"]
cursor = body["next_cursor"] if body["has_more"] else None
if not cursor:
break
```
Stay inside the [rate limits](https://tirver.com/help/api/rate-limits.md) when you page through a long list: use the largest page size that suits you instead of many small pages.
Source: https://tirver.com/help/api/pagination
---
Source: https://tirver.com/help/api/rate-limits.md
# Rate limits
> How many requests you can make and what to do when you hit the limit.
To keep Tirver fast for everyone, the API limits how often each key can call it.
## The limits
- Each key can make **120 requests per minute**, counted over a sliding window. REST and MCP requests made with the same key share this limit.
- `POST /api/v1/ask` and the MCP `ask` tool are also limited to **10 per minute** per key, on top of the 120.
- A request body can be up to 256 KB. A larger one gets `413` with the code `payload_too_large`.
Limits are counted in memory by each server instance, so they are best effort rather than an exact global quota. Plan for the numbers above and rely on the response headers.
## Headers
Every authenticated response carries these headers.
| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | The limit that applies. |
| `X-RateLimit-Remaining` | Requests left in the current window. |
| `X-RateLimit-Reset` | Seconds until the oldest request in the window leaves it. |
## When you go over
The API answers `429 Too Many Requests` with the code `rate_limited` and a `Retry-After` header that gives the number of seconds to wait. A `429` can also mean the AI agent is busy.
```
HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json
{ "error": { "code": "rate_limited", "message": "Too many requests. Try again in 12 seconds.", "request_id": "req_3f9c0a1b22d4e5f6" } }
```
Wait that long, then retry the same request. Keep waiting longer after repeated `429` responses.
## Good habits
- **Always honour `Retry-After`.** It is more precise than any guess.
- **Back off.** Double the wait after each failure, and add a little random jitter so many workers do not retry at the same moment.
- **Page with `limit=100`.** Fewer, larger requests use less of your allowance. See [pagination](https://tirver.com/help/api/pagination.md).
- **Do not poll.** If you check for new conversations every second, check every minute instead.
- **Cache what rarely changes,** such as articles and customer details.
See [errors](https://tirver.com/help/api/errors.md) for a retry helper you can copy.
Source: https://tirver.com/help/api/rate-limits
---
Source: https://tirver.com/help/api/conversations.md
# Conversations
> List, read, reply to and close conversations.
A conversation is one thread between a customer and your team or the AI agent. Requests use your secret API key as a bearer token. See [authentication](https://tirver.com/help/api/authentication.md).
## The conversation object
| Field | Type | Meaning |
|---|---|---|
| `id` | string | The conversation id. |
| `status` | string | `open`, `snoozed` or `closed`. |
| `customer_id` | string | The customer in the conversation. |
| `assignee_id` | string or null | The team member who owns it, or null when unassigned. |
| `handled_by` | string | `ai` when the AI agent is handling it, otherwise `team`. |
| `channel` | string | Where it started: `widget`, `email` or `api`. |
| `subject` | string or null | The subject line, when there is one. |
| `tags` | array of strings | Tag names on the conversation. |
| `snoozed_until` | string or null | When a snoozed conversation returns to open. |
| `last_message_at` | string or null | Time of the latest message. |
| `created_at` | string | When it started. |
| `updated_at` | string | When it last changed. |
## List conversations
`GET /api/v1/conversations`
Needs the `conversations:read` scope. Newest first.
| Parameter | Type | What it does |
|---|---|---|
| `status` | string | One of `open`, `snoozed` or `closed`. |
| `assignee_id` | string | Only conversations assigned to this team member. |
| `handled_by` | string | `ai` or `team`. |
| `tag` | string | Only conversations with this tag, by name or id. |
| `customer_id` | string | Only conversations of this customer. |
| `limit` | integer | Page size, 1 to 100. Defaults to 25. |
| `cursor` | string | The `next_cursor` from the previous page. |
**curl**
```bash
curl "https://app.tirver.com/api/v1/conversations?status=open" \
-H "Authorization: Bearer $TIRVER_API_KEY"
```
**JavaScript**
```js
const res = await fetch('https://app.tirver.com/api/v1/conversations?status=open', {
headers: { Authorization: `Bearer ${process.env.TIRVER_API_KEY}` },
});
const { data, next_cursor, has_more } = await res.json();
```
**Python**
```python
res = requests.get(
"https://app.tirver.com/api/v1/conversations",
params={"status": "open"},
headers={"Authorization": f"Bearer {os.environ['TIRVER_API_KEY']}"},
timeout=10,
)
data = res.json()["data"]
```
```json
{
"data": [
{
"id": "8c1f0d52",
"status": "open",
"customer_id": "3b7a91e4",
"assignee_id": null,
"handled_by": "ai",
"channel": "widget",
"subject": "Cannot log in",
"tags": ["bug"],
"snoozed_until": null,
"last_message_at": "2026-11-14T09:05:00.000Z",
"created_at": "2026-11-14T09:02:00.000Z",
"updated_at": "2026-11-14T09:05:00.000Z"
}
],
"next_cursor": null,
"has_more": false
}
```
## Get a conversation
`GET /api/v1/conversations/{id}`
Needs `conversations:read`. Returns the conversation fields above, plus:
- `customer`: the customer's `id`, `name` and `email`.
- `summary`: a short plain extract of the thread (the first customer message, the latest, and the number of replies). It is not an AI summary.
- `messages`: up to the first 500 messages, oldest first, internal notes included.
```bash
curl https://app.tirver.com/api/v1/conversations/8c1f0d52 \
-H "Authorization: Bearer $TIRVER_API_KEY"
```
## List messages
`GET /api/v1/conversations/{id}/messages`
Needs `conversations:read`. Oldest first. Takes `limit` and `cursor`. Each message looks like this.
| Field | Type | Meaning |
|---|---|---|
| `id` | string | The message id. |
| `conversation_id` | string | The conversation it belongs to. |
| `type` | string | `reply` is visible to the customer. `note` is internal. |
| `sender` | string | `customer`, `agent` or `ai`. |
| `author_id` | string or null | The team member or customer id. Null for the AI agent. |
| `body` | string | The text. |
| `citations` | array | Sources the AI agent used, each with `title` and `url`. |
| `created_at` | string | When it was sent. |
## Reply to a conversation
`POST /api/v1/conversations/{id}/messages`
Needs `conversations:write`. A `reply` reaches the customer and takes the conversation off the AI agent. A `note` stays with your team. Returns `201` with the new message.
| Field | Type | What it does |
|---|---|---|
| `body` | string | Required. The message text, 1 to 4000 characters. |
| `type` | string | Required: `reply` or `note`. There is no default, so a note is never sent as a reply by leaving it out. |
| `author_id` | string | Optional. The team member the message is from. Defaults to the person who created the key. |
**curl**
```bash
curl https://app.tirver.com/api/v1/conversations/8c1f0d52/messages \
-H "Authorization: Bearer $TIRVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"body": "Thanks, we have fixed this.", "type": "reply"}'
```
**JavaScript**
```js
await fetch('https://app.tirver.com/api/v1/conversations/8c1f0d52/messages', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.TIRVER_API_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ body: 'Thanks, we have fixed this.', type: 'reply' }),
});
```
**Python**
```python
requests.post(
"https://app.tirver.com/api/v1/conversations/8c1f0d52/messages",
headers={"Authorization": f"Bearer {os.environ['TIRVER_API_KEY']}"},
json={"body": "Thanks, we have fixed this.", "type": "reply"},
timeout=10,
)
```
```json
{
"id": "5d2e7a10",
"conversation_id": "8c1f0d52",
"type": "reply",
"sender": "agent",
"author_id": "u_1",
"body": "Thanks, we have fixed this.",
"citations": [],
"created_at": "2026-11-15T10:00:00.000Z"
}
```
## Close a conversation
`POST /api/v1/conversations/{id}/close`
Needs `conversations:write`. Returns the conversation with `status` set to `closed`. Closing sends no message to the customer.
A conversation the AI agent answered, that no person touched, can count as an AI resolution when it is closed. See [what counts as a resolution](https://tirver.com/help/what-counts-as-a-resolution.md).
Source: https://tirver.com/help/api/conversations
---
Source: https://tirver.com/help/api/customers.md
# Customers
> Look up the customers who write to you.
A customer is a person who writes to you. Customers appear when someone writes through the widget, and gain a name and email when you [identify signed-in customers](https://tirver.com/help/identify-signed-in-customers.md). The API can list and read customers. It cannot create or change them.
## The customer object
| Field | Type | Meaning |
|---|---|---|
| `id` | string | The customer id. This is the `customer_id` on conversations. |
| `name` | string or null | Display name. |
| `email` | string or null | Email address. |
| `external_id` | string or null | The user id your product passed when identifying them. |
| `attributes` | object | Custom attributes. |
| `last_seen_at` | string or null | When they were last seen. |
| `created_at` | string | When they first appeared. |
## List customers
`GET /api/v1/customers`
Needs the `customers:read` scope. Newest first.
| Parameter | Type | What it does |
|---|---|---|
| `q` | string | Customers whose name or email contains this text. |
| `email` | string | Only the customer with this email address. Exact, not case sensitive. |
| `external_id` | string | Only the customer with this user id from your product. |
| `limit` | integer | Page size, 1 to 100. Defaults to 25. |
| `cursor` | string | The `next_cursor` from the previous page. |
**curl**
```bash
curl "https://app.tirver.com/api/v1/customers?email=ada@example.com" \
-H "Authorization: Bearer $TIRVER_API_KEY"
```
**JavaScript**
```js
const res = await fetch('https://app.tirver.com/api/v1/customers?email=ada@example.com', {
headers: { Authorization: `Bearer ${process.env.TIRVER_API_KEY}` },
});
const { data } = await res.json();
```
**Python**
```python
res = requests.get(
"https://app.tirver.com/api/v1/customers",
params={"email": "ada@example.com"},
headers={"Authorization": f"Bearer {os.environ['TIRVER_API_KEY']}"},
timeout=10,
)
customers = res.json()["data"]
```
```json
{
"data": [
{
"id": "3b7a91e4",
"external_id": "42",
"email": "ada@example.com",
"name": "Ada Lovelace",
"attributes": {},
"last_seen_at": "2026-11-14T09:01:00.000Z",
"created_at": "2026-10-02T08:30:00.000Z"
}
],
"next_cursor": null,
"has_more": false
}
```
## Get a customer
`GET /api/v1/customers/{id}`
Needs `customers:read`. Returns one customer with the same fields plus `conversation_count`, the number of conversations they have had. To list those conversations, call [`GET /api/v1/conversations?customer_id=...`](https://tirver.com/help/api/conversations.md).
Source: https://tirver.com/help/api/customers
---
Source: https://tirver.com/help/api/articles.md
# Articles
> Read help center articles, search them and create drafts.
Articles are the pages of your [help center](https://tirver.com/help/write-your-first-article.md). The API can read them, search the published ones and create drafts. A person publishes a draft in Tirver. If the workspace has switched the help center off, these endpoints answer `404` with `module_disabled`.
## The article object
| Field | Type | Meaning |
|---|---|---|
| `id` | string | The article id. |
| `slug` | string | The address-friendly name. |
| `title` | string | The title. |
| `status` | string | `draft` or `published`. |
| `collection` | object or null | The collection it is filed under, with `id`, `slug` and `name`. |
| `description` | string | The search description, or the start of the body. |
| `helpful_count` | integer | Readers who rated it helpful. |
| `not_helpful_count` | integer | Readers who rated it not helpful. |
| `published_at` | string or null | When it was first published. |
| `created_at` | string | When it was created. |
| `updated_at` | string | When it last changed. |
Lists do not include the text. Fetching a single article adds `body`, the article text as Markdown.
## List articles
`GET /api/v1/help-center/articles`
Needs the `help-center:read` scope. Drafts are included. Ordered by last update, newest first.
| Parameter | Type | What it does |
|---|---|---|
| `status` | string | `draft` or `published`. |
| `collection_id` | string | Only articles in this collection. |
| `q` | string | Search the title and body. |
| `limit` | integer | Page size, 1 to 100. Defaults to 25. |
| `cursor` | string | The `next_cursor` from the previous page. |
```bash
curl "https://app.tirver.com/api/v1/help-center/articles?status=published&q=widget" \
-H "Authorization: Bearer $TIRVER_API_KEY"
```
## Get an article
`GET /api/v1/help-center/articles/{id}`
Needs `help-center:read`. `{id}` is the article id or its slug. Returns one article with its Markdown `body`.
## Search published articles
`GET /api/v1/search`
Needs `help-center:read`. A keyword search over published articles. It matches words, not meaning, and titles rank first. For a natural language answer, use `POST /api/v1/ask`.
| Parameter | Type | What it does |
|---|---|---|
| `q` | string | Required. The words to look for. |
| `limit` | integer | How many results, 1 to 50. Defaults to 10. |
## List collections
`GET /api/v1/help-center/collections`
Needs `help-center:read`. Returns every collection, not paged, each with `id`, `slug`, `name`, `article_count` and `published_article_count`.
## Create an article draft
`POST /api/v1/help-center/articles`
Needs `help-center:write`. The article is always created as a draft, so nothing is shown to customers until a person publishes it. Returns `201` with the article. A slug that is already taken gives `409`.
| Field | Type | What it does |
|---|---|---|
| `title` | string | Required. Up to 160 characters. |
| `body` | string | The text, as Markdown. |
| `collection_id` | string | Optional. The collection to file it under. |
| `slug` | string | Optional. Lowercase letters, numbers and dashes. Made from the title when left out. |
| `description` | string | Optional. The search description, up to 320 characters. |
**curl**
```bash
curl https://app.tirver.com/api/v1/help-center/articles \
-H "Authorization: Bearer $TIRVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Reset your password", "body": "Open Settings, then Profile."}'
```
**JavaScript**
```js
const res = await fetch('https://app.tirver.com/api/v1/help-center/articles', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.TIRVER_API_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ title: 'Reset your password', body: 'Open Settings, then Profile.' }),
});
const article = await res.json();
```
**Python**
```python
res = requests.post(
"https://app.tirver.com/api/v1/help-center/articles",
headers={"Authorization": f"Bearer {os.environ['TIRVER_API_KEY']}"},
json={"title": "Reset your password", "body": "Open Settings, then Profile."},
timeout=10,
)
article = res.json()
```
The response has the article fields above plus `body`, with `status` set to `draft` and `collection` set to `null` when you gave no collection.
Source: https://tirver.com/help/api/articles
---
Source: https://tirver.com/help/api/feedback-posts.md
# Feedback posts
> Read the ideas on your boards and file new ones.
A feedback post is an idea on one of your [boards](https://tirver.com/help/feedback-boards-and-posts.md). Its status decides whether it shows on your roadmap. If the workspace has switched the feedback module off, these endpoints answer `404` with `module_disabled`.
## The feedback post object
| Field | Type | Meaning |
|---|---|---|
| `id` | string | The post id. |
| `title` | string | The idea in a line. |
| `body` | string | More detail, as text. |
| `status` | string | `open` (shown as In review), `planned`, `in_progress`, `shipped` or `declined`. |
| `board_id` | string or null | The board it belongs to. |
| `customer_id` | string or null | The author, when the post came from a customer. |
| `vote_count` | integer | How many votes it has. |
| `source_conversation_id` | string or null | The conversation it was created from. |
| `changelog_entry_id` | string or null | The changelog entry that announced it. |
| `created_at` | string | When it was posted. |
| `updated_at` | string | When it last changed. |
Fetching a single post adds `comments`, each with `id`, `author_kind` (`team` or `customer`), `author_id`, `body` and `created_at`.
## List boards
`GET /api/v1/feedback/boards`
Needs the `feedback:read` scope. Returns every board, not paged, each with `id`, `slug` and `name`.
## List feedback posts
`GET /api/v1/feedback/posts`
Needs `feedback:read`. Newest first. Posts that were merged into another post as duplicates are not listed.
| Parameter | Type | What it does |
|---|---|---|
| `status` | string | Only posts with this status. |
| `board_id` | string | Only posts on this board. |
| `q` | string | Search the title and details. |
| `limit` | integer | Page size, 1 to 100. Defaults to 25. |
| `cursor` | string | The `next_cursor` from the previous page. |
```bash
curl "https://app.tirver.com/api/v1/feedback/posts?status=planned" \
-H "Authorization: Bearer $TIRVER_API_KEY"
```
## Get a feedback post
`GET /api/v1/feedback/posts/{id}`
Needs `feedback:read`. Returns one post with its comments.
## Create a feedback post
`POST /api/v1/feedback/posts`
Needs `feedback:write`. The post starts with the status `open`. Returns `201` with the post.
| Field | Type | What it does |
|---|---|---|
| `title` | string | Required. Up to 160 characters. |
| `body` | string | Optional. More detail, up to 8,000 characters. |
| `board_id` | string | Optional. The board to post on. |
| `conversation_id` | string | Optional. Links the post to the conversation it came from and to that conversation's customer, who gets the first vote. A conversation can have one post, so a second one gives `409`. |
**curl**
```bash
curl https://app.tirver.com/api/v1/feedback/posts \
-H "Authorization: Bearer $TIRVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Dark mode for the booking page", "conversation_id": "8c1f0d52"}'
```
**JavaScript**
```js
const res = await fetch('https://app.tirver.com/api/v1/feedback/posts', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.TIRVER_API_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ title: 'Dark mode for the booking page', conversation_id: '8c1f0d52' }),
});
const post = await res.json();
```
**Python**
```python
res = requests.post(
"https://app.tirver.com/api/v1/feedback/posts",
headers={"Authorization": f"Bearer {os.environ['TIRVER_API_KEY']}"},
json={"title": "Dark mode for the booking page", "conversation_id": "8c1f0d52"},
timeout=10,
)
post = res.json()
```
```json
{
"id": "a41c9e07",
"title": "Dark mode for the booking page",
"body": "",
"status": "open",
"board_id": null,
"customer_id": "3b7a91e4",
"vote_count": 1,
"source_conversation_id": "8c1f0d52",
"changelog_entry_id": null,
"created_at": "2026-11-14T10:15:00.000Z",
"updated_at": "2026-11-14T10:15:00.000Z"
}
```
Source: https://tirver.com/help/api/feedback-posts
---
Source: https://tirver.com/help/api/changelog-entries.md
# Changelog entries
> Read your release notes with the API, or from the public endpoint without a key.
Changelog entries are the release notes customers see on your changelog. The API can read them. It cannot create or publish them: writing and publishing is done in Tirver, because publishing marks linked feedback as shipped. See [publish a changelog entry](https://tirver.com/help/publish-a-changelog-entry.md). If the workspace has switched the changelog module off, these endpoints answer `404` with `module_disabled`.
## The changelog entry object
| Field | Type | Meaning |
|---|---|---|
| `id` | string | The entry id. |
| `slug` | string | The address-friendly name. |
| `title` | string | The title. |
| `status` | string | `draft` or `published`. |
| `labels` | array of strings | Labels such as `New` or `Integrations`. |
| `published_at` | string or null | When it was published. |
| `created_at` | string | When it was created. |
| `updated_at` | string | When it last changed. |
Lists add `description`, the start of the body. Fetching a single entry adds `body`, the notes as Markdown.
## List changelog entries
`GET /api/v1/changelog`
Needs the `changelog:read` scope. Newest first.
| Parameter | Type | What it does |
|---|---|---|
| `status` | string | `published` (the default), `draft` or `all`. |
| `limit` | integer | Page size, 1 to 100. Defaults to 25. |
| `cursor` | string | The `next_cursor` from the previous page. |
```bash
curl "https://app.tirver.com/api/v1/changelog?status=published&limit=5" \
-H "Authorization: Bearer $TIRVER_API_KEY"
```
## Get a changelog entry
`GET /api/v1/changelog/{id}`
Needs `changelog:read`. `{id}` is the entry id or its slug. Returns one entry with its Markdown `body`.
## Public changelog
Published entries for your workspace are also available without a key, as JSON, so you can show them on your own site. Replace `WORKSPACE` with your workspace slug.
`GET /api/public/WORKSPACE/changelog`
Returns every published entry, newest first.
```json
{
"workspace": { "name": "Acme", "slug": "acme" },
"entries": [
{
"slug": "resizable-inbox-panels",
"title": "Resizable inbox panels",
"labels": ["Inbox"],
"description": "Drag the edges of the panels to make room for what you are reading.",
"publishedAt": "2026-11-12T09:00:00.000Z"
}
]
}
```
`GET /api/public/WORKSPACE/changelog/{slug}`
Returns `{ "entry": ... }` with the same fields plus `body` (Markdown), `html` and `markdownUrl`. Add `.md` to the slug to get the entry as Markdown text. Responses are cached for a short time and the endpoints allow requests from any origin. Note that these public endpoints use `camelCase` field names, unlike the keyed API.
Source: https://tirver.com/help/api/changelog-entries
---
Source: https://tirver.com/help/mcp.md
# Overview
> What the Tirver MCP server is, what an assistant can do with it and how it differs from the REST API.
The Tirver MCP server lets an AI assistant such as Claude read and act on your workspace: search articles, read conversations, draft replies and file feedback. MCP, the Model Context Protocol, is the open standard that assistants use to connect to tools.
It is separate from the [REST API](https://tirver.com/help/api.md), which is for your own code. Use MCP when a person works through an assistant. Use the API when a program works on its own. Both use the same [API key](https://tirver.com/help/api/authentication.md), and they share its rate limit.
## What an assistant can do
| Job | Tool |
|---|---|
| Find an answer in your help center | `search_articles` |
| See what is waiting in the inbox | `list_conversations` |
| Read a conversation and its messages | `get_conversation` |
| Look up a customer | `list_customers` |
| Ask the AI agent a question | `ask` |
| Leave a suggested reply for a teammate | `draft_reply` |
| File an idea a customer raised | `create_feedback_post` |
| Start a help article | `create_article_draft` |
There are 16 tools in all. The full list, with inputs and the scope each needs, is on the [tools](https://tirver.com/help/mcp/tools.md) page.
## Safe by design
- A key can only use the tools its scopes allow. The assistant is only shown those tools.
- The write tools never message a customer and never publish anything. `draft_reply` saves an internal note for a teammate to read and send. `create_article_draft` makes a draft. `create_feedback_post` files a post.
- A key works for one workspace only, and you can revoke it at any time.
See [permissions](https://tirver.com/help/mcp/permissions.md) for details.
## Where it lives
The server speaks MCP Streamable HTTP at one address, and answers `POST` requests with JSON.
```
https://app.tirver.com/mcp
```
## Get started
1. [Connect an assistant](https://tirver.com/help/mcp/connect.md) in a few minutes.
2. Read about [permissions](https://tirver.com/help/mcp/permissions.md) and choose what to allow.
3. Try the guides: [draft replies from your editor](https://tirver.com/help/mcp/draft-replies.md) and [triage feedback with an assistant](https://tirver.com/help/mcp/triage-feedback.md).
Source: https://tirver.com/help/mcp
---
Source: https://tirver.com/help/mcp/connect.md
# Connect an assistant
> Create an API key and add the Tirver MCP server to Claude, Cursor or any MCP client.
## Create an API key
The MCP server uses the same workspace API keys as the [REST API](https://tirver.com/help/api/authentication.md). Only owners and admins can create them.
1. Sign in to [app.tirver.com](https://app.tirver.com).
2. Open **Settings, API keys** and create a key.
3. Choose its scopes. For a read-only assistant pick only the read scopes. To let it leave draft replies, create drafts and file feedback, add `conversations:write`, `help-center:write` or `feedback:write`. See [permissions](https://tirver.com/help/mcp/permissions.md).
4. Copy the key straight away. It is shown once.
Treat the key like a password.
## Add the server
Most clients accept a server address and a header. The values are always the same.
| Setting | Value |
|---|---|
| URL | `https://app.tirver.com/mcp` |
| Transport | Streamable HTTP |
| Header | `Authorization: Bearer YOUR_API_KEY` |
**Claude Code**
```bash
claude mcp add --transport http tirver https://app.tirver.com/mcp \
--header "Authorization: Bearer YOUR_API_KEY"
```
**Cursor and similar**
```json
{
"mcpServers": {
"tirver": {
"type": "http",
"url": "https://app.tirver.com/mcp",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}
```
**Claude Desktop**
```json
{
"mcpServers": {
"tirver": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://app.tirver.com/mcp", "--header", "Authorization: Bearer YOUR_API_KEY"]
}
}
}
```
Restart the client after you edit its configuration.
## Check that it works
Ask the assistant something that needs your workspace, for example: "Search the Tirver help center for how to install the widget." The assistant should call `search_articles` and answer from what it finds. If it does not list Tirver among its tools, see the troubleshooting list below.
## Troubleshooting
| What you see | What to check |
|---|---|
| No Tirver tools appear | Restart the client. Check the URL for typos. |
| `401 Unauthorized` | The key is missing, wrong, expired or revoked. The key starts with `trv_live_`. Create a new one. |
| Write tools are missing | The key has no write scope. Create a key that includes `conversations:write`, `help-center:write` or `feedback:write`. |
| A tool answers that a scope is missing | The message names the scope. Create a key that includes it. |
| `429 Too Many Requests` | The assistant is calling too fast. See [limits](https://tirver.com/help/mcp/limits.md). |
Source: https://tirver.com/help/mcp/connect
---
Source: https://tirver.com/help/mcp/tools.md
# Tools
> Every tool the Tirver MCP server offers, with inputs and the scope each needs.
Assistants discover these tools on their own. This page tells you what each does, so you know what to ask for and what to expect. The server only lists the tools your key's [scopes](https://tirver.com/help/mcp/permissions.md) allow, and refuses any other call with the missing scope named. Arguments are checked against each tool's published schema, and unknown arguments are rejected.
| Tool | What it does | Scope |
|---|---|---|
| `search_articles` | Keyword search over published help articles. | `help-center:read` |
| `list_articles` | Lists articles, drafts included. | `help-center:read` |
| `get_article` | Returns one article with its Markdown text. | `help-center:read` |
| `list_collections` | Lists help center collections. | `help-center:read` |
| `list_conversations` | Lists conversations by status, assignee, tag or customer. | `conversations:read` |
| `get_conversation` | Returns one conversation with its messages. | `conversations:read` |
| `list_customers` | Looks up customers by name, email or your own id. | `customers:read` |
| `list_feedback_posts` | Lists feedback posts. | `feedback:read` |
| `get_feedback_post` | Returns one post with its comments. | `feedback:read` |
| `list_changelog` | Lists changelog entries. | `changelog:read` |
| `list_knowledge_sources` | Lists what the AI agent learns from. | `knowledge:read` |
| `get_credits` | Returns the AI credit balance. | `credits:read` |
| `ask` | Asks the AI agent a question and returns an answer with citations. | `ai:ask` |
| `draft_reply` | Saves a suggested reply as an internal note. | `conversations:write` |
| `create_feedback_post` | Files a feedback post, linked to a conversation if given. | `feedback:write` |
| `create_article_draft` | Starts a help center article as a draft. | `help-center:write` |
Arguments and limits are the same as for the matching [REST endpoint](https://tirver.com/help/api.md). Lists accept `limit` (1 to 100) and `cursor` and return `data`, `next_cursor` and `has_more`.
## search_articles
Finds published articles by keyword. It matches words, not meaning, with titles ranking first. For a natural language answer use `ask`.
| Input | Type | Meaning |
|---|---|---|
| `q` | string | Required. The words to look for. |
| `limit` | integer | How many results, 1 to 50. |
## list_articles and get_article
`list_articles` takes `status` (`draft` or `published`), `collection_id`, `q`, `limit` and `cursor`. `get_article` takes `id`, which can be the article id or its slug, and returns the Markdown body.
## list_conversations
| Input | Type | Meaning |
|---|---|---|
| `status` | string | `open`, `snoozed` or `closed`. |
| `assignee_id` | string | Only conversations assigned to this team member. |
| `handled_by` | string | `ai` or `team`. |
| `tag` | string | Only conversations with this tag. |
| `customer_id` | string | Only this customer's conversations. |
| `limit`, `cursor` | | Paging. |
## get_conversation
| Input | Type | Meaning |
|---|---|---|
| `id` | string | Required. The conversation to read. |
Returns the customer, a short plain extract of the thread called `summary` (not an AI summary) and up to the first 500 messages, oldest first. Internal notes are included so the assistant has full context, so be careful where you route the output.
## list_customers
Takes `q` (name or email contains), `email` (exact), `external_id`, `limit` and `cursor`. Needs `customers:read`, which includes email addresses.
## ask
| Input | Type | Meaning |
|---|---|---|
| `question` | string | Required. Up to 2000 characters. |
| `history` | array | Earlier turns, up to 19, each with `role` (`user` or `assistant`) and `text`. |
Uses the same AI agent, tone and instructions as **Test the agent**. It stores nothing and uses no credits. It is limited to 10 calls a minute per key, shared with `POST /api/v1/ask`.
## draft_reply
| Input | Type | Meaning |
|---|---|---|
| `conversation_id` | string | Required. The conversation to draft for. |
| `body` | string | Required. The suggested reply, up to 3,900 characters. |
| `author_id` | string | The team member to show as the note's author. Defaults to the person who created the key. |
Saves an internal note that starts with "Draft reply (from an AI assistant, not sent):". There is no separate draft message type, so the draft appears in the conversation as a note. A team member reads it and sends the reply themselves. Nothing reaches the customer.
## create_feedback_post
| Input | Type | Meaning |
|---|---|---|
| `title` | string | Required. The idea in a line. |
| `body` | string | More detail. |
| `board_id` | string | The board to file it on. |
| `conversation_id` | string | Link the post to the conversation it came from. The customer gets the first vote. A conversation can have one post. |
## create_article_draft
| Input | Type | Meaning |
|---|---|---|
| `title` | string | Required. The article title. |
| `body` | string | The text, as Markdown. |
| `collection_id` | string | The collection to file it under. |
| `slug` | string | The address. Made from the title when left out. |
| `description` | string | The search description. |
The article is always a draft until a person publishes it.
## Resources
Besides tools, the server offers readable resources: `tirver://articles/{id}` (Markdown), `tirver://conversations/{id}` and `tirver://feedback/{id}` (JSON). Each needs the same scope as the matching tool.
## An example exchange
You ask: "Which open conversations are about billing?"
1. The assistant calls `list_conversations` with `status` set to `open` and `tag` set to `billing`.
2. It calls `get_conversation` for the ones that look relevant.
3. It tells you what it found and offers to `draft_reply` to any of them.
New tools are announced in the [changelog](https://tirver.com/changelog.md).
Source: https://tirver.com/help/mcp/tools
---
Source: https://tirver.com/help/mcp/permissions.md
# Permissions
> How API key scopes decide which tools an assistant sees, and why write tools never reach customers.
An API key holds an explicit list of [scopes](https://tirver.com/help/api/permissions.md). The MCP server shows an assistant only the tools those scopes allow, and refuses any other call with the missing scope named. Nothing is implied: a write scope does not include the matching read scope.
| Scope | Tools it unlocks |
|---|---|
| `help-center:read` | `search_articles`, `list_articles`, `get_article`, `list_collections` |
| `conversations:read` | `list_conversations`, `get_conversation` |
| `customers:read` | `list_customers` |
| `feedback:read` | `list_feedback_posts`, `get_feedback_post` |
| `changelog:read` | `list_changelog` |
| `knowledge:read` | `list_knowledge_sources` |
| `credits:read` | `get_credits` |
| `ai:ask` | `ask` |
| `conversations:write` | `draft_reply` |
| `feedback:write` | `create_feedback_post` |
| `help-center:write` | `create_article_draft` |
## Writes never reach customers
The MCP write tools never send a message to a customer and never publish anything.
- `draft_reply` saves an internal note on the conversation, marked as a draft that was not sent. A teammate reads it, then sends it, edits it or ignores it.
- `create_article_draft` creates an unpublished article.
- `create_feedback_post` files a post, which your team can review, merge or decline like any other.
This means a mistaken or manipulated assistant cannot message your customers through MCP. The same key, used with the [REST API](https://tirver.com/help/api/conversations.md), can send a customer reply when it holds `conversations:write`, so give that scope only to code you trust.
## Choose a key for the job
- Use read scopes only for assistants that summarise, search or report.
- Add a write scope only where you want drafts created, and where someone reviews them.
- Create one key per assistant, so you can revoke one without disturbing the others. Set an expiry when the key is only needed for a while.
## Revoke a key
Revoke a key under **Settings, API keys** whenever someone leaves or a device is lost. It stops working at once.
## Mind what is in conversations
Conversations contain customer text. An assistant reads it as input, and a customer could write instructions that try to steer it. Internal notes are included when a key can read conversations. Keep write access narrow, and review drafts before sending, as you would any message written for you.
Source: https://tirver.com/help/mcp/permissions
---
Source: https://tirver.com/help/mcp/limits.md
# Errors and limits
> What assistants see when something goes wrong, and how request limits work.
The MCP server uses the same API keys, sign-in rules and limits as the [REST API](https://tirver.com/help/api.md), so the same ideas apply.
## How the server answers
The server speaks Streamable HTTP in stateless JSON-RPC. Each `POST` carries one JSON-RPC message, or a batch of up to 20, and gets a JSON reply. Notifications get `202` with no body. There is no session and no event stream, so `GET` and `DELETE` answer `405`.
## Errors
Problems before the request reaches the MCP protocol use the HTTP status and the same JSON error body as the REST API, with a `request_id`.
| Status | Code | What to do |
|---|---|---|
| 401 | `missing_api_key` or `invalid_api_key` | Create a new key and update the client. |
| 413 | `payload_too_large` | Send a smaller request. The limit is 256 KB. |
| 429 | `rate_limited` | Wait for `Retry-After` seconds. |
| 500 | `internal_error` | Try again in a moment. |
Protocol mistakes are JSON-RPC errors: `-32700` for a body that is not JSON, `-32600` for an invalid request, `-32601` for an unknown method, `-32602` for invalid parameters or an unknown tool, and `-32002` for a resource that is not found.
When a tool itself fails, because an argument is wrong, the record does not exist, the key lacks the scope, the module is switched off or a limit was hit, the assistant gets a normal result marked `isError` with a plain message it can read to you. Ask it to try again, or to explain what it needs.
## Limits
- 120 requests a minute per key. REST and MCP requests made with the same key share this.
- `ask` is limited to 10 a minute per key, on top of the 120.
Limits are counted per server instance, so they are best effort. Long searches across many conversations are best done in several short steps. See [rate limits](https://tirver.com/help/api/rate-limits.md) for the headers and the full explanation.
## Logs
Tirver records every request, including rejected ones, with the key prefix, the tool name and the status, so problems can be investigated. It does not record arguments, results or the key itself.
Source: https://tirver.com/help/mcp/limits
---
Source: https://tirver.com/help/mcp/draft-replies.md
# Draft replies from your editor
> Use an assistant to prepare replies to open conversations, then review and send them in Tirver.
This guide shows a typical flow with an assistant in your editor or chat window. You need an API key with `conversations:read`, `help-center:read` and `conversations:write`. See [connect an assistant](https://tirver.com/help/mcp/connect.md).
## The flow
1. Ask for the queue: "List my open Tirver conversations that mention the calendar sync."
2. The assistant calls `list_conversations`, then `get_conversation` for each match.
3. Ask it to check your help center: "Find the article about reconnecting a calendar."
4. It calls `search_articles` and quotes what the article says.
5. Ask for a draft: "Draft a reply for the first one, friendly, and link the article."
6. The assistant calls `draft_reply` and tells you the draft is saved.
## Review and send
The draft is saved as an internal note on the conversation, starting with "Draft reply (from an AI assistant, not sent):". Open the conversation in Tirver, read the note, then copy it into a reply, change what you like and send it, or ignore it. It is a note, so it is visible to your team only. Nothing reaches the customer before you send a reply yourself.
## Good prompts
- Give the tone: "short and warm", "formal".
- Ask it to cite the article it used.
- Ask it to flag any conversation it is unsure about instead of drafting.
## What the assistant will not do
Through MCP it cannot send a reply, close or assign a conversation, or publish an article. Those stay with your team.
Source: https://tirver.com/help/mcp/draft-replies
---
Source: https://tirver.com/help/mcp/triage-feedback.md
# Triage feedback with an assistant
> Turn customer requests from conversations into feedback posts and article drafts.
Customers often ask for things in a chat that never become feedback. An assistant can help you catch them. This guide needs an API key with `conversations:read`, `help-center:read`, `feedback:write` and, for article drafts, `help-center:write`.
## The flow
1. Ask: "Look at Tirver conversations from this week that ask for a feature."
2. The assistant calls `list_conversations` and `get_conversation`, then summarises the requests it found.
3. Ask: "File each of these as feedback, linked to its conversation."
4. For each one it calls `create_feedback_post` with the `conversation_id`. The post is linked to the conversation and its customer, who gets the first vote. A conversation can have only one post.
## Spot gaps in the help center
Ask: "Which of these questions are not answered in our articles?" The assistant calls `search_articles` for each topic. For gaps, say: "Start a draft article for the missing ones." It calls `create_article_draft`.
## Then review in Tirver
- Open **Feedback** to review the new posts. Merge duplicates and set a status.
- Open **Help center** to polish and publish the drafts.
The assistant files and drafts. You decide what is real and what is public.
Source: https://tirver.com/help/mcp/triage-feedback
---
Source: https://tirver.com/changelog.md
# What changed in Tirver
New features and improvements, newest first.
---
Source: https://tirver.com/newsletter.md
# Tirver updates by email
Changelog entries and product news, in one email. Subscribe on the page at https://tirver.com/newsletter. You confirm your address by email, and every email has an unsubscribe link.