[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8},"actionData","errors","root",{"_229":230,"_231":232,"_233":234,"_20":21,"_235":-7,"_236":237,"_238":-7,"_239":240,"_241":-5,"_242":31,"_243":31,"_244":-5,"_245":-5,"_246":247,"_51":248,"_249":250,"_251":31},"docs-content",{"_9":10,"_10":11,"_12":13,"_14":15,"_16":17,"_18":19},"type","collection",{"_22":122,"_85":123,"_134":222,"_59":-5,"_71":223,"_224":225,"_140":-5,"_226":-5,"_141":227,"_143":228},"articles",[124,125,126,127,128,129,130,131,132],"subCollectionsWithArticles",[],"breadcrumbData",{"_118":119,"_120":121},"context",{"_20":21},"portal",{"_22":23,"_24":25,"_26":27,"_28":20,"_29":27,"_30":31,"_32":33,"_34":35,"_36":37,"_38":39,"_40":41,"_42":43,"_44":41,"_45":46,"_47":48,"_49":50,"_51":-7,"_52":53,"_54":55,"_56":-7},"id","9ae77332-80b3-4302-b8a5-f0a74c773dbf","tenantId","unthread-unthread-e4pm8","isExternal",true,"mode","isEnabled","requireAuthentication",false,"identityPlatformTenantId","e-unthread-3berp","loginMethods",[111,112,113],"settings",{"_94":95,"_96":97,"_98":99,"_100":101,"_102":103,"_104":105,"_106":-7,"_107":-7,"_108":109,"_110":27},"tenant",{"_85":86,"_87":88},"customDomain","docs.unthread.io","defaultDomain","unthread.help.unthread.io","canonicalDomain","projectIds",[84],"customLinks",[64,65,66,67],"featuredCollections",[61,62,63],"collections","ticketTypeSections",[],"homepageMetadata",{"_57":58,"_59":60},"statusBanner","title","Welcome to Unthread's Helpdesk","description","Browse through docs, ask the AI for help, or manage your own support tickets.","ac886cfd-cbf6-4cb0-b3b0-b66d3ca36752","f3a97e0f-079d-4251-9569-077912cb5dff","6b0ca0aa-e17d-4485-af21-e8bf8610f86e",{"_57":81,"_69":82,"_71":83,"_72":-7},{"_57":77,"_69":78,"_71":79,"_72":80},{"_57":74,"_69":75,"_71":-5,"_72":76},{"_57":68,"_69":70,"_71":-5,"_72":73},"Book a Demo","link","https://unthread.io/demo","icon","buttonStyle","primary","Dashboard","https://app.unthread.io","light","API Docs","https://docs.unthread.io/docs/api-docs/api-reference","server","default","Contact us","mailto:support@unthread.io","mail","e9ce1893-1a81-419e-abc6-8898f4532b56","name","Unthread","allowedPriorities",{"_89":31,"_90":27,"_91":27,"_92":27,"_93":27},"1","3","5","7","9","logoUrl","https://firebasestorage.googleapis.com/v0/b/trnout-co.appspot.com/o/unthread-unthread-e4pm8%2Fportal-logos%2Ficon-transparent.png?alt=media","lightLogoUrl","https://firebasestorage.googleapis.com/v0/b/trnout-co.appspot.com/o/unthread-unthread-e4pm8%2Fportal-logos%2Flogo-dark.png?alt=media","darkLogoUrl","https://firebasestorage.googleapis.com/v0/b/trnout-co.appspot.com/o/unthread-unthread-e4pm8%2Fportal-logos%2Flogo-light.png?alt=media","primaryColor","#f2453e","darkThemeAccentColor","#f2443f","fontFamily","dmSans","embed","homepageBannerUrl","homepageBannerTextColor","black","allowDirectTicketCreation",{"_9":117,"_115":27},{"_9":116,"_115":31},{"_9":114,"_115":31},"sso","enabled","emailPassword","magicLink","currentItem",{"_22":122,"_85":123,"_9":10},"breadcrumbs",[],"ef88f17f-9bdc-4fd1-911c-acf273d2f65f","Unthread AI",{"_57":213,"_134":214,"_136":-5,"_137":215,"_139":122,"_140":-5,"_141":216,"_143":217,"_22":218,"_24":25,"_145":219,"_147":-5,"_148":220,"_150":221},{"_57":204,"_134":205,"_136":-5,"_137":206,"_139":122,"_140":-5,"_141":207,"_143":208,"_22":209,"_24":25,"_145":210,"_147":-5,"_148":211,"_150":212},{"_57":195,"_134":196,"_136":-5,"_137":197,"_139":122,"_140":-5,"_141":198,"_143":199,"_22":200,"_24":25,"_145":201,"_147":-5,"_148":202,"_150":203},{"_57":187,"_134":188,"_136":-5,"_137":189,"_139":122,"_140":-5,"_141":190,"_143":190,"_22":191,"_24":25,"_145":192,"_147":-5,"_148":193,"_150":194},{"_57":178,"_134":179,"_136":-5,"_137":180,"_139":122,"_140":-5,"_141":181,"_143":182,"_22":183,"_24":25,"_145":184,"_147":-5,"_148":185,"_150":186},{"_57":170,"_134":-5,"_136":-5,"_137":171,"_139":122,"_140":-5,"_141":172,"_143":173,"_22":174,"_24":25,"_145":175,"_147":-5,"_148":176,"_150":177},{"_57":161,"_134":162,"_136":-5,"_137":163,"_139":122,"_140":-5,"_141":164,"_143":165,"_22":166,"_24":25,"_145":167,"_147":-5,"_148":168,"_150":169},{"_57":152,"_134":153,"_136":-5,"_137":154,"_139":122,"_140":-5,"_141":155,"_143":156,"_22":157,"_24":25,"_145":158,"_147":-5,"_148":159,"_150":160},{"_57":133,"_134":135,"_136":-5,"_137":138,"_139":122,"_140":-5,"_141":142,"_143":142,"_22":144,"_24":25,"_145":146,"_147":-5,"_148":149,"_150":151},"Unthread WebMCP","slug","unthread-webmcp","url","content","### Drive Unthread from your AI agent\n\nUnthread supports **WebMCP** — a way to connect your own AI agent directly to the Unthread dashboard in your browser.\n\n---\n\n### Two ways to connect\n\nYou can connect an AI agent two ways. Pick whichever fits how you already work:\n\n- **A browser-native agent** — an AI agent that lives inside your browser, like Claude for Chrome. No external setup; the dashboard exposes its tools directly to the agent on the page.\n- **A desktop AI app** — Claude Desktop, Claude Code, Cursor, or any other app that supports MCP. You install a small browser extension that bridges your open Unthread tab to the desktop app.\n\nBoth paths reach the same set of capabilities. The difference is purely about which AI app you prefer.\n\n---\n\n### Set up — browser-native agent\n\n1. Install your browser-native AI agent — for example, Claude for Chrome.\n\n2. Sign in to Unthread as you normally would and open the dashboard.\n\n3. **Start a fresh conversation with your agent and, as the first message, tell it to use the Unthread tools.** A clear opening line:\n\n > `Please connect to the WebMCP tools on this page`\n\n The agent will discover the tools and orient itself. Once it has, give it any task in the next message.\n\nThat's it. The agent authenticates using your existing Unthread session, so everything it does is done as you.\n\n**Why a dedicated first turn matters.** If your first message mixes the connect instruction with a task (e.g., *\"use the unthread tools to filter my inbox\"*), the agent may treat \"unthread tools\" as a vague reference instead of looking up the actual tool registry on the page. A standalone instruction lets it discover and load the tool surface cleanly.\n\n---\n\n### Set up — desktop AI app via the bridge\n\n1. **Install the [WebMCP Bridge extension by MCPCat](https://chromewebstore.google.com/detail/webmcp-bridge/chgjbookknohehmaocfijekhaocaanaf)** in the browser you use for Unthread.\n\n2. **Install the local relay.** In a terminal:\n\n ```plaintext\n npm install -g @mcp-b/webmcp-server\n ```\n\n3. **Configure your desktop AI app to use the relay.**\n\n - **Claude Desktop**: Settings → Developer → Edit Config; add an entry under `mcpServers`:\n\n ```json\n {\n \"mcpServers\": {\n \"webmcp\": {\n \"command\": \"webmcp-server\"\n }\n }\n }\n ```\n - **Claude Code**: `claude mcp add webmcp -- webmcp-server`\n - **Cursor / Windsurf**: follow the app's MCP server configuration; point it at the `webmcp-server` command.\n\n4. **Open Unthread in your browser.** The bridge extension popup will show the active tab and the tools it found.\n\n5. **Open your desktop AI app** and ask it to use Unthread. It sees the dashboard's tools the same way it sees any other MCP server.\n\nYour desktop app authenticates through your browser session — no token to set up.","collectionId","projectId","createdAt","2026-05-29T17:49:56.941Z","updatedAt","beabba07-1cdf-4ad8-8a83-11cce14b899a","collectionPath",[],"hostedUrl","userGroups",[],"channels",[],"Unthread MCP","portal-mcp","You can now connect your AI agent to your Unthread support portal! Once connected, you can ask it to search the knowledge base, check on your open tickets, submit new tickets, and start support conversations — all from inside ChatGPT, Claude, Cursor, or any MCP-capable AI client.\n\n## Setup Instructions\n\nYour portal's MCP URL is your portal's domain followed by `/api/mcp`:\n\n```plaintext\nhttps:///api/mcp\n```\n\nFor example, if your portal is hosted at `help.acme.com`, then your portal MCP is `https://help.acme.com/api/mcp`.\n\nIf you're not sure what your portal's domain is, it's the address you visit to log in. The instructions below use `` as a placeholder — replace it with your actual portal address.\n\n### ChatGPT\n\n1. Sign in to ChatGPT.\n\n2. Open **Apps**, then click on the settings icon (circled in green in this screenshot:![Screenshot 2026-06-02 at 10.53.45 AM.png](/api/knowledge-base/images/ac15d3a3-91ea-4754-b841-822d4984ef27)\n\n3. if you haven't done so already, click into **Advanced settings**, then enable developer mode. *(This is required because these apps are bespoke to your setup and cannot be listed on the public marketplace)*![Screenshot 2026-06-02 at 10.54.33 AM.png](/api/knowledge-base/images/0fa4e52e-ac96-4872-a483-009f4e477c24)![Screenshot 2026-06-02 at 10.58.15 AM.png](/api/knowledge-base/images/9d6f5a4d-d2f0-455a-99e0-4f5bb54cf6fb)\n\n4. Click **Create app**, then enter a name (e.g. \"Acme Support\") and the server URL:\n\n ```plaintext\n https:///api/mcp\n ```\n\n5. Set **Authentication** to **OAuth**.\n\n6. Check the \"I understand and want to continue\" box, and click **Create**.\n\n7. Click **Connect**. ChatGPT will open your portal's sign-in page.\n\n*Note: ChatGPT is a little inconsistent with how they handle MCPs. if you find that the app is not being properly connected, you may need to manually add it to your chat:*\n\n![Screenshot 2026-06-02 at 11.05.41 AM.png](/api/knowledge-base/images/e5a846ee-b693-4cd0-9ce1-40e9d1066cbc)\n\n### Claude.ai (Web)\n\n1. Go to [claude.ai](https://claude.ai) and sign in.\n\n2. Navigate to **Customize** → **Connectors** → **Add custom connector**.![Screenshot 2026-06-02 at 11.07.57 AM.png](/api/knowledge-base/images/5c4d3820-8221-41be-b39b-a0b7399d2499)\n\n3. Enter a name (e.g. \"Acme Support\") and the server URL:\n\n ```plaintext\n https:///api/mcp\n ```\n\n4. Click **Add** and follow the authorization prompt.\n\n5. Sign in with your portal account when prompted.\n\n> \n\n### Claude Code (CLI)\n\n1. Open your Claude Code configuration file at `~/.claude.json`.\n\n2. Add your portal to the `mcpServers` section:\n\n ```json\n {\n \"mcpServers\": {\n \"acme-portal\": {\n \"url\": \"https:///api/mcp\"\n }\n }\n }\n ```\n\n3. Restart Claude Code.\n\n4. When you first use a portal tool, you'll be prompted to authenticate via your browser.\n\n## Capabilities and limitations\n\n**What your agent can read:**\n\n- **Knowledge base** — search, fetch articles, look up an answer.\n- **Your conversations** — list your active conversations, read messages, check status.\n- **Portal context** — the portal's name, ticket types, projects you can submit to.\n- **Bot replies** — start a conversation with the portal bot and poll for its response.\n\n**What your agent can write** (only if your portal admin has enabled it):\n\n- **Create a ticket** — file a new support ticket on your behalf, including custom field values.\n- **Convert a conversation to a ticket** — escalate an existing bot conversation into a tracked ticket.\n- **Reply to a conversation** — send a message into a conversation you're part of.","2026-06-02T14:53:50.315Z","2026-06-02T17:00:55.503Z","162f8604-54a6-4c27-bff1-7825019ce1f9",[],[],[],"Unthread Admin MCP","unthread-mcp","Unthread supports the [**Model Context Protocol (MCP)**](https://modelcontextprotocol.io/), allowing you to connect your AI assistant to your Unthread workspace.\n\nAs of 4/16/26 Unthread is an official **Anthropic Partner** available in **Tools and Plugins** under the **Model Context Protocol** section:\n\n\\\n![image.png](/api/knowledge-base/images/a686059e-d725-4e46-8053-209bfaf31fca)\n\n## Current capabilities and limitations\n\n**What data is available (read)**: The MCP currently supports reading:\n\n- **Conversations**\n- **Users**\n- **Analytics**\n- **Knowledge base** (read-only endpoints)\n- **Custom fields / ticket types**\n- **Surveys**\n - There are five read-only MCP `endpointTool` wrappers for survey analytics: `list_surveys`, `get_survey_analytics`, `list_survey_responses`, `get_outbound_survey`, and `list_outbound_survey_responses`, including Zod list/field allowlists and request-building that separates path params, optional query filters, and bodies.\\\n Use `get_survey_analytics` date-range validation (requires `startDate` and `endDate` together) for date filtering.\n- **External Tasks**\n - Add `external_task_projects` plus materialized `project_id` / `project_lookup_key` arrays, trigger/view updates, and GIN indexes for provider/project filtering.\n - Add `externalTaskProjectId` analytics grouping/filtering with project-name lookup and per-conversation/project deduping.\n - Add opportunistic project lookup upserts on external task writes plus a dry-run-default backfill script. Backfill entry point: `node scripts/backfill-external-task-projects.js --tenant-id <tenant> --dry-run`, then rerun with `--run` when ready.\n\n**What data is available (write): The MCP currently supports writing:**\n\n- **update\\_conversation** tool available in MCP\n- **create\\_conversation\\_comment** tool available in MCP (supports Slack block format)\n- **create\\_approval\\_request tool** available in MCP\n\n## **Setup Instructions**\n\n### [Claude.ai](http://Claude.ai) (Web)\n\n1. Go to [**claude.ai**](http://Claude.ai) and sign in\n\n2. Navigate to **Settings** → **Connectors** → **Add custom connector**\n\n3. Enter a name (e.g., “Unthread”) and the server URL:\n\n ```plaintext\n https://app.unthread.io/api/mcp\n ```\n\n![CleanShot 2026-01-20 at 14.11.03.png](/api/knowledge-base/images/f9a30a7c-dc36-4042-8af5-ffca8a249766)\n\n4. Click **Add** and follow the authorization prompt\n5. Sign in with your Unthread account when prompted\n6. Authorize the connection to grant Claude access to your workspace\n\n![CleanShot 2026-01-20 at 14.11.12.png](/api/knowledge-base/images/7e884d67-b1b6-482f-9300-8d086900937e)\n\nYou’ll be asked to authorize access to your Unthread workspace. This uses secure OAuth authentication - your password is never shared with Claude.\n\n### ChatGPT\n\n**Prerequisites**\n\n- A ChatGPT plan or workspace that supports MCP connectors\n- An active Unthread account with access to the workspace you want to connect\n- The Unthread MCP server URL:\n\n```plaintext\nhttps://app.unthread.io/api/mcp\n```\n\n1. Open ChatGPT and sign in.\n2. Go to **Settings** and open the section for **Connectors**, **Tools**, or **MCP**.\n3. Choose **Add connector**, **Add tool**, or **Add MCP server**.\n4. Enter a name such as **Unthread** and paste in the server URL above.\n5. Save the connector and follow the prompt to connect your account.\n6. When redirected to Unthread, sign in if needed and approve access to your workspace.\n7. Return to ChatGPT after authorization completes.\n\n**Verify it works**\n\nStart a new chat and try a simple request such as:\n\n- “List my open conversations in Unthread.”\n- “Show me conversations from the last 7 days.”\n\nIf the connector is working, ChatGPT should be able to access Unthread data and respond using the MCP tools.\n\n### Claude Code (CLI)\n\n1. Open your Claude Code configuration file at `~/.claude.json`\n2. Add Unthread to the `mcpServers` section:\n\n```plaintext\n{\n \"mcpServers\": {\n \"unthread\": {\n \"url\": \"https://app.unthread.io/api/mcp\"\n }\n }\n}\n```\n\n3. Restart Claude Code\n4. When you first use an Unthread tool, you’ll be prompted to authenticate via your browser\n\n### Cursor\n\n**Option A**: Cursor Deeplink\n\nJust click this button!\n\n[![cursor-install-dark.svg](/api/knowledge-base/images/c32bbf61-9c5f-4a13-8573-89bf7f6239b5)](cursor://anysphere.cursor-deeplink/mcp/install?name=Unthread\\&config=eyJ1cmwiOiJodHRwczovL2FwcC51bnRocmVhZC5pby9hcGkvbWNwIn0=)\n\n**Option B**: OAuth (browser sign-in)\n\n1. Open **Cursor Settings** → **MCP** → **Add new global MCP server**\n2. This opens your `~/.cursor/mcp.json` file. Add Unthread to the `mcpServers` section:\n\n```plaintext\n{\n \"mcpServers\": {\n \"Unthread\": {\n \"url\": \"https://app.unthread.io/api/mcp\"\n }\n }\n}\n```\n\n3. Save the file and restart Cursor. The Unthread MCP should now show up in your Cursor Settings.\n4. When you first use an Unthread tool, you’ll be prompted to authenticate via your browser\n\n**Option C**: Hosted MCP (service account API key)\n\nIf you want to connect to Unthread’s hosted MCP using a service-account token, configure Cursor to use the Unthread API endpoint and attach the token as an HTTP header.\n\n1. Open `~/.cursor/mcp.json`\n2. Add an entry like this:\n\n```plaintext\n{\n \"mcpServers\": {\n \"unthread\": {\n \"url\": \"https://api.unthread.io/api/mcp\",\n \"headers\": {\n \"X-Api-Key\": \"MYKEY\"\n }\n }\n }\n}\n```\n\n## Example Prompts\n\nTry asking your AI assistant:\n\n### Monthly support analytics dashboard (prompt template)\n\n- “List my open conversations”\n- “Show me conversations from the last week”\n- “What’s our ticket volume trend this month?”\n- “Find the conversation about the billing issue”\n\nCopy/paste and replace the bracketed values:\n\n```text\nShow me a support dashboard for [month] using the Unthread MCP for project [project name or ID]. Include: total tickets, resolved count and resolution rate, open/in-progress breakdown, critical ticket count, mean and median response time, P95 response time, mean and median resolution time, weekly volume and resolved trend charts, response time trend by week, agent workload by tickets resolved, average resolution time per agent, priority breakdown (critical/high/medium/low), and channel mix (Slack/email/portal). Pull all data from the analytics API and highlight any key insights like workload concentration, mean vs. median gaps, or outlier agents.\n```\n\n## Troubleshooting\n\n### ”Authorization failed” error\n\nMake sure you’re signed in to Unthread with the correct account. The OAuth flow should open a browser window - if it doesn’t, check if pop-ups are blocked.\n\n## Security\n\n- **OAuth 2.0**: We use industry-standard OAuth 2.0 with PKCE for secure authentication\n- **No password sharing**: Your Unthread credentials are never shared with AI assistants\n- **Scoped access**: The AI assistant can only access data you have permission to view\n- **Revocable**: You can disconnect the integration at any time from your Unthread settings\n\nFor more details on our security practices, [visit**unthread.io/security**](http://visitunthread.io/security).\n","2026-01-20T19:09:51.298Z","2026-09-01T16:48:07.614Z","b6ce0da5-cd74-4b9b-afe6-e293bd22b2db",[],[],[],"Sentiment Scores","Conversations are automatically analyzed and assigned a sentiment score out of 100, with 100 being the most positive sentiment.\\\n\\\nSentiment 0->40 is ![:rage:](https://a.slack-edge.com/production-standard-emoji-assets/15.0/google-medium/1f621.png)\\\n\\\nSentiment >60 is ![:smile:](https://a.slack-edge.com/production-standard-emoji-assets/15.0/google-medium/1f604.png)","2026-05-12T20:59:21.098Z","2026-05-12T21:01:34.404Z","24a555a5-f6cb-4dea-97cd-0f313a11d356",[],[],[],"Introduction to Unthread AI","introduction-to-unthread-ai","## What is Unthread AI?\n\nUnthread AI uses the latest in GPT-based AI to scale up your team’s support capabilities.\n\n## AI Features\n\n### AI-Generated Responses\n\n![ai-autoresponse-phishing.png](/api/knowledge-base/images/b472497b-c5b8-4357-ba03-474b2929038d)\n\nUnthread AI can recommend a response to a question based on your existing documentation. From there, it can:\n\n- Suggest the response privately to the support rep\n- Reply directly as a bot to the customer message\n\nWe’ve got an [article dedicated to AI responses](https://docs.unthread.io/docs/unthread-ai/ai-generated-responses) where you can learn more.\n\n### Auto Set Ticket Type\n\n**AI selection guidance** can be customized for each ticket type. When **Auto Set Ticket Type** is enabled in the Project Setup under AI Features the ticket type will be set automatically. You can manually change the ticket type if needed. The Project or Channel **intake** setting required for Auto Set Ticket Type and pre-filling form fields is \"**Engage AI Agent**.\"\n\n![image.png](/api/knowledge-base/images/56a048ed-ca7c-4c7b-ae46-1a2881909271)\n\n![image.png](/api/knowledge-base/images/c2f6412d-5593-4a37-8f61-fe7260cb8fd5)\n\n### Automatic Tagging\n\n![ai-tags.png](/api/knowledge-base/images/03fd0432-c7a9-4bae-85b1-bd1ab09458f2)\n\n[Tags](https://docs.unthread.io/docs/unthread-ai/automatically-tagging-conversations-with-ai) are a great way to get deeper insights into the types of requests that your team is seeing. We commonly see tags like “Bug” or “Feature request” as well as more descriptive tags like “Backend service workers”. In your analytics tab, you can get a series of reports broken down by types of tags. Once you’ve created your tags, you can have Unthread AI automatically apply tags to conversations based on message content. Some things to note:\n\n- First, enable the auto-tagging feature in your dashboard\n- AI tags will only be applied when the conversation is created\n- You can manually adjust tags at any time to override\n\nSome best practices:\n\n- Use descriptive tag names\n- Add descriptions to tags to help the AI better understand what the tag is about\n- Check your “Analytics” tab to see how tags are trending\n\n### Generate Titles\n\nConversations appear in your inbox based on the title. Titles by default are generated by the content of the customer message, but AI-generated titles can create a short, descriptive title based on the message content. Example input:\n\n> Hi team! Do you have documentation on what is required on from our web developer in order to embed your live chat support widget into our website to start fielding requests there? I checked the documentation but didn’t see anything.\n\nAI-generated title:\n\n> Customer needs documentation to embed the live chat widget\n\n### Summarize Conversations\n\nConversation summaries are posted into the triage channel after a conversation is closed. These summaries are typically 2 to 3 sentences describing the customer and support rep messages and will note the resolution of the thread.\n\n### Surface Similar Conversations\n\nSimilar conversations will be available in the right panel of the conversation details page. You will be able to see the previous conversation’s question & resolution, and can easily click in to view the full thread.\n\n![similar-conversation.png](/api/knowledge-base/images/f680f5c1-1383-4439-a259-6949a3ba22aa)\n\n### Sentiment Analysis\n\nUnderstand your customers with a numerical score measuring the positivity of their tone when speaking with support reps.\n\n### Knowledge Base Management\n\nConnect your [Knowledge Base](https://docs.unthread.io/docs/knowledge-base/knowledge-base-setup) to Unthread, and we’ll be able to generate answers and gather feedback on which answers are missing in your docs.\n\n##\n\n## How do I get access?\n\nHead over to the “Settings” > “AI” tab from your Unthread dashboard, and from there, you’ll be able to enable AI features instantly.\n\n##\n\n## Security\n\nUnthread AI takes a privacy-first approach to leveraging LLMs.\n\n###\n\n## Unthread Servers\n\n- Your data is never used to train our own model\n- Your data is never used in AI generation of any other Unthread customer\n- Your data is always encrypted in transit and at rest\n- Your data is encrypted with a unique tenant key specific to your account\n\n###\n\n## Bring Your Own AI\n\nWe allow customers on higher plans to bring their own OpenAI accounts, giving you full control and transparency over AI behavior. Contact the Unthread team to use your own AI. To use your own model you can self service this through Workspace Settings --> AI --> AI model --> Use Custom Model.\n\nSupported models:\n\n- OpenAI\n- Google Gemini\n- Anthropic Claude\n- Grok by XAI\n- Mistral\n\n###\n\n## OpenAI\n\nUnthread integrates with OpenAI’s API for LLM functionality. We generate a separate workspace within OpenAI’s platform per tenant that keeps data completely isolated.\n\n- **Ownership**\n\n You own and control your data. You own your inputs and outputs (where allowed by law).\n\n- **Control**\n\n You decide who has access within your organization\n\n- **Security**\n\n Data encryption at rest (AES-256) and in transit between us and OpenAI, and between OpenAI and their service providers (TLS 1.2+)\n\nMore on OpenAI’s security and privacy policy [can be found here](https://openai.com/enterprise-privacy/).\n\nThis is all in addition to Unthread’s already strict, industry-leading, and SOC2-compliant security practices that can be found at [unthread.io/security](https://unthread.io/security)\n","2023-12-03T18:55:50.897Z","2026-08-28T17:10:05.745Z","b4e7688a-cd0c-48bd-8df3-3d0dd74b2769",[],[],[],"Connect Anthropic Claude through Google Vertex AI","connect-anthropic-claude-through-google-vertex-ai","Connect Unthread to Anthropic Claude models in your Google Cloud project through Google Vertex AI. Your Google Cloud account manages model access, quota, and inference charges.\n\n## Before you start\n\n- You need permission to manage your Unthread workspace settings.\n- A Google Cloud administrator must be able to enable APIs and Claude model access, grant permissions, and create a service-account JSON key.\n- Your Google Cloud project needs billing enabled and available quota for your chosen Claude model.\n\nThis guide covers the Google-managed Claude offering accessed through Vertex AI. Google may refer to Vertex AI as Agent Platform in its console and documentation.\n\n## 1. Enable Claude in Google Cloud\n\n1. Open the [Google Cloud console](https://console.cloud.google.com/) and select the project that will run your model requests. Copy its **project ID**.\n2. Enable the Vertex AI API (`aiplatform.googleapis.com`) for that project.\n3. Open Model Garden, find the Claude model you want to use, and click **Enable**. Have an authorized administrator complete any required provider terms or access approvals.\n4. Check the model's supported locations and copy its exact Vertex model ID. Enable each model you intend to use.\n\nFor example, Google's [Claude Sonnet 4.6 model page](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/partner-models/claude/sonnet-4-6) lists `claude-sonnet-4-6` and the `us-east5` location. Confirm current availability for your selected model before configuring it.\n\nSee Google's [Claude setup documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/claude/use-claude) for model enablement requirements.\n\n## 2. Create a service-account JSON key\n\n1. In Google Cloud, open **IAM & Admin → Service Accounts → Create service account**.\n2. Give it a descriptive name, such as `unthread-vertex-ai`, and click **Create and continue**.\n3. Grant the account the **Vertex AI User / Agent Platform User** role (`roles/aiplatform.user`) on the project that will run inference, then finish creating the account. A custom role must include `aiplatform.endpoints.predict`. See [Anthropic's Google-managed Claude requirements](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed).\n4. Open the service account, select **Keys → Add key → Create new key**, choose **JSON**, and click **Create**.\n5. Store the downloaded file securely. You will paste its complete contents into Unthread in the next step.\n\nThe JSON contains a private key. Enter it only in Unthread's credential field; do not include it in tickets, screenshots, or email. If your organization blocks service-account key creation, consult your Google Cloud administrator and Unthread support before proceeding.\n\nGoogle documents [service-account creation](https://cloud.google.com/iam/docs/service-accounts-create) and [JSON key creation](https://cloud.google.com/iam/docs/keys-create-delete) in more detail.\n\n## 3. Configure the model in Unthread\n\n1. Open **Workspace Settings → Artificial Intelligence → AI Model**.\n2. Click **Use a custom model**, or edit your existing custom configuration.\n3. Choose **Google Vertex** as the provider.\n4. Fill in the fields below.\n5. Click **Save custom model**, or **Save model settings** when editing.\n\n| Field | What to enter | Example |\n| --- | --- | --- |\n| Provider | Google Vertex | Google Vertex |\n| Model | `anthropic/` followed by the exact Vertex Claude model ID | `anthropic/claude-sonnet-4-6` |\n| Google Cloud Project | Your project ID, rather than its display name or numeric project number | `my-google-cloud-project` |\n| Google Cloud Location | A location supported by your selected model | `us-east5` |\n| Service account JSON | The complete contents of the downloaded JSON key file | Paste the JSON object, including its opening and closing braces |\n\n**Keep the** `anthropic/` **prefix in Unthread's Model field.** It tells Unthread to use Claude through Vertex. Preserve any version suffix included in the Vertex model ID. The **Anthropic** provider option connects to Anthropic's direct API; this setup uses **Google Vertex**.\n\nThe credential must be the service-account JSON, rather than a Google AI Studio key, an Anthropic API key, a file path, or only the private-key value. When editing the same provider, you can leave the credential field blank to reuse the saved credential.\n\n## 4. Test the connection\n\nUnthread checks model access before saving, which can make a small model request. After saving, run an AI action that uses your workspace's configured model, such as generating a suggested response, and confirm that it returns a response. Test any AI features with separate model overrides as well.\n\n## Troubleshooting\n\n- **Permission denied / 403:** Confirm that the service account has the required inference permission on the project entered in Unthread, the API is enabled, and the selected Claude model is enabled. Check organization policies that may restrict access.\n- **Model not found / 404:** Check the exact Vertex model ID, its version suffix if applicable, the `anthropic/` prefix, and the selected location's support for that model.\n- **Invalid credentials or JSON:** Paste the complete, unmodified JSON file. It should include `type: service_account`, `project_id`, `client_email`, and `private_key`. Confirm that the account and key are active.\n- **Quota exceeded / 429:** Review the selected model's quota and available capacity in Google Cloud, confirm billing is active, and retry or request additional quota as appropriate.\n- **Google Vertex is unavailable in your workspace:** Contact Unthread support.\n\nWhen contacting support, share the error message, model ID, location, and approximate request time. Keep the JSON key and private key out of your message.\n\n## Replace credentials or return to the default model\n\nTo rotate credentials, create a replacement JSON key, save it in the same Unthread configuration, and verify an AI request succeeds before deleting the old key in Google Cloud. To switch back to Unthread-managed model settings, choose **Use Unthread default** on the AI Model page.","2026-10-23T14:46:27.451Z","e7a4f6a0-d27c-4f22-8f70-db0cf91abeb9",[],[],[],"Connect Amazon Bedrock with an IAM role","connect-amazon-bedrock-with-an-iam-role","Connect Unthread to Amazon Bedrock in your AWS account using an IAM role. You keep control of the role and its permissions; you do not need to give Unthread an AWS access key or Bedrock API key. Unthread assumes your role to obtain temporary credentials for model requests.\n\n## Before you start\n\n- An Unthread workspace administrator must configure the connection.\n- An AWS administrator must be able to create an IAM role, edit its trust policy, and attach permissions in the account that will run Bedrock.\n- Choose a Bedrock model or inference profile and a supported AWS region. Your account must have the required model access, subscriptions or provider approvals, and available quota.\n- Your AWS account owns inference usage and charges. This integration supports commercial AWS regions and public AWS endpoints; GovCloud, China, and private-only endpoints are not supported.\n\n## 1. Copy your workspace’s AWS setup values\n\n1. In Unthread, open **Workspace Settings → Artificial Intelligence → AI Model**.\n2. Choose **Amazon Bedrock** as the provider and **IAM role** as the authentication method.\n3. Copy the displayed **Unthread AWS principal**, **External ID**, and **Customer role trust policy**.\n\nIf IAM role is unavailable or the page says IAM authentication is not configured by Unthread, contact Unthread support before continuing.\n\nFor production, the Unthread AWS principal is arn:aws:iam::186015733989:user/unthread-bedrock. The external ID is unique to your Unthread workspace; find it in the External ID field on this AI Model page and copy it exactly into the trust policy. There is no single external ID shared by all customers. Staging uses a different principal and external ID, so always use the values shown in the environment you are connecting.\n\n## 2. Create the role in your AWS account\n\n1. Open the AWS IAM console and go to **Roles → Create role**.\n2. Select **Custom trust policy** and paste the complete trust policy copied from Unthread.\n3. Continue through the permissions step; you will attach a scoped policy in the next section.\n4. Name the role, for example **UnthreadBedrock**, review it, and create it.\n5. Copy the role’s ARN from its summary. It should look like arn:aws:iam::123456789012:role/UnthreadBedrock.\n\n```plaintext\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [{\n \"Effect\": \"Allow\",\n \"Principal\": { \"AWS\": \"arn:aws:iam::186015733989:user/unthread-bedrock\" },\n \"Action\": \"sts:AssumeRole\",\n \"Condition\": {\n \"StringEquals\": { \"sts:ExternalId\": \"\" }\n }\n }]\n}\n```\n\nKeep the exact principal and external-ID condition. Do not add another statement allowing Unthread to assume this role without that condition. Unthread checks that missing and incorrect external IDs are denied. See [AWS guidance on third-party access and external IDs](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html).\n\nKeep the role’s maximum session duration at one hour or longer. Unthread requests one-hour sessions and refreshes credentials automatically.\n\n## 3. Allow your selected Bedrock models\n\nOn the role’s **Permissions** tab, choose **Add permissions → Create inline policy → JSON**. Start with the following policy, replace the resource placeholder, and save it with a name such as **InvokeSelectedBedrockModels**.\n\n```plaintext\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [{\n \"Effect\": \"Allow\",\n \"Action\": [\n \"bedrock:InvokeModel\",\n \"bedrock:InvokeModelWithResponseStream\"\n ],\n \"Resource\": [\"\"]\n }]\n}\n```\n\nFor a directly invoked foundation model, use its actual resource ARN, in the form `arn:aws:bedrock:REGION::foundation-model/MODEL_ID`. The account field is empty for foundation models. Confirm that the model supports direct invocation in your selected region.\n\nFor an inference profile, include the profile ARN and the underlying foundation-model ARNs for every region required by that profile. A policy containing only the profile ARN is insufficient. Organization policies and permission boundaries must also allow the required regions and invocation actions. Follow [AWS’s inference-profile permissions guide](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-prereq.html) for your chosen profile.\n\nGrant only the resources you intend to use. AdministratorAccess and Bedrock management permissions are not needed for this connection.\n\n## 4. Save the connection in Unthread\n\n1. Return to the AI Model configuration in Unthread.\n2. Enter the **Customer role ARN** from step 2.\n3. Enter the **AWS region** where requests should be sent, such as `us-east-1`.\n4. Enter the exact Bedrock **model or inference-profile identifier**. If your Unthread configuration uses the Anthropic route, retain the `anthropic/` prefix before the AWS identifier. The prefix belongs only in Unthread’s model field, not in AWS IAM resource ARNs.\n5. Save the configuration.\n\n**Role access verified** means Unthread successfully assumed the role with your external ID and confirmed that missing and incorrect IDs were denied. Saving does not invoke the model or verify model permissions. If validation fails, your existing connection is preserved.\n\n## 5. Test a real AI request\n\nRun an AI action in Unthread that uses this configuration and confirm you receive a model response. Test streaming where your workflow uses it. If your workspace has model overrides for particular AI features, test those features too.\n\n## Troubleshooting\n\n- **Could not verify AWS role access:** check the role ARN, exact principal, and external ID. Confirm you used values from the correct workspace/environment and that organization policies or permission boundaries do not deny role assumption.\n- **The role must reject missing and incorrect external IDs:** remove or restrict any trust-policy statement that lets Unthread assume the role without the exact external ID.\n- **Role access verified, but AI requests fail:** check model access, the selected region and identifier, invocation permissions, profile destination regions, and available quota. Role trust and model access are separate checks.\n- **Model requires an inference profile:** use a supported profile identifier and add the profile plus its underlying model resources to the role’s permissions.\n\nWhen contacting support, share the error message, AWS region, model/profile identifier, and approximate request time. Never send AWS secret keys or session tokens.\n\n## Remove access\n\nTo stop new role sessions, remove Unthread from the role’s trust policy. Existing temporary sessions may remain valid until they expire. To invalidate existing sessions, follow [AWS’s role-session revocation procedure](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html). Unthread does not automatically fall back to an API key when IAM authentication fails.","2026-09-23T15:30:11.109Z","2026-09-25T21:22:03.734Z","2489c55d-dedc-4deb-ae9a-5203b52a6169",[],[],[],"Automatically Tagging Conversations with AI","automatically-tagging-conversations-with-ai","You can create your own custom set of tags and allow Unthread AI to automatically apply them to conversations.\n\n## Creating Tags\n\nTo create a new tag, click “Tags” in the left menu, then select the “Create Tag” button in the top right.\n\nEnter the Name and Description, and select the Project it should apply to. By default, the tag will apply to all projects. The option to “Allow AI to apply tag automatically” is enabled by default and is recommended, as it will maximize Unthread’s capabilities. Only disable this option if necessary.\n\n![ai-tags-create.png](https://firebasestorage.googleapis.com/v0/b/trnout-co.appspot.com/o/unthread-unthread-e4pm8%2Fknowledge-base%2Fai-tags-create.png?alt=media)\n\n## Managing Tags on a Conversation\n\nConversations will have tags applied automatically, and you can manually update them after the fact.\n\n## Viewing Analytics\n\nOne of the primary benefits of AI tagging is that you will have reports generated that indicate trends of common tags over time.\n\nUnthread analytics supports **filtering and breakdowns by tags**, and you can combine multiple reports into a dashboard using the dashboard builder.\n\n- Reports can be **filtered by tags**\n- Reports can **grouped by tags**\n- Tag analytics can show **trends of common tags over time**\n\n![tag-analytics.jpg](https://firebasestorage.googleapis.com/v0/b/trnout-co.appspot.com/o/unthread-unthread-e4pm8%2Fknowledge-base%2Ftag-analytics.jpg?alt=media)\n\n## Can Tags be applied retroactively?\n\nYes.\n\n- Tags can be **manually updated “after the fact”** on a conversation. (So you can go back to older tickets and add/remove tags.)\n- If you’re using **AI auto-tagging**, note that **AI tags are only applied when the conversation is created**, but you can still manually adjust tags later to override.\n\nIf you need to apply a tag to a large set of existing conversations in bulk, the API supports assigning a tag to multiple conversations via an endpoint that takes an array of conversation IDs.","2023-12-03T18:55:51.039Z","2026-04-21T14:32:41.803Z","178e576c-6c1f-44b5-9323-1870313efb77",[],[],[],"AI-Generated Responses","ai-generated-responses","## ![auto-response.gif](https://firebasestorage.googleapis.com/v0/b/trnout-co.appspot.com/o/unthread-unthread-e4pm8%2Fknowledge-base%2Fauto-response.gif?alt=media)\n\n## Introduction\n\nWith Unthread AI, you can use your existing knowledge base to train an AI model to provide helpful responses and relevant documentation to customers. AI works with [Slack](https://docs.unthread.io/docs/setting-up-your-account/connecting-to-slack), [email](https://docs.unthread.io/docs/email-support/email-support), and [in-app chat](https://docs.unthread.io/docs/in-app-support/in-app-chatsupport) support so you can automate your responses to customers across any channel.\n\n## Training AI on Your Knowledge Base\n\nOnce you’ve enabled this feature, you’ll see a tab under “Settings” > “Knowledge Base” where you can connect your documentation. We have an article about how to set up various source of knowledge\n\n📖 [Knowledge Base Syncing](https://docs.unthread.io/docs/knowledge-base/knowledge-base-setup)\n\n### Testing Responses\n\nYou can also click “Test Responses” and enter in some sample text to get a preview of what the AI will generate.\n\n## **AI-Generated Responses**\n\nYou can have the AI automatically respond to a customer question with a human-friendly response via the**Auto-responder**.\n\n💡*As a reminder, the Auto-responder is a helpful tool to automatically reply in a thread or a new email with a custom message, which can be dynamically set based on your hours of operation.*\n\n### AI-Generated Responses in the Channel\n\n![ai-gen-response.png](https://firebasestorage.googleapis.com/v0/b/trnout-co.appspot.com/o/unthread-unthread-e4pm8%2Fknowledge-base%2Fai-gen-response.png?alt=media)\n\n### Auto-closing Conversations\n\nAfter the AI sends a response in the channel, the customer will be presented with a thumbs up or thumbs down to provide feedback on the answer. A thumbs up will auto-close the conversation, marking it as resolved.\n\n### Enabling Auto-responder Replies\n\nFrom the Slack settings or your Email inbox settings, you can enable the AI-generated responses in the “auto-responder” section.\n\n![auto-responder-ai.png](https://firebasestorage.googleapis.com/v0/b/trnout-co.appspot.com/o/unthread-unthread-e4pm8%2Fknowledge-base%2Fauto-responder-ai.png?alt=media)\n\n### White-labeling the Bot\n\nYou can set your own custom name and image for the bot that replies. To set this, go to “Settings” > “General”, and you’ll see an option to set the “support name & logo”.\n\n## Suggesting Responses to Support Reps\n\nIn the case that you don’t want your customers to be interacting directly with the AI, you can instead **suggest responses** to support reps privately. This is a great way to preview what the AI-generated response would be and make edits before sending.\n\n### Suggesting a Response in Slack\n\nTo generate a suggested response from inside of Slack, you can do one of the following:\n\n- Apply the ”🤔” reaction to the message you’d like a response to\n- Use a “message shortcut” called “Suggest AI Response”\n\nIn either case, you will get a private message inline with a human-friendly response as well as links to any relevant documentation\n\n![suggest-response.png](https://firebasestorage.googleapis.com/v0/b/trnout-co.appspot.com/o/unthread-unthread-e4pm8%2Fknowledge-base%2Fsuggest-response.png?alt=media)\n\n### Suggesting a Response in Your Web Inbox\n\nFrom the web dashboard, when managing a conversation, you can suggest a respnose by navigating to the conversation details page, and clicking ”✨ Suggest response”.\n\nℹ️ *If you don’t see a “Suggest response” button, you likely need to go to your “Settings” > “AI” page and enable AI responses from there*\n\n## Analytics\n\n![kb-analytics.png](https://firebasestorage.googleapis.com/v0/b/trnout-co.appspot.com/o/unthread-unthread-e4pm8%2Fknowledge-base%2Fkb-analytics.png?alt=media)\n\nTo view feedback from end users on the quality of your AI-generated responses, head over to “Analytics” > “AI” from your Unthread dashboard.\n\nFrom there, you’ll see the thumbs up or thumbs down reactions by end users, as well as examples where the AI wasn’t able to find any documentation.\n\n💡***Coming soon:*** *we’ll also suggest improvements to your docs based on the conversation history that takes place!*","2023-12-03T18:55:51.532Z","2026-05-13T19:50:52.213Z","702292cb-0523-4cb8-bc3f-05583306b466",[],[],[],"unthread-ai","lightbulb","articleCount",9,"parentId","2025-09-09T20:08:33.282Z","2025-10-08T20:22:15.795Z","cspNonce","1653d74a8b783f3505d327c1b72e27e7401b8b1772e0a74d7bfd934f54160219","firebaseConfig",{"_1250":1251,"_1252":41,"_140":1253},"session",{"_1245":1246,"_1247":27},"inAppChat","mixpanelToken","cc23843c498db1553f595eae3fae57d7","sentryDsn","environment","prd","theme","isMac","isEmbed","embedConfig","userProfile","projects",[1236],[252,253,254,255,256,257,258,259,260,261,262,263,264,265,266,267],"uncategorizedArticles",[],"hasNavigationError",{"_85":1219,"_134":1220,"_59":-5,"_71":1221,"_270":271,"_226":-5,"_140":-5,"_141":1222,"_143":1223,"_22":61,"_24":25,"_224":274,"_12":1224,"_276":1225},{"_85":1163,"_134":1164,"_59":-5,"_71":36,"_270":271,"_226":-5,"_140":-5,"_141":1165,"_143":1166,"_22":62,"_24":25,"_224":1167,"_12":1168,"_276":1169},{"_85":1058,"_134":1059,"_59":-5,"_71":223,"_270":271,"_226":-5,"_140":-5,"_141":1060,"_143":1061,"_22":1062,"_24":25,"_224":1063,"_12":1064,"_276":1065},{"_85":1021,"_134":1022,"_59":-5,"_71":1023,"_270":271,"_226":-5,"_140":-5,"_141":1024,"_143":1025,"_22":1026,"_24":25,"_224":570,"_12":1027,"_276":1028},{"_85":123,"_134":222,"_59":-5,"_71":223,"_270":271,"_226":-5,"_140":-5,"_141":227,"_143":228,"_22":122,"_24":25,"_224":225,"_12":983,"_276":984},{"_85":945,"_134":946,"_59":-5,"_71":947,"_270":271,"_226":-5,"_140":-5,"_141":948,"_143":949,"_22":950,"_24":25,"_224":570,"_12":951,"_276":952},{"_85":687,"_134":688,"_59":-5,"_71":689,"_270":271,"_226":-5,"_140":-5,"_141":690,"_143":691,"_22":63,"_24":25,"_224":328,"_12":692,"_276":693},{"_85":618,"_134":619,"_59":-5,"_71":620,"_270":271,"_226":-5,"_140":-5,"_141":621,"_143":622,"_22":623,"_24":25,"_224":624,"_12":625,"_276":626},{"_85":603,"_134":604,"_59":-5,"_71":83,"_270":271,"_226":-5,"_140":-5,"_141":605,"_143":606,"_22":607,"_24":25,"_224":274,"_12":608,"_276":609},{"_85":564,"_134":565,"_59":-5,"_71":566,"_270":271,"_226":-5,"_140":-5,"_141":567,"_143":568,"_22":569,"_24":25,"_224":570,"_12":571,"_276":572},{"_85":467,"_134":468,"_59":-5,"_71":469,"_270":271,"_226":-5,"_140":-5,"_141":470,"_143":471,"_22":472,"_24":25,"_224":225,"_12":473,"_276":474},{"_85":77,"_134":440,"_59":-5,"_71":79,"_270":271,"_226":-5,"_140":-5,"_141":441,"_143":442,"_22":443,"_24":25,"_224":444,"_12":445,"_276":446},{"_85":322,"_134":323,"_59":-5,"_71":324,"_270":271,"_226":-5,"_140":-5,"_141":325,"_143":326,"_22":327,"_24":25,"_224":328,"_12":329,"_276":330},{"_85":305,"_134":306,"_59":307,"_71":-5,"_270":271,"_226":-5,"_140":-5,"_141":308,"_143":308,"_22":309,"_24":25,"_224":274,"_12":310,"_276":311},{"_85":288,"_134":289,"_59":-5,"_71":-5,"_270":271,"_226":-5,"_140":-5,"_141":290,"_143":291,"_22":292,"_24":25,"_224":274,"_12":293,"_276":294},{"_85":268,"_134":269,"_59":-5,"_71":-5,"_270":271,"_226":-5,"_140":-5,"_141":272,"_143":272,"_22":273,"_24":25,"_224":274,"_12":275,"_276":277},"Personal Settings and Notifications","personal-settings-and-notifications","articleSort","alphabetical","2026-04-29T13:36:55.700Z","53c910af-e807-4764-990f-1da7d256356b",1,[278],"subCollections",[],{"_57":279,"_134":280,"_136":-5,"_137":281,"_139":273,"_140":-5,"_141":282,"_143":283,"_22":284,"_24":25,"_145":285,"_147":-5,"_148":286,"_150":287},"Personal Notification Settings","personal-notification-settings","### How to change personal notification settings\n\nOnce logged in as an Unthread Agent, Owner, or Admin you can change your notification settings by clicking your user profile in the top right of any page in the Unthread UI.\n\n![Unthread-04-29-2026_09_42_AM.png](/api/knowledge-base/images/686ab8f6-200b-40f4-8931-981b3b80e178)\n\nSelect Notification settings to adjust your preferences.\n\n![image.png](/api/knowledge-base/images/82dfa2b8-048b-4548-84a6-14294a222d1b)\n\n## Stop following a conversation (Unthread dashboard)\n\nIf you’re getting Unthread notifications for a conversation you no longer want to follow, open the conversation in the Unthread web dashboard and remove yourself as a follower from the right-hand side of the conversation page.","2026-04-29T13:42:34.207Z","2026-05-15T18:45:59.245Z","aec5c3c2-9891-49bc-bb14-3c31dbcf6da5",[],[],[],"Knowledge Base","knowledge-base","2026-04-27T22:16:15.140Z","2026-05-01T15:47:22.779Z","73642454-3483-4fd5-9712-56b2e6eee071",[295],[],{"_57":296,"_134":297,"_136":-5,"_137":298,"_139":292,"_140":-5,"_141":299,"_143":300,"_22":301,"_24":25,"_145":302,"_147":-5,"_148":303,"_150":304},"Knowledge Base Setup","knowledge-base-setup","Connect your documentation to provide better answers for AI-generated responses or for suggesting responses to your support reps. Let’s walk through how to set it up!\n\n![knowledgebase-list.png](/api/knowledge-base/images/956286a3-1cef-4b85-a573-47ca06c9179d)\n\n## Connecting to Your Existing Documentation\n\nUnthread can sync documentation from any web-based documentation system automatically by crawling pages and adding them to your knowledge base. To do this, head over to the Dashboard then click “Knowledge” on the left then select “Sources” finally “Add Source”\n\n### Adding Public Documentation Sites\n\n![kb-add-public.png](/api/knowledge-base/images/3ec432fe-8947-45c9-8ed0-5c9a7b640f94)\n\nTo sync in a public-facing website of documentation, you can enter the base URL of the page, and Unthread AI will automatically crawl and ingest all of the subpages within it. Advanced options include the ability to add certain root URLs to an allowlist or blocklist.\n\n⚠️Some large public documentation does not need to be added as a source and scraped because all AI models already have awareness of the information from it being publicly available across the web. For examples, URLs from Apple's public-facing website of documentation can't, and do not need to be added and scraped as a webpage source in your workspace.\n\n### Adding Internal Documentation\n\nFor internal wikis, you’ll want to use our native integrations with your platform of choice to provide us access to the correct pages to sync. In each case, you can choose the root folder or URL and have Unthread AI scrape all subpages. Supported native integrations:\n\n- Google Drive\n- Notion\n- Confluence\n- Wiki.js\n- Coda\n- SharePoint\n- Freshservice\n- GitHub\n- Airtable\n\n### Workspace-level vs. project-level sources (and duplicates)\n\nYou can keep a workspace-level (global) knowledge base while also allowing each project/team to create their own Google Drive / Notion sync job.\n\n- **Global knowledge**: It can be helpful to keep global knowledge, but consider using it more sparingly.\n- **Project-level knowledge**: Teams can connect and manage their own sources for their project.\n\nGoogle IAM accounts\n\nYou should be able to reuse the same Google IAM account across projects. When connecting a Google Drive source, teams can provide the same IAM credentials when they connect.\n\n### Article visibility settings\n\n- **Status:** Use inactive status for articles that are still being drafted and are not ready for use.\n- **Publish:** When published, the article can appear in the customer portal and customer facing links. When unpublished, the article can still guide bot answers internally, but customers will not see the article, citation name, or link to the article. \n- **Who can read:** When user groups are selected here the article visibility will be limited to these user groups.\n- **Channels:** Select channels to restrict visibility to specific channels.\n\n### Using Unthread AI “built-in” knowledge (public documentation)\n\nBy default, Unthread’s bot prompt is configured to only use knowledge sources that are connected in your Unthread **Knowledge** section. This is to prevent the bot from answering outside the scope of your company.\n\nIf you want Unthread AI to also use its built-in knowledge about tools (for example, answering basic questions about Google Drive using publicly available documentation), ask the Unthread team to enable this via a backend setting.\n\nAlternatively, you can connect your own documentation sources in Unthread and keep the bot restricted to those sources.\n\n### Freshservice Knowledge Base: “Delete stale articles”\n\nWhen syncing a **Freshservice Knowledge Base** source, the **Delete stale articles** option only affects the copies of articles stored in **Unthread**.\n\n- If enabled, Unthread will delete the corresponding article record in Unthread when the article has been deleted in Freshservice.\n- This does **not** delete anything in Freshservice.\n\nMost teams enable this option to avoid stale articles remaining searchable in Unthread.\n\n### Adding One-off Articles\n\nIf you’d like to add individual articles or Q&As to your knowledge base, click to the “Text” option when adding to your knowledge base. From here, you can write a custom title and content, while optionally also including a relevant link if a customer asks this question.\n\n### Keeping Things Up to Date\n\nAfter uploading, you will see a list of documentation sets and the date that the documentation was last synced. If you make a change and need it to go live immediately, you can also click the “Re-run sync” to immediately refresh the list.\n\n## Testing Responses\n\nAfter you’ve connected your documentation, you can see how the AI will generate responses for you. From the Knowledge Base tab, click the “Test response” button. It will present you with a text box to enter a prompt, and hitting submit will generate a response as well as surface the articles used to generate the answer.\n\n![image.png](/api/knowledge-base/images/d3d7454d-cf9e-440b-94d2-01627bd65b48)\n\n## Learning From Previous Conversations\n\nAs you manage support tickets through Unthread, you’ll likely start answering the same question and you’ll want to reference that in future answers.\n\n### Generating Articles\n\nAs you close out a conversation (marking it as resolved), the system automatically detect if the answer is not yet captured in your knowledge base. If not, we’ll generate a draft article using AI that you can edit before storing to your knowledge base for future use!\n\n![generate-article.gif](/api/knowledge-base/images/1b12be66-eb5a-4c7c-8397-e7bafb1f7548)\n\n### Reviewing Suggestions\n\nYou can review the recommended articles to create by navigating to “Knowledge” > “Suggestions”. This will show you a history of resolved conversations not yet captured in your knowledge base. As you create articles, they’ll automatically be removed from the list.\n\n- If a user is an **organization Admin** but can’t see anything in a specific project’s **Knowledge → Suggestions** tab, make sure they are also added as a **member of that project**.\n- In the project, go to **Setup → Members** and add the user.\n\n## Analytics\n\nTo view the history of responses generated and feedback on any of the documents used in your replies, you can see the AI analytics section under the [AI responses](https://docs.unthread.io/docs/analytics/ai-analytics#ai-generated-response-history) section.\n\n## Enabling AI responses\n\nAI responses can be enabled across Slack, email, in-app chat, and Microsoft Teams. We have an article specifically on how to leverage the Auto-Responder for this:\n\n📖 [*AI-Generated Responses*](https://docs.unthread.io/docs/unthread-ai/ai-generated-responses)","2023-12-03T18:55:51.389Z","2026-09-21T21:36:21.301Z","bc59ca2e-64e8-482f-9f9a-6e162db8fed2",[],[],[],"Global Workspace Settings","global-workspace-settings","The settings that apply to your Unthread workspace at the highest level. This includes administrative account management functionality along with other settings.","2026-04-23T15:32:33.531Z","a2145e34-f8e1-4ecb-b1ff-b580331d1d4f",[312],[],{"_57":313,"_134":314,"_136":-5,"_137":315,"_139":309,"_140":-5,"_141":316,"_143":317,"_22":318,"_24":25,"_145":319,"_147":-5,"_148":320,"_150":321},"Accounts","accounts","### What are Accounts?\n\n**Accounts** are used to define **external customer accounts** when Unthread is being used with customers external to your organization. You can add **Accounts from the Workspace Settings --> Accounts**.\n\n### What settings are defined at the Account level?\n\n- **Account Name:** Name of the external customer organization that will be visible on tickets.\n- **Account Tags:** Optional Tags you can add to an Account for filtering, reporting, SLAs, and automations.\n- **Associated email domain(s)** of the Account organization: The email domain matches new tickets to the correct customer Account.\n- **Associated Slack Channels** (#account name-Unthread): All shared slack channels between your organization and the customer account that Unthread has been added to.\n- **HubSpot Integration & Synced CRM contacts** if applicable: Our [HubSpot integration ](https://docs.unthread.io/docs/integrations/hubspot)enables syncing of the HubSpot Account configuration to Unthread Accounts and pushes tracked Slack conversations into HubSpot in the Account activity feed.\n- **SLA Override Configuration:** Use this option to create an SLA specific to a customer Account rather than using the Project or Channel level SLA settings.\n- **Primary and Secondary Support Representatives** defined for this Account within your organization: You can utilize the primary and secondary support representatives designated in the Account settings in your SLAs to route tickets to them first, defer to the secondary representative when the primary one is unavailable, and in automations should you wish to do thinks like send message alerts to these representatives about Account ticket activity.\n- **Account Admins** designated within the customer Account: This provisions external users with permission to view all tickets in this account.\n\n![image.png](https://firebasestorage.googleapis.com/v0/b/trnout-co.appspot.com/o/unthread-unthread-e4pm8%2Fknowledge-base%2Fe05a794e-53ab-462d-bb55-f5c297c3a2c3.png?alt=media)\n\n### Accounts and the External Customer Portal\n\nIf you enable your Unthread hosted [External Customer Portal ](https://docs.unthread.io/docs/in-app-support/customer-portal-overview)and require authentication for your external customers to access the portal, one of the authentication options is to \"**Restrict Login to Account Domains**.\" When enabled, only individuals using an email domain associated with one or more of your **Accounts** will be able to access the External Customer Portal via authentication.\n\n![image.png](https://firebasestorage.googleapis.com/v0/b/trnout-co.appspot.com/o/unthread-unthread-e4pm8%2Fknowledge-base%2F8dec1250-bd8b-4ee1-81d2-464013752e69.png?alt=media)\n\n### How to Update or Delete an Account\n\n\\*Note that only Unthread Administrators and Owners within your organization can Add, Update, and Delete Accounts\n\n- Click the **Account name** to open the Account details modal\n- Update any **Account fields** an click **save to update**\n- Use the **trashcan icon** on the bottom right of the Account details modal to **delete** the Account","2026-04-23T15:59:46.459Z","2026-05-19T13:35:59.659Z","73d94f1f-ae9c-46bd-8333-8fdab2daf7bd",[],[],[],"FAQs","faqs","help-circle","2025-09-24T21:44:22.729Z","2025-10-08T20:27:22.787Z","f10863c7-8fe8-42f4-9112-ea23db1ca8e4",11,[331,332,333,334,335,336,337,338,339,340,341],[],{"_57":431,"_134":432,"_136":-5,"_137":433,"_139":327,"_140":-5,"_141":434,"_143":435,"_22":436,"_24":25,"_145":437,"_147":-5,"_148":438,"_150":439},{"_57":422,"_134":423,"_136":-5,"_137":424,"_139":327,"_140":-5,"_141":425,"_143":426,"_22":427,"_24":25,"_145":428,"_147":-5,"_148":429,"_150":430},{"_57":413,"_134":414,"_136":-5,"_137":415,"_139":327,"_140":-5,"_141":416,"_143":417,"_22":418,"_24":25,"_145":419,"_147":-5,"_148":420,"_150":421},{"_57":405,"_134":-5,"_136":-5,"_137":406,"_139":327,"_140":-5,"_141":407,"_143":408,"_22":409,"_24":25,"_145":410,"_147":-5,"_148":411,"_150":412},{"_57":396,"_134":397,"_136":-5,"_137":398,"_139":327,"_140":-5,"_141":399,"_143":400,"_22":401,"_24":25,"_145":402,"_147":-5,"_148":403,"_150":404},{"_57":387,"_134":388,"_136":-5,"_137":389,"_139":327,"_140":-5,"_141":390,"_143":391,"_22":392,"_24":25,"_145":393,"_147":-5,"_148":394,"_150":395},{"_57":378,"_134":379,"_136":-5,"_137":380,"_139":327,"_140":-5,"_141":381,"_143":382,"_22":383,"_24":25,"_145":384,"_147":-5,"_148":385,"_150":386},{"_57":369,"_134":370,"_136":-5,"_137":371,"_139":327,"_140":-5,"_141":372,"_143":373,"_22":374,"_24":25,"_145":375,"_147":-5,"_148":376,"_150":377},{"_57":360,"_134":361,"_136":-5,"_137":362,"_139":327,"_140":-5,"_141":363,"_143":364,"_22":365,"_24":25,"_145":366,"_147":-5,"_148":367,"_150":368},{"_57":351,"_134":352,"_136":-5,"_137":353,"_139":327,"_140":-5,"_141":354,"_143":355,"_22":356,"_24":25,"_145":357,"_147":-5,"_148":358,"_150":359},{"_57":342,"_134":343,"_136":-5,"_137":344,"_139":327,"_140":-5,"_141":345,"_143":346,"_22":347,"_24":25,"_145":348,"_147":-5,"_148":349,"_150":350},"Unthread outbound IP addresses for firewall allowlisting","unthread-outbound-ip-addresses-for-firewall-allowlisting","Traffic from Unthread may come from any of the following outbound IP addresses. If your endpoint restricts inbound traffic by source IP, allowlist all of them:\n\n- 34.135.70.193\n- 34.134.133.208\n- 34.28.221.26\n- 34.69.152.47\n- 52.34.139.153\n- 54.69.127.183\n- 44.247.133.183\n- 52.26.211.56","2026-09-03T18:56:10.198Z","2026-09-09T14:00:08.110Z","f85205ba-e4b9-4b6f-ace7-ab8ff555e0ea",[],[],[],"Understanding Ticket Types, Tags, and Custom Fields in Unthread","understanding-ticket-types-tags-and-custom-fields-in-unthread","This article provides clarity on the usage of Ticket Types, Tags, and Custom Fields in Unthread, as well as the meaning of \"Submitted By\" in the Inbox view.\n\n### Ticket Types vs. Tags\n\n- [**Ticket Types**](https://docs.unthread.io/docs/conversational-ticketing/ticket-types): These are used for categorizing conversations and allow for custom attributes to be associated with each type. This involves manual selection via dropdowns or other inputs.\n- **Tags**: These are simpler categorizations that can be applied to conversations and customers. Tags can be set manually or automatically by AI.\n- **Recommendation**: Use Ticket Types if custom attributes are needed; otherwise, Tags are a streamlined option for categorization.\n\n### \"Submitted By\" Definition\n\n- The \"Submitted By\" field in the Inbox view refers to the initiator of the conversation.\n- This can be used to track individual initiators and analyze the topics they frequently address by filtering analytics by submitter and viewing the breakdown by Tags.\n\n### Custom Fields vs. Tags in the Customer View\n\n- **Custom Fields**: These are custom profile attributes that can be set up and viewed when managing a conversation.\n- **Customer Tags**: These are standard categorizations for accounts, useful for custom filtering and reporting.\n\nBy understanding these features, you can effectively categorize and analyze conversations and customer interactions in Unthread.","2024-12-17T15:34:18.585Z","2026-05-13T21:41:17.024Z","9417c561-404f-4ee3-84d8-27b689eb8169",[],[],[],"Tracking Time Spent by Assignee on Tickets","tracking-time-spent-by-assignee-on-tickets","To determine how much time each engineer spends on a specific ticket, you can utilize the \"waiting on agent time\" metric. This metric provides insights into the duration an agent is actively engaged with a ticket. By analyzing this data, you can effectively monitor and manage the time allocation of engineers on individual tickets.","2025-03-06T20:55:24.411Z","2025-10-30T18:39:41.781Z","43f7a70b-208a-40de-99a8-649e1a216420",[],[],[],"Snowflake integration: service user authentication and RBAC scoping","snowflake-integration-service-user-authentication-and-rbac-scoping","# Snowflake integration: service user authentication and RBAC scoping\n\nUnthread connects to Snowflake using a dedicated Snowflake service user (for example, `UNTHREAD_SVC`).\n\n## Authentication\n\nThe Snowflake connection uses **a username and key** for authentication.\n\n## Permission scoping (read-only vs. read-write)\n\nYou can enforce the integration’s access using **standard Snowflake RBAC restrictions**.\n\n- You can set **read-only** or **read-write** permissions.\n- You can scope permissions on a **per-table** or **per-schema** basis.\n\n### Recommended least-privilege approach\n\nTo minimize access, grant the service user **write permissions only to the specific tables you want Unthread to write to**.\n\nWith this approach, the service user would not be able to read or write anything else.","2026-05-15T17:53:06.198Z","2026-05-18T22:13:01.276Z","7196c0e0-233e-4698-9862-a6f3195eb47e",[],[],[],"Slack Permissions Explained","slack-permissions-explained","Below you will find a list of all the permissions we request and how we use them.\n\n## App Mentions\n\n`app_mentions:read`\n\n- **Description**: View messages that directly mention @Unthread in conversations that the app is in\n- **Request Reason**: We can optionally add you as the follower or assignee of a ticket if you are mentioned in a comment.\n\n## Channels\n\n`channels:history`\n\n- **Description**: View messages and other content in public channels that Unthread has been added to\n- **Request Reason**: We automatically track new tickets in channels that you add our bot to. New messages from customers in the channel can automatically be tracked as tickets.\n\n`channels:join`\n\n- **Description**: Join public channels in a workspace\n- **Request Reason**: We allow you to automatically add our bot to channel from the web UI. This also allows you to automatically track certain channels like customer Slack channels.\n\n`channels:manage`\n\n- **Description**: Manage public channels that Unthread has been added to and create new ones\n- **Request Reason**: This allows you to create new channels for triaging threads internally. You can create a temporary channel for discussing a ticket.\n\n`channels:read`\n\n- **Description**: View basic information about public channels in a workspace\n- **Request Reason**: This allows you to view a list of available channels to connect or use as a triage channel.\n\n`channels:write.invites`\n\n- **Description**: Invite members to public channels\n- **Request Reason**: This allows you to automatically join new triage channels for tickets that you’re a part of.\n\n`channels:write.topic`\n\n- **Description**: Set the description of public channels\n- **Request Reason**: This allows you to pin a ticket history view to the top of a channel. More information on the ticket history view here ↗.\n\n## Chat\n\n`chat:write`\n\n- **Description**: Send messages as @Unthread\n- **Request Reason**: This allows you to send replies and mass broadcasts to channels from the Unthread web app.\n\n`chat:write.customize`\n\n- **Description**: Send messages as @Unthread with a customized username and avatar\n- **Request Reason**: This allows you to send broadcasts as a separate support rep or as a support team.\n\n## Commands\n\n`commands`\n\n- **Description**: Add shortcuts and/or slash commands that people can use\n- **Request Reason**: This allows easy shortcuts to Unthread actions to modify tickets. You can open a modal to edit ticket details by using our “Manage conversation” shortcut on any message.\n\n## Emoji\n\n`emoji:read`\n\n- **Description**: View custom emoji in a workspace\n- **Request Reason**: This allows you to use custom emojis to trigger actions like closing tickets.\n\n## Files\n\n`files:read`\n\n- **Description**: View files shared in channels and conversations that Unthread has been added to\n- **Request Reason**: This allows you to view attachments in Slack channels from the Unthread web dashboard.\n\n`files:write`\n\n- **Description**: Upload, edit, and delete files as Unthread\n- **Request Reason**: This allows you to upload files from the Unthread web dashboard. You can upload photos and other documents from the web UI and have them visible in the Slack thread for a ticket.\n\n## Groups (Private Channels)\n\n`groups:history`\n\n- **Description**: View messages and other content in private channels that Unthread has been added to\n- **Request Reason**: This allows you to use private channels as triage channels. If you add the Unthread bot a private channel, we can publish messages there and track conversation history.\n\n`groups:read`\n\n- **Description**: View basic information about private channels that Unthread has been added to\n- **Request Reason**: This allows you to browse the list of available channels that the Unthread bot is in.\n\n`groups:write`\n\n- **Description**: Manage private channels that Unthread has been added to and create new ones\n- **Request Reason**: This allows you to create a new private message from the Unthread web dashboard.\n\n`groups:write.invites`\n\n- **Description**: Invite members to private channels\n- **Request Reason**: This allows you to automatically create new channels with relevant members of a ticket.\n\n`groups:write.topic`\n\n- **Description**: Set the description of private channels\n- **Request Reason**: This allows you to pin a ticket history view to the top of a channel. More information here ↗.\n\n## Instant Messages (Direct Messages)\n\n`im:history`\n\n- **Description**: View messages and other content in direct messages that Unthread has been added to\n- **Request Reason**: This allows you to directly message the Unthread bot to create new tickets. More information on bot DMs [here](https://docs.unthread.io/docs/conversational-ticketing/bot-for-slack-private-tickets).\n\n`im:read`\n\n- **Description**: View basic information about direct messages that Unthread has been added to\n- **Request Reason**: This allows you to directly message the Unthread bot to create new tickets. More information on bot DMs [here](https://help.unthread.unthread.io/articles/d955cd9d-eeed-4c43-b746-86f402977760).\n\n`im:write`\n\n- **Description**: Start direct messages with people\n- **Request Reason**: This allows you to directly message the Unthread bot to create new tickets. More information on bot DMs [here](https://help.unthread.unthread.io/articles/d955cd9d-eeed-4c43-b746-86f402977760).\n\n## Multi-Party Instant Messages (Group DMs)\n\n`mpim:history`\n\n- **Description**: View messages and other content in group direct messages that Unthread has been added to\n- **Request Reason**: This allows you to track group messages as tickets if the Unthread is included.\n\n`mpim:read`\n\n- **Description**: View basic information about group direct messages that Unthread has been added to\n- **Request Reason**: This allows you to track group messages as tickets if the Unthread is included.\n\n## Pins\n\n`pins:write`\n\n- **Description**: Add and remove pinned messages and files\n- **Request Reason**: This allows you to pin a ticket history view to the top of a channel so members can view the status of previous tickets they’ve submitted. More information on that [here](https://help.unthread.unthread.io/articles/7ac9e92c-e4aa-459f-a668-16a53c91e545).\n\n## Reactions\n\n`reactions:read`\n\n- **Description**: View emoji reactions and their associated content in channels and conversations that Unthread has been added to\n- **Request Reason**: This allows you to see message reactions from the web dashboard. You can see both standard and custom emojis for a conversation thread.\n\n`reactions:write`\n\n- **Description**: Add and edit emoji reactions\n- **Request Reason**: This allows you to add emoji reactions to messages from the web dashboard. You can add both standard and custom emojis to a conversation thread.\n\n## Team\n\n`team:read`\n\n- **Description**: View the name, email domain, and icon for workspaces Unthread is connected to\n- **Request Reason**: This allows you to see team members in your workspace and set them as agents and assignees.\n\n## User Groups\n\n`usergroups:read`\n\n- **Description**: View user groups in a workspace\n- **Request Reason**: This allows you to set groups as assignees of tickets (for example, assigning to an on-call rotation).\n\n`usergroups:write`\n\n- **Description**: Create and manage user groups\n- **Request Reason**: This allows you to update a user group for an on-call rotation. More information on using user groups can be found here ↗.\n\n## Users\n\n`users.profile:read`\n\n- **Description**: View profile details about people in a workspace\n- **Request Reason**: This allows you to have the user’s most recent name and photo up to date. When selecting an assignee, we’ll show you the name and photo of the user being selected.\n\n`users:read`\n\n- **Description**: View people in a workspace\n- **Request Reason**: This allows you to see team members in your workspace and set them as agents and assignees.\n\n`users:read.email`\n\n- **Description**: View email addresses of people in a workspace\n- **Request Reason**: This allows you to have the latest email address available for users if using our email support ticketing functionality.","2025-07-21T16:04:45.201Z","2026-05-13T21:38:06.011Z","b7f40037-b033-4d6b-8d6e-17c2731b82ff",[],[],[],"Integrating Customer Portals with Unthread for Ticket Management","integrating-customer-portals-with-unthread-for-ticket-management","### Overview\n\nThis article provides guidance on integrating customer portals with Unthread for managing support tickets. It covers how to ensure that tickets are correctly attributed to customers and how to maintain privacy and security.\n\n### Setting Up a [Customer Portal](https://docs.unthread.io/docs/in-app-support/customer-portal-overview)\n\n- **Single Portal Configuration:** It is recommended to create a single customer portal configuration. This setup allows users to view only their tickets, ensuring privacy and security.\n- **Ticket Attribution:** Tickets submitted through the customer portal are attributed to the customer profile based on the authenticated user's email. This ensures that analytics and data are correctly associated with the respective customer.\n\n### Ticket Management\n\n- **Channel Posting:** Tickets from the customer portal are not posted to a customer-facing Slack channel. Instead, they are managed internally, allowing for private handling of customer issues.\n- **Agent Access:** Agents create and manage tickets through the Unthread dashboard, not through the customer portal.\n\n### Security and Authentication\n\n- **User Authentication:** The portal supports user authentication to ensure that tickets are separated by customer. This is crucial for maintaining privacy and ensuring that users only see their own tickets.\n\n### Conclusion\n\nBy following these guidelines, you can effectively integrate a customer portal with Unthread, ensuring that tickets are managed securely and attributed correctly to each customer. This setup also allows for efficient internal handling of support tickets while maintaining customer privacy.","2024-12-03T15:32:40.523Z","2026-05-13T21:28:44.996Z","0570d9fa-3f63-4ee1-aa63-79a7b7b8d40d",[],[],[],"How to Generate a Google Gemini API Key (Service Account Key)","how-to-generate-a-google-gemini-api-key-service-account-key","These steps will create a **Google Cloud service account** with the right permissions and give you a JSON key file to share securely.\n\n### 1. Sign in to Google Cloud Console\n\n1. Go to: \n\n2. Make sure you’re in the **correct Google Cloud project** that is tied to your Google Workspace / Gemini instance.\n\n### 2. Enable the Vertex AI API (if not already enabled)\n\n1. In the top search bar, type **\"Vertex AI API\"**.\n\n2. Click **Enable**.\n\n - If it says “API enabled,” you can skip this step.\n\n### 3. Create a Service Account\n\n1. In the left menu, go to **IAM & Admin > Service Accounts**.\n\n2. Click **+ CREATE SERVICE ACCOUNT**.\n\n3. Fill in:\n\n - **Service account name:** `gemini-api-access` (or similar)\n\n - **Description:** \"Access for Gemini API calls\"\n\n4. Click **Create and Continue**.\n\n### 4. Grant the Required Role\n\n1. Under **Grant this service account access**, click **+ Select a role**.\n\n2. In the search box, type:\n\n ```\n Vertex AI User\n \n ```\n\n and select it.\n\n3. (Optional but safer) If you want to scope it down further, you can create a **custom role** that only has:\n\n ```\n aiplatform.endpoints.predict\n \n ```\n\n but \"Vertex AI User\" is the standard.\n\n4. Click **Continue**, then **Done**.\n\n### 5. Create a JSON Key\n\n1. In the **Service Accounts list**, find your new account.\n\n2. Click the three dots (**⋮**) on the right > **Manage keys**.\n\n3. Under **Keys**, click **Add key > Create new key**.\n\n4. Choose **JSON** and click **Create**.\n\n - This downloads a file ending in `.json`.\n\n - **This file is your API key.**\n\n### 6. Send the Key Securely\n\n- **Do not email the file as an attachment.**\n\n- Instead:\n\n - Upload it to a secure company file-share (e.g., Google Drive with restricted access).\n\n - Or use a secure password manager’s sharing feature.\n\n- Notify us when it’s shared.","2025-09-24T21:44:11.121Z","2025-09-24T21:44:29.518Z","bd81e821-86fe-4a1a-86e0-bc476ccf415e",[],[],[],"How to create a Checklist within a Ticket Type","## Using Ticket Type Custom Fields to create a Checklist for Agents\n\nSome ticket types, like new hire onboarding for example, require a checklist of actions to be completed before the new hire onboarding ticket type can be closed. You can use the custom field properties to create a checklist that will be visible to agent only in the details sidebar of the conversation.\n\n \\\n![image.png](/api/knowledge-base/images/b98c2bd0-0181-4a6f-8618-b0e81ff1867d)\n\n## Creating the Checklist within the Ticket Type\n\n- Create a new custom field with the type of \"Label\" to specify the name of the checklist\n- Add subsequent custom checkbox fields with the checklist items required for the ticket type\n- Make sure the checklist isn't a required field or visible to the submitter by de-selecting the question mark and eyeball icons on the custom field\n\n![image.png](/api/knowledge-base/images/18aee36e-3cbe-48df-b5d6-8c934139a73a)","2026-06-02T13:06:55.883Z","2026-06-02T13:14:58.408Z","2d5cdf8b-daad-4e47-a4f0-0fcb7362fa3a",[],[],[],"How to Change the Unthread Application Name in Slack","how-to-change-the-unthread-application-name-in-slack","Want Unthread to show up with a different name in Slack? You can rename the Unthread bot directly from your Slack app configuration.\n\nThis will update the bot name that members see when Unthread sends messages in your Slack workspace.\n\n## **Renaming the Bot**\n\nTo change the Unthread bot name in Slack:\n\n1. Open Slack’s **Installed Apps** page for your workspace.\n\n > ℹ️ You can also go directly to: `https://app.slack.com/apps-manage//integrations/installed`\n\n2. Search for **Unthread**.\n\n3. Click into the Unthread app, then select **App Details**.\n\n4. Go to the **Configuration** tab.\n\n5. Scroll down to the section labeled **Bot User**.\n\n6. Click **Edit**.\n\n7. Enter the new bot name, then save your changes.\n\nThat’s it! The Unthread bot will now appear with the updated name in Slack.\n\n## **Can’t Edit the Bot User?**\n\nIf you don’t see the option to edit the bot user, you may not have permission to manage apps in Slack. Ask a Slack Workspace Owner, Admin, or app manager to make the change for you.","2026-04-29T14:32:00.374Z","2026-04-29T15:03:42.188Z","1700d928-c665-481e-8676-cc4a9dce25fd",[],[],[],"How to Change the Logo and Bot Name for a Specific Team","how-to-change-the-logo-and-bot-name-for-a-specific-team","To change the logo and bot name for a specific team (project), follow these steps:\n\n1. Navigate to **Settings**\n2. Select **Projects**\n3. Click on the specific team you want to modify, such as the HR or IT team.\n4. Look for the option labeled **Support Name & Logo**.\n5. Update the logo and bot name as desired.\n\n## When will the updated name appear in Slack?\n\nAfter updating the bot/app name for a project, the new name will appear in Slack the next time the bot posts a message to the channel.\n\nThis process allows you to customize the logo and bot name for individual teams without affecting others. If you encounter any issues or have further questions, feel free to reach out to support for assistance.","2025-01-05T21:14:51.040Z","2026-05-15T18:49:24.089Z","8122880c-bb82-47d3-9c4d-bd951d3d0470",[],[],[],"Bot & Private Tickets - Unthread","bot-private-tickets-unthread","Unthread’s bot for Slack is the easiest way to intake customer requests, [generate AI responses](https://docs.unthread.io/docs/unthread-ai/ai-generated-responses), [assign to team members](https://docs.unthread.io/docs/conversational-ticketing/slas), and manage tickets end-to-end. As a customer, you will already see the Unthread app for Slack in your workspace as a way to view your [inbox](https://docs.unthread.io/docs/managing-your-inbox/managing-your-slack-inbox) and get notifications about conversations. The Unthread bot for Slack messaging tab is a great way to let customers easily create new support tickets for your team.\n\n## The Benefits of Bot Ticket Intake\n\n- All conversations are by default private between the user and ticket assignees\n- Users no longer need to remember the various Slack channels for support – all requests can funnel through the bot\n- You can set up custom SLAs and auto-response settings for the bot vs. other support channels\n\n![Example of a DM request](https://mintlify.s3.us-west-1.amazonaws.com/unthread/images/dm-promotion-request.png)\n\n## Users Viewing Ticket Submissions\n\nFrom the Unthread app homepage in Slack, users can view their history of requests, and easily jump back into the conversation. ![Example of viewing tickets](https://mintlify.s3.us-west-1.amazonaws.com/unthread/images/my-requests-view.png)\n\n## Privacy & Sending Tickets to the Right Agents\n\nWhen the user submits a question, they’ll be prompted to select the correct [Ticket Type](https://docs.unthread.io/docs/conversational-ticketing/ticket-types) for their request. As an example, if they select a “Laptop Replacement”, you can configure the request to be sent directly to the IT team. Separately, if they request “Time Off”, you can be sure this request is relayed directly to the HR team. Unthread will automatically handle privacy limitations so that ticket visibility is limited to only the correct team fielding the request. ![](https://mintlify.s3.us-west-1.amazonaws.com/unthread/images/ticket-thread.png)\n\n## Using Unthread AI\n\nAs discussed above, users can select the right ticket for their request, but you can also leverage Unthread AI to make this process even easier:\n\n- Unthread AI can generate a helpdesk answer and deflect tickets before they reach a human\n- If the request is unclear, the bot can ask clarifying questions\n- Once a ticket needs to be created, the bot can auto-detect the ticket type, and the user can confirm\n- If additional fields are requested for that ticket, the bot can auto-populate these fields based on the conversation\n\n## Enabling the Bot for Slack\n\nHead over to the “Settings” > “Slack”, and look for the “Bot DM” section to enable. You can also select a default Customer that will be linked for all new tickets created from DMs.\n\n## White-Labeling the Bot\n\nWe also support launching your own Slackbot with your own brand and image. To configure this, navigate to the “Settings” menu in the left sidebar, then select “Settings” under the corresponding project. Next to the “Bot Configuration” section, you can configure your own brand and image.","2024-10-16T15:22:08.108Z","2026-05-11T19:52:56.943Z","1ca215bb-4e44-4c1e-abc8-a1a9a20b0eab",[],[],[],"api-docs","2025-09-09T20:27:46.142Z","2025-10-08T20:19:42.138Z","eceee293-2334-444e-8851-be6efa5dcd01",2,[447,448],[],{"_57":458,"_134":459,"_136":-5,"_137":460,"_139":443,"_140":-5,"_141":461,"_143":462,"_22":463,"_24":25,"_145":464,"_147":-5,"_148":465,"_150":466},{"_57":449,"_134":450,"_136":-5,"_137":451,"_139":443,"_140":-5,"_141":452,"_143":453,"_22":454,"_24":25,"_145":455,"_147":-5,"_148":456,"_150":457},"Webhooks","webhooks","Unthread provides webhooks which allow you to receive HTTP POST requests when data is created or updated.\n\n## Configuration\n\nCreate an HTTP endpoint capable of receiving and responding to POST requests containing JSON payloads. The endpoint must be publicly accessible and must use HTTPS. The endpoint should respond with a 200 status code within 30 seconds of receiving a request.\n\n### URL Verification\n\nWhen the endpoint URL is given to Unthread, Unthread will emit a “url_verification” event. Your endpoint must respond to this request with a 200 status code within 3 seconds.\n\n### Security\n\nTo ensure security, your endpoint should validate that event payloads are signed with the signing secret available from the Unthread dashboard. This ensures that the events are coming from Unthread and not from a malicious source. Create an HMAC-SHA256 hash of the request body using the singing secret as the key and compare it to the signature included in the “X-Unthread-Signature” HTTP header. If the two values match, then the signature is considered valid.\n\n### Payload\n\nEvents will have the following structure:\n\n```plaintext\n{\n \"event\": \"conversation_created\", // The event type.\n \"eventId\": \"49bac55d-5445-4e70-ad72-c87e2e8adb3f\", // Unique ID for the event.\n \"eventTimestamp\": 1678732685142, // When the event took place, in milliseconds.\n \"webhookTimestamp\": 1678732685382, // When the event was sent, in milliseconds.\n \"data\": {\n // The event data, depends on the event type.\n \"id\": \"b72c8bcd-0387-4a6d-92b3-14016c3c53e5\"\n }\n}\n```\n\nThe following `event` types are supported:\n\n- `'conversation_created'`\n- `'conversation_updated'`\n- `'conversation_deleted'`\n- `'message_created'`\n\n### Retries\n\nIf the endpoint returns a status code other than 200 or it times out, the event will be retried up to 4 more times at increasing intervals. An “X-Unthread-Attempt-Number” HTTP header starting at 1 is included in every request to identify when a retry is occurring. If an endpoint fails consecutively more than 100 times or returns a 410 status code, it will be disabled automatically.\n\nIt is possible, though unlikely, that an event will be resent after succeeding. Your endpoint should be prepared to handle this case gracefully using the “eventId” property.\n\n## Examples\n\n```plaintext\nconst { createHmac } = require('crypto');\n\n// Example of how to get the rawBody property if using express:\n/***\napp.use(\n express.json({\n verify: (req, res, buf) => {\n req.rawBody = buf.toString();\n }\n })\n);\n***/\n\n// Replace the value here with one obtained from your Unthread dashboard.\nconst SIGNING_SECRET = 'your_signing_secret_here';\n\nfunction verifySignature(req) {\n // It's recommended to use raw request body content in the hash since JSON parsing might change it.\n const rawBody = req.rawBody;\n\tconst hmac = createHmac('sha256', SIGNING_SECRET).update(rawBody).digest('hex');\n\n\treturn return mac === req.get('x-unthread-signature');\n}\n\nfunction webhookHandler(req, res) {\n\tif (!verifySignature(req)) {\n\t\tres.sendStatus(403);\n\t\treturn;\n }\n\n\tconst { event, data } = req.body;\n\n if (event === 'url_verification') {\n // Respond within 3 seconds.\n res.status(200);\n return;\n }\n\n // Handle other event types here.\n\n // Default to returning 200.\n\tres.sendStatus(200);\n}\n```\n\n```plaintext\nimport hashlib\n\n# Replace the value here with one obtained from your Unthread dashboard.\nSIGNING_SECRET = 'your_signing_secret_here'\n\ndef verify_signature(request):\n hmac = hashlib.sha256(SIGNING_SECRET.encode('utf-8'), request.get_data(), digestmod=hashlib.sha256).hexdigest()\n\n return hmac == request.headers.get('x-unthread-signature')\n\n@app.route('/webhook', methods=['POST'])\ndef webhook():\n if not verify_signature(request):\n return 'Invalid signature', 403\n\n body = request.get_json()\n event = body.get('event')\n\n if event == 'url_verification':\n # Respond within 3 seconds.\n return 'OK', 200\n\n\t\t# Handle other event types here.\n\n # Default to returning 200.\n return 'OK', 200\n```\n\n## Zapier\n\nA webhook trigger is available as part of Unthread’s integration with [Zapier](https://docs.unthread.io/docs/integrations/zapier). You will need to create a connection to Unthread using your Unthread API key and you will also need to provide your webhook signing secret. The Zapier integration will automatically configure your webhook within Unthread. The integration will automatically validate webhook event signatures and ignore any events with invalid signatures.\n\n## Make (Integromat)\n\nA webhook trigger is available as part of Unthread’s integration with Make. You will need to create a connection to Unthread using your Unthread API key and you will also need to provide your webhook signing secret. The Zapier integration will automatically configure your webhook within Unthread. The integration will NOT automatically validate webhook event signatures however it is possible to configure your scenario to validate the signature. Add a “Transform to JSON” step and pass in the “payload” property from the Unthread webhook step. Then add a “Webhook Response” step with the following expression in the “Status” field: `if(sha256(; \"hex\"; ) = ; 200; 403)`. This will return a 403 status code if the signature is invalid.","2023-12-03T18:55:48.334Z","2026-05-13T21:04:51.582Z","2281de72-fe64-4357-a7ca-b2c078b33a8f",[],[],[],"API Reference","api-reference","Everything in Unthread is driven by our powerful API. You can set up your own Service Account to get an API key with specific permissions.\n\n## Create a Service Account to Generate an API Key\n\nIn order to call the API, you will first need to create a service account. Service Accounts are given permissions just like users, and they can be scoped to a [Project](https://docs.unthread.io/docs/setting-up-your-account/projects-permissions), or be tenant-wide.\n\nTo generate a **Project-scoped API key**, go to \"Setup\" > \"Service Accounts\"\n\nTo generate a **tenant-wide API key** (if you're a platform admin or owner), you can go to \"Workspace Settings\" > \"Service Accounts\".\n\nOptionally, you can add a helpful description and a date of expiration of the service account. There are no limits on the number of service accounts that you create.\n\nAfter creating the new service account, you will see a window displaying the service account’s API key. Copy this key and put it somewhere safe and secret. **Once you close the window you will not be able to view the key again.**\n\n## Calling the API\n\nThe URL for calls to the API will have the following form, with $ being replaced by the endpoint you are trying to call:\n\n```plaintext\nhttps://api.unthread.io/api/${endpoint}\n```\n\nIn order to authenticate, you must send an HTTP header with the key “X-Api-Key” and the value set to the service account key created in the previous section. All request and response bodies will be in JSON.\n\n## \n\n## API Conventions\n\nThe Unthread API follows RESTful conventions when possible, with most operations performed via `GET`, `POST`, `PATCH`, and `DELETE` requests. Request and response bodies are encoded as JSON.\n\n### List Endpoints\n\nAll list endpoints follow the same conventions. Requests are made in the following format:\n\n```plaintext\ninterface Where {\n field: WhereField;\n operator: '==' | '!=' | '>' | '<' | 'in' | 'notIn' | 'contains' | 'notContains' | 'like';\n value: string | number | string[];\n}\n\ninterface ListRequest {\n select?: Array;\n order?: Array;\n where?: Array>;\n limit?: number;\n descending?: boolean;\n cursor?: string;\n}\n```\n\nAccepted values for SelectField, OrderByField and WhereField depend on the object. Responses are made in the following format:\n\n```plaintext\ninterface ListResponse {\n data: Array;\n totalCount: number;\n cursors: {\n hasNext: boolean;\n hasPrevious: boolean;\n next?: string;\n previous?: string;\n };\n}\n```\n\nResponses are paginated by providing a cursor to the next or previous page. The limit per page is 100. An example list request is provided below:\n\n```plaintext\n// Request\n// POST /conversations/list\n{\n \"select\": [\n\t\t\"id\",\n\t\t\"title\",\n\t\t\"initialMessage.ts\",\n\t\t\"initialMessage.text\",\n\t\t\"tags.id\",\n\t\t\"tags.name\"\n\t],\n \"order\": [\"createdAt\", \"id\"],\n \"where\": [\n {\n \"field\": \"customerId\",\n \"operator\": \"==\",\n \"value\": \"9YQjOSTFXeOPF8xNURFd\"\n }\n ],\n \"descending\": true,\n \"limit\": 1,\n \"cursor\": \"W3RydWUsWyIwNTU4MTc5Zi1kYTJkLTQxZjItOTZlYy1iZGY2YzkzZGQ1MjIiXV0=\"\n}\n\n// Response\n{\n \"data\": [\n {\n \"id\": \"0476bfd0-0c3f-4dfb-b462-d75a4a6908e1\",\n\t\t \"title\": \"A bug report\",\n\t\t \"initialMessage\": {\n \"ts\": \"1675183719.124879\",\n \"text\": \"Help, I found a bug\"\n } ,\n\t\t \"tags\": [\n {\n \"id\": \"32561c55-0f01-47af-aa55-1a3d638f41e8\",\n \"name\": \"Bug\"\n }\n ]\n }\n ],\n \"totalCount\": 688,\n \"cursors\": {\n \"hasNext\": true,\n \"hasPrevious\": true,\n \"next\": \"W3RydWUsWyIwNDUzYmFiNi1iNDY3LTQ0MGMtYmMzZi1mNWEyODQ5YzlkYWUiXV0=\",\n \"previous\": \"W2ZhbHNlLFsiMDI4ZDg3NzMtY2I5Ni00MDQzLTlmYjYtMGZhOWUzYmFmY2MzIl1d\"\n }\n}\n```\n\n### Create and Update Endpoints\n\nCreate and update endpoints can specify a `select` query param that takes a comma-separated list of fields to return in the response. Example below:\n\n```plaintext\n// Request\n// PATCH /conversations/0476bfd0-0c3f-4dfb-b462-d75a4a6908e1?select=id,title,initialMessage.ts,initialMessage.text,tags.id,tags.name\n{\n \"status\": \"closed\"\n}\n\n// Response\n{\n \"id\": \"0476bfd0-0c3f-4dfb-b462-d75a4a6908e1\",\n \"title\": \"A bug report\",\n \"initialMessage\": {\n \"ts\": \"1675183719.124879\",\n \"text\": \"Help, I found a bug\"\n } ,\n \"tags\": [\n {\n \"id\": \"32561c55-0f01-47af-aa55-1a3d638f41e8\",\n \"name\": \"Bug\"\n }\n ]\n}\n```\n\n## \n\n## Objects\n\n### Conversation\n\n\\*The conversation friendly ID can be used in GET API calls and the conversation UUID should be used in all others calls.\n\n```plaintext\ninterface Conversation {\n id: string;\n status: \"open\" | \"in_progress\" | \"on_hold\" | \"closed\";\n subStatusId: string;\n customerId: string | null;\n channelId: string;\n wasManuallyCreated: boolean;\n friendlyId: number;\n createdAt: string;\n updatedAt: string;\n closedAt: string | null;\n statusUpdatedAt: string | null;\n responseTime: number | null;\n responseTimeWorking: number | null;\n resolutionTime: number | null;\n resolutionTimeWorking: number | null;\n title: string | null;\n priority: number | null;\n initialMessage: Message;\n assignedToUserId: User | null;\n tags: Array;\n customer: Customer | null;\n wakeUpAt: string | null;\n summary: string | null;\n snoozedAt: string | null;\n lockedAt: string | null;\n ticketTypeId: string | null;\n ticketTypeFields: Record;\n metadata?: Record;\n projectId: string;\n followers?: {\n userId?: string;\n groupId?: string;\n entityId: string;\n }[];\n collaborators?: {\n collaboratorTypeId: string;\n userId?: string;\n groupId?: string;\n entityId: string;\n }[];\n files?: {\n id: string;\n name: string;\n size: number;\n filetype: string;\n mimetype: string;\n }[];\n triageThreads?: {\n id: string;\n ts: string;\n channelId: string;\n createdAt?: Date;\n }[];\n}\n```\n\n### Message\n\n```plaintext\ninterface Message {\n ts: string;\n userId: string;\n userTeamId: string;\n botId: string;\n botName: string;\n text: string;\n subtype: string | null;\n conversationId: string;\n timestamp: string;\n threadTs: string | null;\n conversation: Conversation;\n user: User | null;\n metadata?: {\n eventType?:\n | \"autoresponder_replied\"\n | \"email_received\"\n | \"email_explanation_sent\"\n | \"widget_message_received\"\n | \"microsoft_teams_message_received\"\n | \"unthread_outbound\"\n | \"post_close_template_sent\"\n | \"customer_view_button\"\n | \"slack_bot_dm_received\";\n };\n}\n```\n\n### Customer (aka Channel)\n\n```plaintext\ninterface Customer {\n name: string;\n primarySupportAssigneeId: string | null;\n primarySupportAssigneeType: \"user\" | \"team\" | null;\n secondarySupportAssigneeId: string | null;\n secondarySupportAssigneeType: \"user\" | \"team\" | null;\n replyTimeoutMinutes: number | null;\n defaultTriageChannelId: string | null;\n disableAutomatedTicketing: boolean | null;\n botHandling: \"off\" | \"all\" | null;\n autoresponder: AutoresponderOptions | null;\n supportSteps: Array | null;\n slackTeamId: string | null;\n assignToTaggedUserEnabled: boolean | null;\n slackChannelId: string | null;\n createdAt: string;\n updatedAt: string;\n tags: Array;\n slackChannel: SlackChannel | null;\n projectId: string;\n}\n```\n\n### Tag\n\n```plaintext\ninterface Tag {\n id: string;\n name: string;\n description: string;\n autoTaggingEnabled: boolean;\n projectId: string;\n}\n```\n\n### User\n\n```plaintext\ninterface User {\n id: string;\n name: string;\n email: string;\n slackId: string;\n photo: string;\n customFields: CustomField[];\n}\n```\n\n### User Team\n\n```plaintext\ninterface UserTeam {\n id: string;\n name: string;\n slackId: string;\n}\n```\n\n### Slack Channel\n\n```plaintext\ninterface SlackChannel {\n id: string;\n name: string;\n isShared: boolean;\n isPrivate: boolean;\n}\n```\n\n### Simple Condition\n\n```plaintext\ninterface SimpleCondition {\n leftValue?: any;\n leftValueFrom?: string;\n operator: \"equals\" | \"notEquals\" | \"greaterThan\" | \"lessThan\" | \"greaterThanOrEquals\" | \"lessThanOrEquals\" | \"contains\" | \"notContains\" | \"in\" | \"notIn\";\n rightValue?: any;\n rightValueFrom?: string;\n}\n```\n\nFor a “simple condition”, the left and right values are compared using the operator. For example, if the operator is “equals”, the left and right values are compared for equality. For left and right values, either a value can be provided directly or a reference to a field in the “context”, through the `leftValueFrom` and `rightValueFrom` fields.\n\nThe “context” depends on the object and the operation. For example, for ticket type field conditions, the context has the following shape:\n\n```plaintext\n{\n \"conversation\": {\n \"ticketTypeFields\": {\n \"12345678-1234-1234-1234-123456789abc\": \"value-1\",\n \"42345678-1234-1234-1234-123456789abd\": \"value-2\"\n }\n }\n}\n```\n\nTherefore, a condition can be added on a ticket type field like this:\n\n```plaintext\n{\n \"leftValueFrom\": \"conversation.ticketTypeFields['12345678-1234-1234-1234-123456789abc']\",\n \"operator\": \"equals\",\n \"rightValue\": \"value-1\"\n}\n```\n\nThis will cause the field to be available for a given conversation if the ticket type has field `12345678-1234-1234-1234-123456789abc` set to `value-1`.\n\n### Ticket Type Field\n\n```plaintext\ninterface TicketTypeField {\n id: string;\n label: string;\n type: \"short-answer\" | \"long-answer\" | \"multi-select\" | \"single-select\" | \"checkbox\" | \"user-select\" | \"multi-user-select\";\n required: boolean;\n public: boolean;\n description: string;\n options?: string[];\n conditions?: {\n type: \"simple\";\n simple:\n | SimpleCondition\n | {\n and: SimpleCondition[];\n }\n | {\n or: SimpleCondition[];\n };\n };\n}\n```\n\nFor ticket type field conditions, the only context\n\n### Ticket Type\n\n```plaintext\ninterface TicketType {\n id: string;\n name: string;\n projectId: string;\n description: string;\n createdAt: string;\n updatedAt: string;\n fields: Array;\n}\n```\n\n### Autoresponder Options\n\n```plaintext\ninterface AutoresponderOptions {\n enabled: boolean;\n condition: \"always\" | \"outside-working-hours\";\n message: string;\n}\n```\n\n### Support Step\n\n```plaintext\ninterface SupportStep {\n type: \"assignment\" | \"escalation\" | \"reminder\" | \"triage\";\n assigneeId?: string;\n assigneeType?: \"user\" | \"team\";\n minutes: number;\n shouldCycleThroughTeamMembers?: boolean;\n maxCycles?: number;\n cycleMinutes?: number;\n}\n```\n\n### Outbound\n\n```plaintext\ninterface Outbound {\n id: string;\n status: \"scheduled\" | \"draft\" | \"sent\" | \"failed\";\n deliveryMethod: \"slack\";\n subject: string;\n // See Slack Block Kit documentation for details on the blocks field: https://api.slack.com/block-kit\n blocks: Array;\n recipients: {\n type: \"customer\";\n id: string;\n }[];\n sendAs: {\n // For type == \"support-rep\" the ID is the user ID to use as a default if there is no support rep for a given customer.\n type: \"user\" | \"support-rep\";\n id: string;\n };\n runAt: string;\n}\n```\n\n### Webhook Subscription\n\n```plaintext\ninterface WebhookSubscription {\n id: string;\n url: string;\n enabled: boolean;\n}\n```\n\n### Approval Request\n\n```plaintext\ninterface ApprovalRequest {\n status: \"approved\" | \"rejected\" | \"pending\";\n id: string;\n tenantId: string;\n assignedToGroupId?: string;\n assignedToUserId?: string;\n statusChangedAt?: Date;\n conversationId: string;\n title?: string;\n notes?: string;\n createdAt: Date;\n approverUser?: User;\n approverGroup?: UserTeam;\n}\n```\n\n### Collaborator Type\n\n```plaintext\ninterface CollaboratorType {\n id: string;\n name: string;\n key: string;\n description?: string;\n}\n```\n\n### Account\n\n```plaintext\ninterface Account {\n id: string;\n name: string;\n primarySupportAssigneeId: string | null;\n primarySupportAssigneeType: \"user\" | \"team\" | null;\n secondarySupportAssigneeId: string | null;\n secondarySupportAssigneeType: \"user\" | \"team\" | null;\n emailsAndDomains: string[];\n slackChannelIds: string[];\n slackTeamIds: string[];\n customFields: any[];\n supportSteps: any[];\n imageUrl: string | null;\n externalCrmMetadata: {\n id: string;\n } | null;\n createdAt: string;\n updatedAt: string;\n createdBy: string;\n updatedBy: string;\n slackChannels: Array;\n slackTeams: Array<{\n id: string;\n name: string;\n icon: string;\n }>;\n tags: Array;\n}\n```\n\n### User Group\n\n```plaintext\ninterface UserGroup {\n id: string;\n description?: string;\n isExternal: boolean;\n filters: Array;\n projectId: string | null;\n}\n```\n\n### Filter\n\n```plaintext\ninterface Filter {\n field: string;\n operator: 'contains' | 'notContains' | 'in' | 'notIn' | 'equals' | 'notEquals' | 'lessThan' | 'greaterThan' | 'isNull' | 'isNotNull' | 'stringContains' | 'stringNotContains'\n value: any;\n}\n```\n\n# Endpoints\n\n## Accounts\n\n**Create Account**\n\n```plaintext\nPOST /accounts\n```\n\nThis endpoint will create and return a new account.\n\nRequest schema:\n\n```plaintext\ninterface CreateAccountRequest {\n name: string;\n primarySupportAssigneeId?: string | null;\n primarySupportAssigneeType?: \"user\" | \"team\" | null;\n secondarySupportAssigneeId?: string | null;\n secondarySupportAssigneeType?: \"user\" | \"team\" | null;\n emailsAndDomains?: string[];\n slackChannelIds?: string[];\n slackTeamIds?: string[];\n customFields?: any[];\n supportSteps?: any[];\n imageUrl?: string | null;\n externalCrmMetadata?: {\n id: string;\n } | null;\n}\n```\n\n### Get Account by ID\n\n```plaintext\nGET /accounts/:accountId\n```\n\nThis endpoint will return the given account.\n\n### Update Account\n\n```plaintext\nPATCH /accounts/:accountId\n```\n\nThis endpoint will return the updated account. All fields from the create request schema can be updated.\n\n### Delete Account\n\n```plaintext\nDELETE /accounts/:accountId\n```\n\nThis endpoint will delete the given account.\n\n### List Accounts\n\n```plaintext\nPOST /accounts/list\n```\n\nThis endpoint will return a list of accounts following the standard list conventions. Supported fields for select, order, and where operations:\n\n- `id`\n- `name`\n- `imageUrl`\n- `primarySupportAssigneeId`\n- `primarySupportAssigneeType`\n- `secondarySupportAssigneeId`\n- `secondarySupportAssigneeType`\n- `primarySupportAssignee.id`\n- `primarySupportAssignee.name`\n- `secondarySupportAssignee.id`\n- `secondarySupportAssignee.name`\n- `emailsAndDomains`\n- `slackChannelIds`\n- `slackTeamIds`\n- `customFields`\n- `supportSteps`\n- `createdAt`\n- `updatedAt`\n- `createdBy`\n- `updatedBy`\n- `slackChannels.id`\n- `slackChannels.name`\n- `slackChannels.isPrivate`\n- `slackChannels.isShared`\n- `slackChannels.archivedAt`\n- `slackChannels.slackTeamId`\n- `slackTeams.id`\n- `slackTeams.name`\n- `slackTeams.icon`\n- `tags.id`\n- `tags.name`\n- `externalCrmMetadata`\n\n## \n\n## Approval Requests\n\n### **Create Approval Request for Conversation**\n\n```plaintext\nPOST /conversations/:conversationId/approval-requests\n```\n\nThis endpoint will return the newly created approval request. Fields that can be set on create are: `title`, `assignedToUserId` and `assignedToGroupId`.\n\n### **Get Approval Requests for Conversation**\n\n```plaintext\nGET /conversations/:conversationId/approval-requests\n```\n\nThis endpoint will return a list of approval requests for the given conversation.\n\n## \n\n## Automations\n\n**Create Automation**\n\n```plaintext\nPOST / automations;\n```\n\nThis endpoint creates a new automation.\n\n**Request Body**\n\nThe request body should be a JSON object with the following structure:\n\n```plaintext\n{\n name: string;\n description?: string | null;\n status?: 'draft' | 'active' | 'inactive';\n trigger: AutomationTrigger;\n steps: AutomationStep[];\n conditions?: Conditions | null;\n}\n```\n\n- `name` (required): The name of the automation.\n- `description` (optional): A description of the automation.\n- `status` (optional): The status of the automation. Defaults to ‘draft’ if not provided.\n- `trigger` (required): The trigger configuration for the automation.\n- `steps` (required): An array of steps that define the automation’s actions.\n- `conditions` (optional): Conditions that determine when the automation should run.\n\n### AutomationTrigger\n\nThe `trigger` field should be an object with a `type` property and a `data` property. The structure depends on the trigger type:\n\n```plaintext\n{\n type: \"event\" | \"manual\" | \"webhook\" | \"slackReaction\" | \"scheduled\" | \"delay\";\n data: {\n // Fields depend on the trigger type\n }\n}\n```\n\n### AutomationStep\n\nEach step in the `steps` array should be an object with a `type` property and a `data` property:\n\n```plaintext\n{\n type: \"action\" | \"branches\";\n data: {\n // Fields depend on the step type\n }\n}\n```\n\n### Response\n\nThe response will be a JSON object representing the created automation, including its ID and other details.\n\n### Notes\n\n- Automations are only available if custom actions are enabled for the tenant.\n\n### Get Automation\n\n```plaintext\nGET /automations/:automationId\n```\n\nReturns the existing automation.\n\n### List Automations\n\n```plaintext\nPOST /automations/list\n```\n\nReturns automations visible to your service account using the standard list conventions.\n\n### Update Automation\n\n```plaintext\nPATCH /automations/:automationId\n```\n\nUpdates the supplied fields and returns the updated automation. Supported fields include `name`, `description`, `status`, `priority`, `trigger`, `steps`, `conditions`, and `projectId`.\n\nYour service account must have permission to manage automations in the relevant workspace or project. Automations must be enabled for your workspace.\n\n### Posting shared code library external functions for automations\n\nUse this POST function:\n\n```plaintext\nPOST /automations/functions?projectId=${project ID goes here}\n\n{\n\"code\": \"code goes here...\"\n}\n```\n\nThat should return an object with a version property:\n\n```plaintext\n{\\\n\"version\": 2,\\\n...other properties here\\\n}\n```\n\nThen you'll need to activate the version:\n\n```plaintext\nPOST /automations/functions/${version here}/activate?projectId${project ID here}\n\n{}\n```\n\nThe projectId query param is optional. If this is for *tenant* level automations leave that blank.\n\n\\*\\*\\*If you need to \"roll-back\" a change made through the API you can do so by activating a previous function version.\n\n## Conversation Management\n\n### Add Follower to Conversation\n\n```plaintext\nPOST /conversations/:conversationId/add-follower\n```\n\nThis endpoint will add a follower to the given conversation. The request body should contain the `entityId` of the follower to add and the `entityType` which is either “user” or “group”.\n\n### **Remove Follower from Conversation**\n\n```plaintext\nPOST /conversations/:conversationId/remove-follower\n```\n\nThis endpoint will remove a follower from the given conversation. The request body should contain the `entityId` of the follower to remove.\n\n### Assign Collaborator to Conversation\n\n```plaintext\nPUT /conversations/:conversationId/collaborators/:collaboratorTypeId\n```\n\nThis endpoint will add a collaborator with the given collaborator type to the given conversation. The request body should contain the `entityId` of the collaborator to add and the `entityType` which is either “user” or “group”.\n\n### List Collaborator Types\n\n```plaintext\nPOST /collaborator-types/list;\n```\n\nThis endpoint will return a list of collaborator types.\n\n### Create External Task\n\n```plaintext\nPOST /conversations/:conversationId/external-tasks\n```\n\nSample body:\n\n```plaintext\n{\n \"title\": \"Fix widget export failure\",\n \"description\": \"Customer cannot export CSV from the dashboard.\",\n \"integrationId\": \"linear-task-manager-integration-uuid\",\n \"projectId\": \"linear-project-id\",\n \"assigneeId\": \"linear-user-id\",\n \"providerConfig\": {\n \"linearTeamId\": \"linear-team-id\",\n \"linearLabelIds\": [\"linear-label-id-1\", \"linear-label-id-2\"],\n \"linearPriority\": 2,\n \"linearStatusId\": \"linear-workflow-state-id\",\n \"linearDueDate\": \"2026-06-15\"\n }\n}\n```\n\n## Conversations\n\n### Create Conversation\n\n```plaintext\nPOST / conversations;\n```\n\nThis endpoint will create and return a new conversation. Behavior will differ depending on the `type` field:\n\n- For `type == \"slack\"`, the conversation will be for communication in Slack. You can choose to post the details either into a DM or into a channel.\n- For `type == \"triage\"`, the conversation will be for internal discussion only and there will be no way to communicate with the customer. The `triageChannelId` field is required.\n- For `type == \"email\"`, the conversation will be continued via email replies. Replies in the thread with `/unthread send` appended will be sent to the customer via email. The `emailInboxId` field is required. The `onBehalfOf` field is used to specify the email address and name of the end user to communicate with.\n\n To distinguish between agents and customers on an email conversation use the message’s `isExternal`: `true` means customer-side, and `false` means support-side. `sentByUser` identifies the actual sender, including someone replying from CC. Bots/system messages need separate handling. `onBehalfOf` is an input for creating messages, not a sender-classification field.\n\nIf `customerId` is provided, the conversation will be linked to the given customer and that customer’s autoresponder and SLA settings will be applied.\n\nRequest schema:\n\n```plaintext\ninterface CreateConversationRequest {\n type: \"triage\" | \"email\" | \"slack\";\n markdown: string;\n status: \"open\" | \"in_progress\" | \"on_hold\" | \"closed\";\n assignedToUserId?: string;\n customerId?: string;\n channelId?: string; // Only required if type == \"slack\". If not provided, the conversation will be continued through the Unthread app for Slack via a DM.\n projectId?: string;\n priority?: 3 | 5 | 7 | 9;\n triageChannelId?: string; // Only required if type == \"triage\"\n notes?: string;\n title?: string;\n excludeAnalytics?: boolean;\n emailInboxId?: string; // Only required if type == \"email\"\n ticketTypeId?: string;\n onBehalfOf?: {\n // Only required if type == \"email\". Either email or id must be provided.\n email?: string;\n name?: string;\n id?: string;\n };\n}\n```\n\n### Attachments\n\nFiles can be attached to the conversation by making a multipart/form-data request instead of a JSON request. The JSON payload should be included as a form field named `json` and the files should be included as additional form fields with the name `attachments` and the file as the value.\n\nSlack enforces a hard limit of **10 file attachments per Slack message** (not per conversation). If you need to attach more than 10 files, split the attachments across multiple messages.\n\nThe maximum file size is 20MB.\n\nFiles attached to email conversations through the API are delivered upon public reply to the thread. Attachments totaling over 15 MB are sent as download links instead.\n\nFiles can be tied to a specific message by using the the containing message’s `id`. The message-list API exposes `files` and `attachments`; email attachment details are also available by selecting `inbound.inboundEmail.attachments.`\n\nSee the following Javascript example for clarification:\n\n```plaintext\nconst formData = new FormData();\n\nformData.append(\n \"json\",\n JSON.stringify({\n type: \"email\",\n markdown: \"Hello, world!\",\n status: \"open\",\n onBehalfOf: {\n email: \"example@unthread.io\",\n name: \"Example User\",\n },\n emailInboxId: \"12345678-1234-1234-1234-123456789abc\",\n })\n);\n\nformData.append(\"attachments\", file1);\nformData.append(\"attachments\", file2);\n\nawait fetch(\"https://api.unthread.io/api/conversations\", {\n method: \"POST\",\n headers: {\n \"X-Api-Key\": \"\",\n },\n body: formData,\n});\n```\n\nNotes:\n\n- Markdown should follow the [Slack formatting](https://api.slack.com/reference/surfaces/formatting) guide.\n- For more info on multipart/form-data requests, see the IETF [RFC 7578](https://tools.ietf.org/html/rfc7578).\n\n### Get Conversation by ID\n\n```plaintext\nGET /conversations/:conversationId\n```\n\nThis endpoint will return the given conversation.\n\n### Update Conversation\n\n```plaintext\nPATCH /conversations/:conversationId\n```\n\nThis endpoint will return the updated conversation. Fields that can be updated are:\n\n- `status`\n- `subStatusId`\n- `priority`\n- `notes`\n- `assignedToUserId`\n- `wakeUpAt`\n- `snoozedAt`\n- `excludeAnalytics`\n- `title`\n- `lockedAt`\n- `customerId`\n- `ticketTypeId`\n- `ticketTypeFields`\n- `submitterUserId`\n- `metadata`\n\n### \n\nQuery parameters:\n\n- `useFullContent` (optional): When set to `true`, returns the full content of the conversation in the response. Defaults to `false`.\n- `mergeTicketTypeFields`(optional): When set to `true`, merges the provided `ticketTypeFields` with existing fields instead of replacing them entirely. Defaults to `false`.\n\nExample:\n\n```plaintext\nPATCH /conversations/:conversationId?mergeTicketTypeFields=true\n```\n\n### Transfer Conversation\n\n`POST /conversations/:conversationId/transfer`\n\nTransfers an existing conversation to another project in the same workspace and returns the updated Conversation. Use the conversation UUID for `conversationId`.\n\nAuthenticate with the `X-Api-Key` header. The service account must be able to access the source conversation and have permission to manage conversations in the destination project.\n\nRequest schema:\n\n```plaintext\ninterface TransferConversationRequest {\n projectId: string; // Required destination project UUID\n status?: \"open\" | \"in_progress\" | \"on_hold\" | \"closed\";\n ticketTypeId?: string | null; // Ticket type UUID in the destination project\n ticketTypeFields?: Record | null;\n priority?: number | null; // Integer from 0 through 10\n assignedToUserId?: string | null; // User UUID\n}\n```\n\nDefaults and behavior:\n\n- `projectId` is required.\n- Omitting `status` sets the status to `open`.\n- Omitting `ticketTypeId` or sending `null` clears the ticket type. A supplied ticket type must belong to the destination project.\n- `ticketTypeFields` replaces the existing field values. Omitting it or sending `null` resets the fields to an empty object.\n- Omitting `assignedToUserId` clears the current user assignment; sending `null` also clears it.\n- Omitting `priority` preserves the current priority; sending `null` clears it.\n\nExample request:\n\n```plaintext\nPOST /conversations/0476bfd0-0c3f-4dfb-b462-d75a4a6908e1/transfer?select=id,projectId,status\nContent-Type: application/json\nX-Api-Key: YOUR_API_KEY\n\n{\n \"projectId\": \"12345678-1234-4234-8234-123456789abc\",\n \"status\": \"open\"\n}\n```\n\nExample response (HTTP 200):\n\n```plaintext\n{\n \"id\": \"0476bfd0-0c3f-4dfb-b462-d75a4a6908e1\",\n \"projectId\": \"12345678-1234-4234-8234-123456789abc\",\n \"status\": \"open\"\n}\n```\n\nThe optional `select` query parameter follows the standard create and update endpoint conventions. Invalid request fields, an unavailable conversation, or a ticket type outside the destination project cause the request to fail.\n\n### **List Conversations**\n\n```plaintext\nPOST / conversations / list;\n```\n\nThis endpoint will return a list of conversations.\n\n### List Messages for Conversation\n\n```plaintext\nPOST /conversations/:conversationId/messages/list\n```\n\nThis endpoint will return a list of messages for a given conversation.\n\n### Create Message in Conversation\n\n```plaintext\nPOST /conversations/:conversationId/messages\n```\n\nThis endpoint will post a new message into a Slack thread for a conversation.\n\nSample request:\n\n```plaintext\ninterface Block {\n type: \"section\" | \"survey\";\n text?: {\n text: string;\n type: \"mrkdwn\" | \"plaintext\";\n };\n survey_id?: string;\n}\n\ninterface CreateMessageRequest {\n body?: {\n type: \"html\" | \"markdown\";\n value: string;\n };\n blocks?: Block[];\n markdown?: string; // DEPRECATED: Use 'blocks' and/or 'body' instead\n triageThreadTs?: string; // Slack thread value (e.g. \"1782936472.199649\")\n isPrivateNote?: boolean; // Only applicable for email and in-app chat conversations\n isAutoresponse?: boolean; // Set this to true to treat this as a bot auto-response. Useful when responding to a conversation with your own AI bot.\n onBehalfOf?: {\n email?: string;\n name?: string;\n id?: string;\n };\n}\n```\n\nNotes:\n\n- Either `body`, `blocks` or `markdown` must be provided.\n- If both `blocks` and `body` or `markdown` are provided, the `blocks` will be appended after the `markdown` content\n- Only pass in `triageThreadTs` if you want the message to be posted to a [triage](https://help.unthread.unthread.io/articles/016a0ff3-d7ba-40bc-bbd6-9676c04854db) thread for that conversation rather than being sent to the customer.\n- For email and in-app chat conversations, set `isPrivateNote` to `true` to mark the message as a private note which will post to the Slack thread for the conversation without sending a response back to the customer.\n- File attachments can also be included. See the section on adding attachments when creating a conversation for more information.\n- If `onBehalfOf` is provided, the message will be sent as the given user. If not provided, the message will be sent as the Unthread bot.\n\n### Link Conversations\n\n```plaintext\nPOST /conversations/:conversationId/links\n```\n\nCreate a related to, blocking, or tracking link to a conversation.\n\n```plaintext\ninterface LinkConversationRequest {\n linkedConversationId: string;\n type: 'relatedTo' | 'blocks' | 'blockedBy' | 'tracks' | 'trackedBy'\n}\n```\n\n## Download File Attachment\n\n```plaintext\nGET /conversations/:conversationId/files/:fileId/full\n```\n\nThis endpoint will return the full contents of a file attachment for a given conversation. The `:fileId` can be found in the `files` array of the conversation object.\n\n## \n\n## Customers\n\n### Get Customer by ID\n\n```plaintext\nGET /customers/:customerId\n```\n\nThis endpoint will return the given customer.\n\n### Update Customer\n\n```plaintext\nPATCH /customers/:customerId\n```\n\nThis endpoint will return the updated customer. Fields that can be updated are: `name`, `slackChannelId`, `autoresponder`, `supportSteps`, `defaultTriageChannelId`, `disableAutomatedTicketing`, `primarySupportAssigneeId`, `primarySupportAssigneeType`, `secondarySupportAssigneeId`, `secondarySupportAssigneeType`, `replyTimeoutHours`, `botHandling`, `emailDomains`.\n\n### Create Customer\n\n```plaintext\nPOST / customers;\n```\n\nThis endpoint will return the newly created customer and will create a Slack channel automatically if the `createChannel` flag is set to `true`.\n\n```plaintext\ninterface CreateCustomerRequest {\n name: string;\n slackChannelId?: string;\n emailDomains?: string[];\n tagIds?: string[],\n isPrivate?: boolean;\n inviteUserIds?: string[];\n channelTopic?: string; // max 250 characters\n createChannel?: boolean; // to create a channel in Slack for this customer\n}\n```\n\n### Delete Customer\n\n```plaintext\nDELETE /customers/:customerId\n```\n\nThis endpoint will delete the given customer.\n\n### List Customers\n\nThis endpoint will return a list of customers.\n\n## \n\n## Knowledge Base\n\n### Query Knowledge Base\n\n```plaintext\nPOST / knowledge - base / query;\n```\n\nThis endpoint allows you to make a one-off query to the knowledge base. You can optionally pass various context parameters to influence the query results.\n\nRequest schema:\n\n```plaintext\ninterface QueryKnowledgeBaseRequest {\n query: string; // Required\n customerId?: string; // Optional\n userId?: string; // Optional\n conversationId?: string; // Optional\n}\n```\n\n### Parameters\n\n- `query` (required): The string query to search for in the knowledge base.\n- `customerId` (optional): The ID of the customer associated with this query.\n- `userId` (optional): The ID of the user making the query.\n- `conversationId` (optional): The ID of the conversation context for this query.\n\nExample request:\n\n```plaintext\n{\n \"query\": \"How do I reset my password?\",\n \"customerId\": \"9YQjOSTFXeOPF8xNURFd\",\n \"userId\": \"63335fa9-ffcc-4103-8905-e4440cc7c7d4\",\n \"conversationId\": \"0476bfd0-0c3f-4dfb-b462-d75a4a6908e1\"\n}\n```\n\n### Create Knowledge Base Article\n\n```plaintext\nPOST / knowledge - base / articles;\n```\n\nThis endpoint allows you to create a new article in the knowledge base.\n\nRequest schema:\n\n```plaintext\ninterface CreateKnowledgeBaseArticleRequest {\n title: string; // Required\n content: string; // Required\n url?: string; // Optional\n userGroupIds?: string[]; // Optional\n}\n```\n\n### Parameters:\n\n- `title` (required): The title of the knowledge base article.\n- `content` (required): The content of the knowledge base article.\n- `url` (optional): The URL associated with this article.\n- `userGroupIds` (optional): Array of user group IDs that have access to this article.\n\nExample request:\n\n```plaintext\n{\n \"title\": \"How to Reset Your Password\",\n \"content\": \"To reset your password, go to the login page and click on 'Forgot Password', then follow the instructions sent to your email.\",\n \"url\": \"https://help.example.com/password-reset\",\n \"userGroupIds\": [\"63335fa9-ffcc-4103-8905-e4440cc7c7d4\"]\n}\n```\n\n### Get Knowledge Base Article by ID\n\n```plaintext\nGET /knowledge-base/articles/:articleId\n```\n\nThis endpoint retrieves a specific knowledge base article by its ID.\n\nExample response:\n\n```plaintext\n{\n \"id\": \"63335fa9-ffcc-4103-8905-e4440cc7c7d4\",\n \"title\": \"How to Reset Your Password\",\n \"content\": \"To reset your password, go to the login page and click on 'Forgot Password', then follow the instructions sent to your email.\",\n \"url\": \"https://help.example.com/password-reset\",\n \"status\": \"active\",\n \"userGroupIds\": [\"63335fa9-ffcc-4103-8905-e4440cc7c7d4\"],\n \"createdAt\": \"2023-04-15T14:32:21Z\",\n \"updatedAt\": \"2023-04-16T09:14:07Z\"\n}\n```\n\n### Update Knowledge Base Article\n\n```plaintext\nPATCH /knowledge-base/articles/:articleId\n```\n\nThis endpoint allows you to update an existing article in the knowledge base.\n\nRequest schema:\n\n```plaintext\ninterface UpdateKnowledgeBaseArticleRequest {\n title?: string; // Optional\n content?: string; // Optional\n url?: string; // Optional\n userGroupIds?: string[]; // Optional\n status?: \"active\" | \"inactive\"; // Optional\n}\n```\n\n### Parameters:\n\n- `title` (optional): The updated title of the knowledge base article.\n- `content` (optional): The updated content of the knowledge base article.\n- `url` (optional): The updated URL associated with this article.\n- `userGroupIds` (optional): Updated array of user group IDs that have access to this article.\n- `status` (optional): The status of the article, either “active” or “inactive”.\n\nExample request:\n\n```plaintext\n{\n \"title\": \"Updated: How to Reset Your Password\",\n \"status\": \"inactive\"\n}\n```\n\n### Delete Knowledge Base Article\n\n```plaintext\nDELETE /knowledge-base/articles/:articleId\n```\n\nThis endpoint deletes an article from the knowledge base.\n\n### List Knowledge Base Articles\n\n```plaintext\nPOST / knowledge - base / articles / list;\n```\n\nThis endpoint will return a list of knowledge base articles following the standard list conventions. Example request:\n\n```plaintext\n{\n \"select\": [\"id\", \"title\", \"url\", \"status\"],\n \"order\": [\"createdAt\"],\n \"where\": [\n {\n \"field\": \"status\",\n \"operator\": \"==\",\n \"value\": \"active\"\n }\n ],\n \"descending\": true,\n \"limit\": 10\n}\n```\n\n## Outbound Messages (Broadcasts)\n\n### Create and/or send an outbound message\n\n```plaintext\nPOST / outbounds;\n```\n\nThis endpoint will create an outbound and send it, unless the status is set to “draft”. Drafts can be sent later by updating the status to “scheduled”.\n\n### Update and/or send an outbound message\n\n```plaintext\nPATCH /outbounds/:outboundId\n```\n\nThis endpoint will update an outbound. Drafts can be sent by updating the status to “scheduled”.\n\n### List outbounds\n\n```plaintext\nGET / outbounds;\n```\n\nThis endpoint will list all outbounds.\n\n### Get outbound by ID\n\n```plaintext\nGET /outbounds/:outboundId\n```\n\nThis endpoint will return the given outbound.\n\n## \n\n## Reporting\n\n```plaintext\nPOST / reporting / time - series;\n```\n\nThis endpoint will return metrics about your conversations. Requests are made in the following format:\n\n```plaintext\ntype Metric = \"totalCount\" | \"responseTimeMean\" | \"responseTimeWorkingMean\" | \"resolutionTimeMean\" | \"resolutionTimeWorkingMean\" | \"conversationsResolved\";\ntype DateDimension = \"day\" | \"week\" | \"month\";\ntype Dimension = \"assigneeId\" | \"customerId\" | \"tagId\" | \"sourceType\";\n\ninterface ReportingTimeSeriesRequest {\n timezone?: string;\n startDate: string;\n endDate: string;\n dateDimension?: DateDimension;\n metric: Metric;\n dimensions?: Dimension[];\n filters?: {\n [dim: Dimension]: string | string[];\n };\n}\n```\n\n- The `timezone` field is optional and defaults to “UTC”.\n- `startDate` and `endDate` have the following format: “2022-12-31”. The dates are inclusive.\n- `dateDimension` specifies the time period in which the data should be grouped.\n- All metrics are numbers. Response and resolution times are in seconds.\n- `dimensions` is an array of fields to group the data by in addition to the date.\n- `filters` allows you to filter the data to specific dimensions. If an array is passed for a given dimension, then it is treated as an `OR`.\n\nResponses are returned in the following format:\n\n```plaintext\ntype Dimension = \"assigneeId\" | \"customerId\" | \"tagId\" | \"sourceType\";\n\ntype DataSplit = {\n [key: string]: DataPoint;\n};\ntype DataPoint = number | Data: Split;\n\ninterface ReportingTimeSeriesResponse {\n data: DataSplit;\n dates: string[];\n lookups: {\n [dim: Dimension]: {\n [key: string]: string;\n };\n };\n}\n```\n\n- If there is no data for a particular day, then that day will not be included in the `data` object; however, it will be included in the `dates` array.\n- If dimensions are included in the request, then the data will be nested for each dimension included. Dimensions are nested in the order they are included in the request. See the example below for clarification.\n- `dates` is an array of the time periods covered by the query. For grouping by weeks, each value in the array is the first day of the week starting on Monday. For grouping by months, each value in the array is the first day of the month.\n- `lookups` contains friendly names for the keys contained in `data`. For example, if grouping by `customerId`, the lookups would contain a mapping from the customer ID to the customer name.\n\n### \n\nAn example request and response are included below:\n\n```plaintext\n// Request\n// POST /reporting/time-series\n{\n \"dateDimension\": \"week\",\n\t\"startDate\": \"2022-12-01\",\n\t\"endDate\": \"2022-12-31\",\n\t\"metric\": \"totalCount\",\n\t\"timezone\": \"America/New_York\",\n\t\"filters\": {\n\t\t\"assigneeId\": [\n\t\t\t\"63335fa9-ffcc-4103-8905-e4440cc7c7d4\",\n\t\t\t\"2e8dab53-a7a2-4e1f-b9d9-66018b98365d\"\n\t\t]\n\t},\n\t\"dimensions\": [\"customerId\", \"sourceType\"]\n}\n\n// Response\n{\n \"lookups\":{\n \"customerId\":{\n \"9YQjOSTFXeOPF8xNURFd\": \"Customer 1\",\n \"AWEpBY0uqxfp73HaTVS4\": \"Customer 2\",\n\t\t\t \"aZHO2af1RFa92QiOq3Y4\": \"Customer 3\"\n },\n \"sourceTypes\":[]\n },\n \"dates\":[\n \"2022-11-28\",\n \"2022-12-05\",\n \"2022-12-12\",\n \"2022-12-19\",\n \"2022-12-26\"\n ],\n \"data\":{\n \"9YQjOSTFXeOPF8xNURFd\":{\n \"slack\":{\n \"2022-11-28\":19,\n \"2022-12-12\":70,\n \"2022-12-19\":17\n },\n\t\t\t \"widget\":{\n \"2022-11-28\":6,\n \"2022-12-12\":1\n }\n },\n \"AWEpBY0uqxfp73HaTVS4\":{\n \"email\":{\n \"2022-12-31\":1\n },\n\t\t\t \"slack\":{\n \"2022-11-28\":6,\n \"2022-12-12\":1\n }\n },\n \"aZHO2af1RFa92QiOq3Y4\":{\n \"slack\":{\n \"2022-11-28\":6,\n \"2022-12-12\":1\n }\n }\n }\n}\n```\n\n## Surveys\n\n```plaintext\nList surveys: POST /surveys/list\nList survey responses: POST /surveys/:surveyId/responses/list\nGet survey analytics (CSAT): GET /surveys/:surveyId/analytics\n```\n\n## Slack Integration\n\n### Update Slack User Group\n\n```plaintext\nPATCH /slack/usergroup\n```\n\nThis endpoint updates a Slack user group.\n\nParameters:\n\n- `email` (required): The email address of the user to update.\n- `slackHandle` (required): The Slack handle of the user to update.\n\nExample request:\n\n```plaintext\n{\n \"email\": \"test@example.com\",\n \"slackHandle\": \"test\"\n}\n```\n\n## \n\n## Tags\n\n### Get Tag by ID\n\n```plaintext\nGET /tags/:tagId\n```\n\nThis endpoint will return the given tag.\n\n### Update Tag\n\n```plaintext\nPATCH /tags/:tagId\n```\n\nThis endpoint will return the updated tag. Fields that can be updated are: `name`.\n\n### Create Tag\n\n```plaintext\nPOST / tags;\n```\n\nThis endpoint will return the newly created tag. Fields that can be updated or set on create are: `name`\n\n### Delete Tag\n\n```plaintext\nDELETE /tags/:tagId\n```\n\nThis endpoint will delete the given tag.\n\n### List Tags\n\n```plaintext\nPOST / tags / list;\n```\n\nThis endpoint will return a list of tags.\n\n### Add Tag to Customers\n\n```plaintext\nPOST /tags/:tagId/customers/create-links\n```\n\nThis endpoint takes an array of customer IDs and will assign the given tag to all the specified customers.\n\nSample request body: `[ '93ba5298-a23f-413b-94fe-73e0ab26a816', '7ab46970-19ec-492e-90fe-47a8abc93fec' ]`\n\n### Add Tag to Conversations\n\n```plaintext\nPOST /tags/:tagId/conversations/create-links\n```\n\nThis endpoint takes an array of conversation IDs and will assign the given tag to all the specified conversations.\n\nSample request body: `[ 'ad00e2d0-4ea4-45c4-9b5d-8728f93e51a7', 'e82cde04-0d59-4416-b5da-1f405f6d4ddb' ]`\n\n### Remove Tag from Customers\n\n```plaintext\nPOST /tags/:tagId/customers/delete-links\n```\n\nThis endpoint takes an array of customer IDs and will remove the given tag from all the specified customers.\n\n### Remove Tag from Conversations\n\n```plaintext\nPOST /tags/:tagId/conversations/delete-links\n```\n\nThis endpoint takes an array of conversation IDs and will remove the given tag from all the specified conversations.\n\n## Ticket Types\n\n### Create Ticket Type\n\n```plaintext\nPOST / ticket - types;\n```\n\nThis endpoint creates a new ticket type. Example request body:\n\n```plaintext\n{\n \"name\": \"Access Request\",\n \"description\": \"A request for access to a resource\",\n \"fields\": [\n {\n \"id\": \"12345678-1234-1234-1234-123456789abc\",\n \"name\": \"Application\",\n \"type\": \"single-select\",\n \"required\": true,\n \"options\": [\"Salesforce\", \"Slack\"]\n },\n {\n \"id\": \"42345678-1234-1234-1234-123456789abd\",\n \"name\": \"Access Level\",\n \"type\": \"single-select\",\n \"required\": true,\n \"options\": [\"Admin\", \"User\"],\n \"conditions\": {\n \"type\": \"simple\",\n \"simple\": {\n \"leftValueFrom\": \"conversation.ticketTypeFields['12345678-1234-1234-1234-123456789abc']\",\n \"operator\": \"equals\",\n \"rightValue\": \"Salesforce\"\n }\n }\n }\n ]\n}\n```\n\n### Update Ticket Type\n\n```plaintext\nPATCH /ticket-types/:ticketTypeId\n```\n\nThis endpoint updates a ticket type.\n\n### Delete Ticket Type\n\n```plaintext\nDELETE /ticket-types/:ticketTypeId\n```\n\nThis endpoint deletes a ticket type.\n\n### List Ticket Types\n\n```plaintext\nPOST / ticket - types / list;\n```\n\nThis endpoint lists all ticket types.\n\n### Get Ticket Type\n\n```plaintext\nGET /ticket-types/:ticketTypeId\n```\n\nThis endpoint gets a ticket type.\n\n## Users\n\n### List Users\n\n```plaintext\nPOST / users / list;\n```\n\nThis endpoint will return a list of users who are a member of your Slack workspace and have been synced into Unthread.\n\nTo return external users, pass in the `includeExternalUsers` field with a value of `true`.\n\n### Get User by ID\n\n```plaintext\nGET /users/:userId\n```\n\nThis endpoint will return the given user.\n\n### Update User by ID\n\n```plaintext\nPATCH /users/:userId\n```\n\nThis endpoint will return the given user. Supported fields on update:\n\n- `name`\n- `pronoun`\n- `title`\n- `department`\n- `organization`\n- `division`\n- `costCenter`\n- `employeeNumber`\n- `streetAddress`\n- `locality`\n- `region`\n- `postalCode`\n- `country`\n- `description`\n- `customAttributes`\n- `photo`\n- `awayUntil`\n\n### Create User Group\n\n```plaintext\nPOST /user-groups\n```\n\nCreates an Unthread user group. `name` is required. Optional fields include `description`, `photo`, `filters`, `isExternal`, `slackId`, and `projectId`.\n\nProvide `projectId` for a project-scoped group; omit it or send `null` for a workspace-wide group.\n\nCreating or updating groups requires permission to manage user groups in the relevant scope. For groups managed by a synced source, updates are limited to `slackId`.\n\n### List User Groups\n\n```plaintext\nPOST /user-groups/list\n```\n\n### Get User Group\n\n```plaintext\nGET /user-groups/:userGroupId\n```\n\n### Update User Group\n\n```plaintext\nPATCH /user-groups/:userGroupId\n```\n\n## Webhooks\n\n### Create Webhook Subscription\n\n```plaintext\nPOST / webhook - subscriptions;\n```\n\nThis endpoint will return the newly created webhook subscription. Fields that can be set on create are: `url` and `enabled`.\n\n### Update Webhook Subscription\n\n```plaintext\nPATCH /webhook-subscriptions/:webhookSubscriptionId\n```\n\nThis endpoint will return the updated webhook subscription. Fields that can be updated are: `url` and `enabled`.\n\n### Delete Webhook Subscription\n\n```plaintext\nDELETE /webhook-subscriptions/:webhookSubscriptionId\n```\n\nThis endpoint will delete the given webhook subscription.\n\n### List Webhook Subscriptions\n\n```plaintext\nGET / webhook - subscriptions;\n```\n\nThis endpoint will return a list of webhook subscriptions.\n\n## Service-Level Agreements (SLAs)\n\nThese endpoints accept service account API keys. SLA functionality must be enabled for the workspace, and the service account must have access to the relevant workspace or project. SLA policy write operations require a workspace owner/admin service account, or a project service account with permission to manage project settings.\n\n### SLA policy and instance objects\n\n```plaintext\ntype SlaMetricType =\n | \"first_response\"\n | \"resolution\"\n | \"next_reply\"\n | \"escalation_acknowledgement\"\n | \"escalation_closed\";\n\ntype SlaPolicyStatus = \"active\" | \"inactive\";\ntype SlaPriorityChangeBehavior =\n | \"adjust_target\"\n | \"reset\"\n | \"keep_original\";\n\ninterface SlaMetricTarget {\n targetMinutes: number;\n warningMinutes?: number;\n useBusinessHours: boolean;\n}\n\ninterface SlaPolicyMetric {\n id: string;\n metricType: SlaMetricType;\n targets: Record<\"_default\" | string, SlaMetricTarget>;\n}\n\ninterface SlaPolicy {\n id: string;\n projectId: string | null;\n name: string;\n description: string | null;\n status: SlaPolicyStatus;\n onPriorityChange: SlaPriorityChangeBehavior;\n metrics: SlaPolicyMetric[];\n createdAt: string;\n updatedAt: string;\n pauseConditions: SlaPauseConditions | null;\n}\n\ntype SlaInstanceStatus =\n | \"running\"\n | \"paused\"\n | \"breached\"\n | \"completed\"\n | \"cancelled\";\n\ninterface SlaInstance {\n id: string;\n conversationId: string;\n metricType: SlaMetricType | null;\n status: SlaInstanceStatus;\n startedAt: string;\n deadlineAt: string;\n warningAt: string | null;\n breachedAt: string | null;\n completedAt: string | null;\n elapsedPausedMinutes: number;\n policyName: string | null;\n slaPolicyId: string | null;\n useBusinessHours: boolean | null;\n}\n\ntype SlaPauseStatusType = \"open\" | \"in_progress\" | \"on_hold\";\n\ninterface SlaPauseConditions {\n type: \"simple\";\n simple: {\n and: Array<{\n leftValueFrom: \"conversation.subStatus.type\";\n operator: \"in\";\n rightValue: SlaPauseStatusType[];\n }>;\n };\n}\n```\n\nEach `targets` key is either `_default` or a stringified conversation priority such as `\"1\"`. `targetMinutes` must be a positive integer. When supplied, `warningMinutes` must be a positive integer smaller than `targetMinutes`.\n\n`pauseConditions` controls when active SLA timers pause. The supported status types are `open`, `in_progress`, and `on_hold`. Send `null` to disable pausing. SLA pause conditions support literal status values with the `in` or `equals` operator; advanced conditions, `or` groups, and dynamic right-hand values are not supported.\n\nWhen pause conditions change, Unthread reconciles active SLA instances against each conversation's current status.\n\n### Create an SLA policy\n\n```plaintext\nPOST /sla-policies\n```\n\nCreates a workspace-wide policy when `projectId` is null or omitted, or a project-scoped policy when `projectId` is provided.\n\n```plaintext\n{\n \"name\": \"Standard support\",\n \"description\": \"Default response and resolution targets\",\n \"projectId\": \"e9ce1893-1a81-419e-abc6-8898f4532b56\",\n \"status\": \"active\",\n \"onPriorityChange\": \"adjust_target\",\n \"metrics\": [\n {\n \"metricType\": \"first_response\",\n \"targets\": {\n \"_default\": {\n \"targetMinutes\": 60,\n \"warningMinutes\": 45,\n \"useBusinessHours\": true\n },\n \"1\": {\n \"targetMinutes\": 15,\n \"warningMinutes\": 10,\n \"useBusinessHours\": true\n }\n }\n }\n ],\n \"pauseConditions\": {\n \"type\": \"simple\",\n \"simple\": {\n \"and\": [\n {\n \"leftValueFrom\": \"conversation.subStatus.type\",\n \"operator\": \"in\",\n \"rightValue\": [\"in_progress\", \"on_hold\"]\n }\n ]\n }\n },\n}\n```\n\nReturns the created `SlaPolicy` with HTTP 201. A policy can contain one metric of each metric type.\n\n### List SLA policies\n\n```plaintext\nPOST /sla-policies/list\n```\n\nUses the standard list endpoint conventions. Service accounts need a non-viewer role.\n\n```plaintext\n{\n \"select\": [\n \"id\",\n \"projectId\",\n \"name\",\n \"description\",\n \"status\",\n \"onPriorityChange\",\n \"metrics.id\",\n \"metrics.metricType\",\n \"metrics.targets\",\n \"createdAt\",\n \"updatedAt\",\n \"pauseConditions\"\n ],\n \"where\": [\n { \"field\": \"status\", \"operator\": \"==\", \"value\": \"active\" }\n ],\n \"order\": [\"name\"],\n \"limit\": 100\n}\n```\n\nSupported order fields: `name`, `projectId`, `createdAt`, and `updatedAt`. Supported filter fields: `id`, `name`, `projectId`, and `status`.\n\n### Get an SLA policy\n\n```plaintext\nGET /sla-policies/:slaPolicyId\n```\n\nReturns the requested `SlaPolicy`. Use the optional `select` query parameter to return a comma-separated subset of fields.\n\n### Update an SLA policy\n\n```plaintext\nPATCH /sla-policies/:slaPolicyId\n```\n\nUpdates any supplied policy fields. Include a metric `id` to update that metric in place; omit the ID to create a replacement metric.\n\n```plaintext\n{\n \"name\": \"Updated support targets\",\n \"status\": \"active\",\n \"onPriorityChange\": \"keep_original\",\n \"metrics\": [\n {\n \"id\": \"8dbf1a97-7ee0-4d23-9c5f-a479717a48cb\",\n \"metricType\": \"first_response\",\n \"targets\": {\n \"_default\": {\n \"targetMinutes\": 45,\n \"warningMinutes\": 30,\n \"useBusinessHours\": true\n }\n }\n }\n ]\n}\n```\n\nReturns the updated `SlaPolicy`.\n\n### Delete an SLA policy\n\n```plaintext\nDELETE /sla-policies/:slaPolicyId\nDELETE /sla-policies/:slaPolicyId?confirm=true\n```\n\nIf the policy is referenced, the first request returns HTTP 409 with `code: \"SLA_POLICY_DELETE_REQUIRES_CONFIRMATION\"` and reference counts. Repeat with `confirm=true` to confirm deletion. A successful deletion returns HTTP 204.\n\n### List SLA instances\n\n```plaintext\nPOST /sla-instances/list\n```\n\nReturns SLA instances across conversations visible to the service account. Workspace owner, admin, or standard access is required. In addition to standard list fields, the request supports `conversationId`, `status`, `metricType`, and `dateRange` shortcuts.\n\n```plaintext\n{\n \"status\": [\"running\", \"paused\", \"breached\"],\n \"metricType\": \"first_response\",\n \"dateRange\": {\n \"field\": \"deadlineAt\",\n \"start\": \"2026-08-01T00:00:00.000Z\",\n \"end\": \"2026-08-31T23:59:59.999Z\"\n },\n \"order\": [\"deadlineAt\"],\n \"limit\": 100\n}\n```\n\n`dateRange.field` may be `startedAt`, `deadlineAt`, `warningAt`, `breachedAt`, `completedAt`, `createdAt`, or `updatedAt`. The default is `deadlineAt`.\n\n### List SLA instances for a conversation\n\n```plaintext\nPOST /conversations/:conversationId/sla-instances/list\n```\n\nReturns SLA instances for one visible conversation and supports the same filters as the workspace-wide instance list. Workspace owner, admin, standard, and viewer service accounts can call this endpoint.\n\n### Assign SLA policies\n\nThe following existing endpoints are also open to service accounts. Send a policy ID to assign it, or `null` to clear it:\n\n- `PATCH /conversations/:conversationId` with `{ \"slaPolicyId\": \"...\" }`\n- `PATCH /customers/:customerId` with `{ \"slaPolicyId\": \"...\" }`\n- `PATCH /accounts/:accountId` with `{ \"slaPolicyId\": \"...\" }`\n- `PATCH /projects/:projectId` with `{ \"defaultSlaPolicyId\": \"...\" }`\n\nProject, customer, and account policies provide defaults for new conversations. A conversation's explicit `slaPolicyId` controls its active policy after creation.\n\n## Escalation Paths\n\nEscalation paths are represented as `escalation-types` in the API.\n\n### Create Escalation Path\n\n```plaintext\nPOST /escalation-types\n```\n\nCreates an escalation path. Required fields are `name` and `projectId`. Optional fields are `description`, `slackChannelId`, `assigneeSelector`, `assigneeSelectorIds`, and `prioritySelector`.\n\nFor either selector, use `0` for disabled, `1` for optional, or `2` for required. Both default to `1`.\n\n### Get Escalation Path\n\n```plaintext\nGET /escalation-types/:escalationTypeId\n```\n\nReturns the given escalation path.\n\n### List Escalation Paths\n\n```plaintext\nPOST /escalation-types/list\n```\n\nReturns escalation paths using the standard list conventions.\n\n### Update Escalation Path\n\n```plaintext\nPATCH /escalation-types/:escalationTypeId\n```\n\nUpdates the supplied fields from the create request, except `projectId`, and returns the updated path.\n\nCreating or updating escalation paths requires permission to manage the relevant project's settings.\n\n## Escalations\n\nEscalation paths configure where an escalation goes and which assignment and priority fields are available. Escalations are instances created on a conversation using one of those paths.\n\nThese endpoints use the API base URL and service account authentication described above. The service account must have access to the conversation and permission to create or update escalations.\n\n### Create Escalation\n\n```plaintext\nPOST /escalations\n```\n\nCreates an escalation and returns the created escalation. Request schema:\n\n```plaintext\ninterface CreateEscalationRequest {\n escalationTypeId: string; // destination escalation path UUID\n conversationId: string; // conversation UUID, not its friendly ticket number\n title: string; // Subject, plain text\n body?: string | null; // Additional Details, HTML\n publicNote?: string | null; // separate customer-facing note, HTML\n priority?: 3 | 5 | 7 | 9 | null; // Low, Medium, High, Critical\n assignedToGroupId?: string | null;\n assignedToUserId?: string | null;\n}\n```\n\nThe destination path must belong to the conversation's project. The path's required-assignee and required-priority settings still apply.\n\n**Additional Details maps to** `body`**.** It is distinct from the path's `description` and the escalation's customer-facing `publicNote`. Send HTML in `body` to preserve rich text, lists, and links.\n\n### Get Escalation by ID\n\n```plaintext\nGET /escalations/:escalationId\n```\n\nReturns the escalation, including `id`, `conversationId`, `escalationTypeId`, `title`, `body`, `priority`, `assignedToGroupId`, `assignedToUserId`, and `status` (`pending`, `acknowledged`, or `resolved`).\n\n### List Escalations\n\n```plaintext\nPOST /escalations/list\n```\n\nUses the standard list conventions. For example, find unresolved escalations of one destination type on a conversation:\n\n```plaintext\n{\n \"select\": [\"id\", \"title\", \"body\", \"priority\", \"status\"],\n \"where\": [\n { \"field\": \"conversationId\", \"operator\": \"==\", \"value\": \"CONVERSATION_UUID\" },\n { \"field\": \"escalationTypeId\", \"operator\": \"==\", \"value\": \"DESTINATION_PATH_UUID\" },\n { \"field\": \"status\", \"operator\": \"in\", \"value\": [\"pending\", \"acknowledged\"] }\n ],\n \"limit\": 100\n}\n```\n\n### Update Escalation\n\n```plaintext\nPATCH /escalations/:escalationId\n```\n\nAccepts `title`, `body`, `priority`, `assignedToGroupId`, `assignedToUserId`, and `status`. The response is the updated escalation. The conversation and escalation path cannot be changed through this endpoint.\n\n### Mirror an Escalation with a Custom Function\n\nUse the **Escalation Created** automation trigger. The triggering escalation is already available to the function as `input.escalation`, including `title`, `body`, `priority`, `conversationId`, and `escalationTypeId`. No extra GET is needed to access those values.\n\nReuse the original escalation's `title`, `body`, `priority`, and `conversationId` in `unthreadClient.post('/escalations', ...)`, and supply a fixed destination `escalationTypeId` and assignee. The client supplies the base URL and authentication automatically. It returns a Fetch `Response`; check `response.ok` and use `response.json()` to read the result.\n\nRestrict mirroring to the intended ticket types and check `input.escalation.escalationTypeId` against the source path before creating a mirror. The mirror itself also fires **Escalation Created**.\n\nThe built-in Create Escalation action skips creation when an unresolved escalation of the destination type already exists on that conversation. Direct API creation does not provide that check; custom functions need their own duplicate-prevention handling.\n\nMirroring creates a snapshot of the subject, details, and priority. It does not continuously synchronize replies, status changes, or later edits.","2023-12-03T18:55:47.916Z","2026-11-06T17:18:11.132Z","72d90ae5-34de-42da-ad47-64b60c6b0d09",[],[],[],"Analytics","analytics","bar-chart","2025-09-09T20:08:44.731Z","2025-10-08T20:19:55.221Z","a45d37f7-afe5-49cf-836a-6c15ba59769b",[475,476,477,478,479,480,481,482,483],[],{"_57":555,"_134":556,"_136":-5,"_137":557,"_139":472,"_140":-5,"_141":558,"_143":559,"_22":560,"_24":25,"_145":561,"_147":-5,"_148":562,"_150":563},{"_57":546,"_134":547,"_136":-5,"_137":548,"_139":472,"_140":-5,"_141":549,"_143":550,"_22":551,"_24":25,"_145":552,"_147":-5,"_148":553,"_150":554},{"_57":537,"_134":538,"_136":-5,"_137":539,"_139":472,"_140":-5,"_141":540,"_143":541,"_22":542,"_24":25,"_145":543,"_147":-5,"_148":544,"_150":545},{"_57":528,"_134":529,"_136":-5,"_137":530,"_139":472,"_140":-5,"_141":531,"_143":532,"_22":533,"_24":25,"_145":534,"_147":-5,"_148":535,"_150":536},{"_57":519,"_134":520,"_136":-5,"_137":521,"_139":472,"_140":-5,"_141":522,"_143":523,"_22":524,"_24":25,"_145":525,"_147":-5,"_148":526,"_150":527},{"_57":510,"_134":511,"_136":-5,"_137":512,"_139":472,"_140":-5,"_141":513,"_143":514,"_22":515,"_24":25,"_145":516,"_147":-5,"_148":517,"_150":518},{"_57":501,"_134":502,"_136":-5,"_137":503,"_139":472,"_140":-5,"_141":504,"_143":505,"_22":506,"_24":25,"_145":507,"_147":-5,"_148":508,"_150":509},{"_57":493,"_134":-5,"_136":-5,"_137":494,"_139":472,"_140":-5,"_141":495,"_143":496,"_22":497,"_24":25,"_145":498,"_147":-5,"_148":499,"_150":500},{"_57":484,"_134":485,"_136":-5,"_137":486,"_139":472,"_140":-5,"_141":487,"_143":488,"_22":489,"_24":25,"_145":490,"_147":-5,"_148":491,"_150":492},"Volume Analytics","volume-analytics","## Introduction\n\nNavigate to **Analytics > Volume** to view conversation volume metrics and understand your support team’s workload patterns. Every support team has its busy seasons and quiet moments. Volume analytics help you spot patterns in conversation volumes and understand your workload trends over time.\n\n## Key Report Types\n\n- **Message Volume** - Total number of messages received or sent within a period\n- **Daily Averages** - Average message volume per day\n- **Day of Week Analysis** - Volume patterns by day of the week\n- **Hourly Breakdown** - Volume patterns by hour of the day\n\n**ℹ️** *Volume analytics help you plan staffing, identify peak support hours, and understand seasonal patterns in customer inquiries.*\n\n## Understanding Your Data\n\n### Message Volume Trends\n\nTrack the total number of conversations and messages over time to identify:\n\n- Peak support periods\n- Seasonal patterns\n- Growth trends\n- Channel-specific volume differences\n\n### Daily and Hourly Patterns\n\nAnalyze your data by day of week and hour to:\n\n- Plan optimal staffing schedules\n- Identify when customers need support most\n- Balance workload across your team\n- Prepare for busy periods\n\n### Channel Performance\n\nCompare volume across different channels (Slack, email, in-app chat) to:\n\n- Understand customer preferences\n- Allocate resources effectively\n- Optimize channel-specific processes\n\n### Daily Operations\n\nReview volume analytics as part of your daily routine to:\n\n- Understand current workload\n- Plan team capacity\n- Identify unusual spikes in volume\n- Monitor channel distribution\n\n### Weekly Planning\n\nUse weekly volume data to:\n\n- Plan staffing for the upcoming week\n- Identify recurring patterns\n- Adjust processes based on volume trends\n- Celebrate volume milestones\n\n### Monthly Analysis\n\nLeverage monthly volume insights for:\n\n- Strategic planning\n- Resource allocation\n- Process optimization\n- Performance benchmarking\n\n## Related Pages\n\n- [Performance Analytics](https://docs.unthread.io/docs/analytics/performance-analytics)\n- [Board Builder](https://docs.unthread.io/docs/analytics/board-builder)\n- [Analytics Overview](https://docs.unthread.io/docs/analytics/analytics-overview)","2025-09-09T18:48:12.938Z","2026-05-13T21:00:36.327Z","38dfaed6-c54a-4cf1-b2a0-115afdf4bf0e",[],[],[],"Scheduling Emailed Reports","To schedule emails of **Reports** and **Boards** create an automation with the Trigger of Scheduled.\n\n- Set your cadence for email delivery - Daily, Weekly, Monthly, or Custom\n- Set the time of day for email delivery\n- Add a \"**Send Report**\" step to the automation\n- Select the Report or Board you would like to schedule send\n- Select the individual or group you would like the scheduled email delivered to\n- Add an email subject\n\n![image.png](/api/knowledge-base/images/a13758b3-4799-4971-a39c-17a4e0564191)","2026-05-21T20:04:29.628Z","2026-05-21T20:05:14.523Z","3c1ae11e-238e-4e26-9585-1da02abc623c",[],[],[],"Performance Analytics","performance-analytics","## Introduction\n\nPerformance analytics allow you to visualize tickets by grouping them using different values. These reports help you understand how your team is performing across various metrics and identify areas for improvement.\n\nUnthread includes a range of out-of-the-box report types to help teams track key support metrics and gain insights into their support operations.\n\n## Report Types\n\nBefore reviewing these variables, we’ll review the different report types available in performance analytics.\n\nYou’ll notice that some of these report types have two variables:\n\n- **P95 and P99** represent the 95th and 99th percentiles of response times, respectively. This means that 95% (or 99%) of requests are completed within the reported P95 (or P99) latency.\n\n# \n\n## Core Performance Metrics\n\n- **Conversations Created:** Total number of tickets opened\n\n- **First Response (FR) Time** (in minutes): Time between ticket creation and first response by an Agent. A teammate’s response won’t be counted as a first response. Agents can use emoji triggers to manually set the FR message.\n\n- **Resolution Time** (in minutes): Time between ticket getting created and resolved. -If a ticket gets created at t0, closed at t1, re-opened at t3, and re-closed at t4, the resolution time will be the time between t0 and t4\n\n- **Waiting on Customer Time**: Total amount of time the ticket is in Open status\n\n- **Waiting on Agent Time**: Total amount of time the ticket is in In Progress status\n\n- **Ticket Active Duration**: Total amount of time the ticket is in In Progress or Open status type\n\n### Which metric captures an accurate resolution time on a ticket that is closed and then re-opened?\n\nTicket Active Duration excludes time when the ticket is in the closed status before it is re-opened again.\n\n## Escalation Reports\n\n- **Ticket to Escalation Time**: Time from ticket creation to when it’s escalated by a team member\n\n- **Escalation to Acknowledgement Time**: Time between when an escalation is created and when it’s acknowledged by the partner team\n\n- **Acknowledgement to Resolution Time**: Time from when the escalation is acknowledged to when it’s resolved. **Note: This refers specifically to the resolution of the escalation, not the main ticket. Unless automated, resolving an escalation does not automatically resolve the parent ticket.**\n\n ![analytics-ReportTypes.png](https://firebasestorage.googleapis.com/v0/b/trnout-co.appspot.com/o/unthread-unthread-e4pm8%2Fknowledge-base%2Fanalytics-ReportTypes.png?alt=media)\n\n## Filtering and Breakdowns\n\nAll dashboards are fully filterable by default attributes like assignee, date range, tags, ticket type, and status, as well as any custom fields tied to your ticket types. Use the filters at the top of each report to drill down by time, submitters, or specific properties.\n\n![analytics-filters.png](https://firebasestorage.googleapis.com/v0/b/trnout-co.appspot.com/o/unthread-unthread-e4pm8%2Fknowledge-base%2Fanalytics-filters.png?alt=media)\n\nIn addition to filtering, Unthread offers advanced breakdowns to give teams more granular insights.\n\n![analytics-breakdown.png](https://firebasestorage.googleapis.com/v0/b/trnout-co.appspot.com/o/unthread-unthread-e4pm8%2Fknowledge-base%2Fanalytics-breakdown.png?alt=media)\n\nEach report type also includes a table view, displaying the data broken down by your selected time intervals for easy analysis.\n\n![analytics-table.png](https://firebasestorage.googleapis.com/v0/b/trnout-co.appspot.com/o/unthread-unthread-e4pm8%2Fknowledge-base%2Fanalytics-table.png?alt=media)\n\n## Key Performance Insights\n\n### First Response Time\n\nYour customers’ first impression of your support often comes down to one thing: how quickly you respond. Analytics helps you track this critical metric from the moment a conversation starts, showing you exactly how quickly your team is serving up solutions.\n\nStart by exploring your first response times—this tells you how long customers wait before getting their first reply. Then dive into resolution times to see how efficiently your team closes out issues.\n\n### Resolution Time\n\nTrack how efficiently your team closes out issues and meets customer needs. Monitor trends to identify process improvements and training opportunities.\n\n### Waiting on Agent Time\n\nUnderstand bottlenecks in your support process by tracking how long tickets wait for agent attention. Use this data to optimize staffing and workflow.\n\n## Breaking Down Results\n\nIn this section, we’ll dive into how our report viewer can be used to drill down into specific data.\n\nFor the purposes of this walkthrough, we’ll use the “Conversation Created” report.\n\nWhen viewing any report, you’ll find a number of categories above the chart which can be used to group the data presented. For example, you can select “source” to visualize all conversations created by their source, be it Slack, email, or otherwise.\n\nYou can also apply this grouping to any custom fields you have configured.\n\n## Chart Visualization Options\n\nThese charts can be visualized in a few ways. You can change this by selecting chart options below the default line chart:\n\n- **Bar Chart** - Useful for comparing different categories\n- **Card View** - Presents you with the actual values for the dataset\n- **Line Chart** - Default view, great for trends over time\n\n**Show Legend** will display the categories for a given selection and will allow you to remove categories from the view by clicking on them.\n\nFinally, you can view this with **working hours enabled**, which will only pull metrics for tickets created during your configured working hours.\n\n**ℹ️** *These working hours can be set at the project level, so you want to be sure each project aligns with the hours the corresponding team provides support in order to keep the data from being skewed incorrectly. To set your working hours, go to \"Setup\" > \"Project Settings\" for your project.*\n\n## Sharing and Exporting Reports\n\n### Saving Reports\n\nIf you have a report that you view frequently, we recommend saving this report. To do so, configure the report with the format that is most helpful and then click the save option in the top right.\n\nSaving these reports will also allow you to use the chart in the board builder.\n\n### Sharing Reports\n\nShare your performance reports with team members, stakeholders, or executives to keep everyone informed about your support team’s performance. Shared reports update automatically, so everyone always sees the latest data.\n\nTo share a report:\n\n1. Open any saved report\n2. Click the “Share” button in the top right\n3. Copy the generated link\n4. Send the link to your intended recipients\n\n**ℹ️** *Shared reports maintain all your filters and settings, so recipients see exactly the same view you’ve configured.*\n\n### Exporting Data\n\nDownload your performance data as CSV files for external analysis, presentations, or reporting to stakeholders. This is perfect for:\n\n- Creating custom reports in Excel or Google Sheets\n- Sharing data with external stakeholders\n- Archiving performance data for historical analysis\n- Creating presentations for executive reviews\n\nTo export data:\n\n1. Configure your report with the desired filters and date range\n2. Save the report, if desired.\n3. Click the download button in the top right\n\n## Related Pages\n\n- [Analytics Overview](https://docs.unthread.io/docs/analytics/analytics-overview)\n- [Board Builder](https://docs.unthread.io/docs/analytics/board-builder)","2025-09-09T18:48:11.194Z","2026-08-14T18:05:14.118Z","29437d5b-06f8-4209-bec3-8a23e11413cf",[],[],[],"Excluding conversations from Analytics Data","excluding-conversations-from-analytics-data","## How to bulk exclude conversations from your Analytics\n\nIf you have older test conversations and data that you would like to exclude from your Analytics you can do so in bulk or on a per conversation basis.\n\n- Navigate to the inbox view of the dashboard\n- To bulk exclude conversations select all and then select \"More\" and choose the \"exclude from Analytics\" option\n\n![Unthread - 25 June 2026 (1) (1).gif](/api/knowledge-base/images/b5f1a593-c11b-4899-82fc-16698d1b09f3)\n\n## How to exclude individual conversations from your Analytics\n\n- Navigate to the conversation within the Unthread dashboard\n- Click the ... for more options at the top\n- Select \"exclude from Analytics\"\n\n![1894 Question about stale conversation prompt – Unthread - 25 June 2026.gif](/api/knowledge-base/images/d3e35203-bcaa-4b07-94f5-248f1ea4e790)","2026-06-25T14:51:25.780Z","2026-06-25T17:08:26.014Z","883ae09a-fefa-47d4-9081-9aef59d7f44a",[],[],[],"Channel Health Scores","health-scores","![CleanShot 2026-05-08 at 15.18.38@2x.png](/api/knowledge-base/images/bf0c87a5-b77c-4fa3-bb9f-68ceaa2fce60)\n\nHealth scores help teams quickly understand which customer or support channels may need attention. Each score is calculated on a 0-100 scale, where higher means healthier and lower means more risk.\n\n## **What the Score Measures**\n\nPulse starts every channel at 100, then subtracts penalties for risk signals found in the selected reporting window.\n\nThe main score factors are:\n\n| **Factor** | **What it measures** | **Max penalty** |\n| --- | --- | --- |\n| Sentiment pressure | Average ticket sentiment below neutral | 20 |\n| High-severity load | Share of tickets marked high priority or above | 25 |\n| Unresolved backlog | Share of tickets not closed | 20 |\n| Volume spike | Ticket volume increase vs the prior same-length period | 15 |\n| Repeat issue concentration | One ticket type dominating more than 50% of volume | 20 |\n| Poor survey feedback | Low CSAT/NPS responses linked to tickets | 30 |\n\nFinal score:\n\n`Health score = 100 - total penalties`\n\nThe final value is rounded and kept between 0 and 100.\n\n## **How Each Factor Works**\n\nPulse compares tickets in the current date range against the prior same-length date range.\n\nFor example, if the current range is the last 30 days, Pulse compares it to the 30 days before that.\n\nA few important details:\n\n- Missing sentiment does not hurt the score.\n- Neutral or positive sentiment does not add a penalty.\n- CSAT and NPS are converted to a shared 0-100 satisfaction scale.\n- No survey responses means no survey penalty.\n- Channels with no reportable tickets in the selected range will not have health data yet.\n- Top tag is shown for context, but it does not directly affect the score.\n- Top ticket type can affect the score when one type makes up more than half of volume.\n\nProject owners can also add scoring priorities. These adjust how much Pulse emphasizes or de-emphasizes each factor, while keeping every factor within its normal cap.\n\n## **Trend and Risk Labels**\n\nPulse also compares the current score to the prior score.\n\n- Improving: current score is more than 5 points higher\n- Worsening: current score is more than 5 points lower\n- Flat: score changed by 5 points or less\n\nRisk labels are based on the score and the underlying risk mix:\n\n- Healthy: score is 80 or higher\n- Monitor: moderate score without severe risk concentration\n- Needs attention: score below 70 with a high share of severe tickets\n- Churn risk: score below 50 with more than 30% unresolved tickets\n- Critical: same as churn risk, but used for internal support projects\n\n## **How Often Scores Are Calculated**\n\nYou can set a default period for calculation, with 30 days being the default. These are calculated continuously so you should always be seeing the most up-to-date information in your channel list.\n\n## **Example Calculation**\n\nA channel has 10 tickets in the selected range:\n\n- Average sentiment is 40 out of 100\n- 3 tickets are high severity\n- 4 tickets are unresolved\n- Volume is flat vs the prior period\n- One ticket type represents 60% of volume\n- Survey satisfaction is healthy\n\nPulse might calculate:\n\n`Sentiment penalty: 4`\\\n`High-severity penalty: 7.5`\\\n`Unresolved penalty: 8`\\\n`Volume spike penalty: 0`\\\n`Repeat issue penalty: 4`\\\n`Survey penalty: 0`\\\n\\\n`Total penalty: 23.5`\\\n`Health score: 100 - 23.5 = 76.5, rounded to 77`\n\n## **Common Use Cases**\n\nUse Pulse health scores to:\n\n- Prioritize which customer channels need attention first\n- Spot volume spikes before they become escalations\n- Identify recurring issues by reviewing top ticket types and tags\n- Track whether a channel is improving after an intervention\n- Prepare for customer check-ins, QBRs, or internal service reviews\n- Find internal support queues with unresolved backlog or high-severity load\n- Compare channel health across a project using the same date range","2026-05-08T19:17:51.282Z","2026-05-11T18:59:22.859Z","3956715e-42e1-4faa-aeed-ca0489d2becb",[],[],[],"Board Builder","board-builder","![exec-dashboard.png](/api/knowledge-base/images/e26bdcef-c1a4-4fc4-965b-a8cb542df659)\n\n## Introduction\n\nNavigate to **Analytics > Dashboards** section to create powerful live dashboards by combining existing reports.\n\nOur Board Builder allows you to combine saved reports into a single view. You can use these boards to track metrics that are most important to you or use the TV Mode feature to output this to a display for real-time updates.\n\n**ℹ️** _Board Builder is perfect for executives and stakeholders who need a high-level view of your support operations at a glance._\n\n## Creating Your Dashboard\n\n### Step 1: Open the Dashboard Builder\n\n1. Go to **Analytics > Dashboards** in your dashboard\n2. Click “Create New Board” to start building\n3. Give your board a descriptive name\n\n### Step 2: Add Reports\n\n1. Select from your saved reports\n2. Choose the layout and positioning for each report\n3. Configure display options for each widget\n\n### Step 3: Customize Your View\n\n- **Layout Options** - Choose from grid layouts to arrange your reports\n- **Size Controls** - Resize reports to emphasize important metrics\n- **Auto-refresh** - Set refresh intervals for real-time updates\n\n![Analytics-Dashboard.png](/api/knowledge-base/images/7dd40f4e-0ddf-4b93-a8b3-821c9cefaf0c)\n\n## TV Mode\n\nUse TV Mode to display your dashboard on a monitor or TV screen for:\n\n- **Team visibility** - Keep everyone informed of current metrics\n- **Real-time monitoring** - Display live updates during busy periods\n- **Executive dashboards** - Provide leadership with key insights\n- **War rooms** - Centralized monitoring during critical situations\n\n### Setting Up TV Mode\n\n1. Create your board with the reports you want to display\n2. Click Preview\n3. Select TV Mode\n\n## Best Practices\n\n### Dashboard Design\n\n- **Keep it focused** - Include only the most important metrics\n- **Use consistent layouts** - Maintain visual hierarchy\n- **Consider your audience** - Tailor content for different stakeholders\n- **Regular updates** - Refresh dashboards as your needs evolve\n\n### Performance Optimization\n\n- **Limit report count** - Too many reports can slow performance\n- **Use appropriate date ranges** - Shorter ranges for better performance\n- **Apply filters** - Reduce data volume for faster loading\n- **Schedule updates** - Set reasonable refresh intervals\n\n## Common Use Cases\n\n### Executive Dashboard\n\n- High-level performance metrics\n- Customer satisfaction scores\n- Volume trends\n- Team productivity indicators\n\n### Operations Dashboard\n\n- Real-time response times\n- Open conversation counts\n- Agent workload distribution\n- SLA compliance metrics\n\n### Team Dashboard\n\n- Individual performance metrics\n- Channel-specific data\n- Quality indicators\n- Improvement opportunities\n\n## Related pages\n\n- [Performance Analytics](https://docs.unthread.io/docs/analytics/performance-analytics)\n- [AI Analytics](https://docs.unthread.io/docs/analytics/ai-analytics)\n- [Volume Analytics](https://docs.unthread.io/docs/analytics/volume-analytics)\n- [Analytics Overview](https://docs.unthread.io/docs/analytics/analytics-overview)\n","2025-09-09T18:48:13.198Z","2026-08-31T19:31:43.827Z","4e75cbc7-b67a-4946-a420-203034aff02d",[],[],[],"Audit Logs","audit-logs","Unthread Audit Logs is an **admin-only** page that captures key account and configuration events. This allows you to understand the who, when, and why of changes in your account.\n\n> **Note**: this feature is only available on the Enterprise plan.\n\n## Events Captured\n\n### Authentication & Access\n\n- Login / logout\n- Portal user registration\n- Portal password reset request\n- User impersonation (dashboard + portal)\n- SSO config changes (enabled/disabled, protocol)\n- Auth method changes (password/Google sign-in toggled)\n- API key created / revoked\n\n### User Management\n\n- User created (name, email, role)\n- User updated (role, name, email, status — role changes flagged as high importance)\n- User deactivated / reactivated\n- User deleted\n\n### Service Accounts\n\n- Service account created / disabled / enabled\n- API key created / revoked\n\n### [Projects](https://docs.unthread.io/docs/setting-up-your-account/projects-permissions)\n\n- Project created / deleted\n- Project settings updated (name, visibility, description, escalation settings, AI features, channel settings, intake settings, autoresponder settings, etc.)\n\n### Automations\n\n- Automation created / deleted\n- Automation updated (name, status, trigger)\n\n### Org / Tenant Settings\n\n- Tenant settings updated (name, support branding, permissions, working hours, AI features, Slack inbox config, integrations, post-close settings, allowed priorities, customer view settings, AI usage limits, allowed email domains, etc.)\n\n## Metadata included with each audit log entry\n\nEvery entry captures (when available):\n\n- Who performed the action (user, automation, or system)\n- Source (Dashboard, API, Slack, Portal, etc.)\n- IP address + geo location (city, region, country)\n- Auth method (session, API key, etc.)\n- Timestamp","2026-04-01T18:26:21.692Z","2026-06-26T18:52:37.932Z","e5d8442f-9d0c-415f-9de5-ab86a23b9790",[],[],[],"Analytics Overview","analytics-overview","## Introduction\n\nWelcome to Unthread Analytics! Whether you’re just getting started or looking to dive deeper, this guide will help you understand and optimize your customer support operations using data.\n\nThink of analytics as your support team’s compass—it shows you where you’ve been, where you are now, and helps you navigate toward better customer experiences.\n\n## Getting Started: Your First Steps\n\n1. **Navigate to Analytics**\n\n Go to **Dashboard > Analytics** in the main menu\n\n2. **Start with Response Times**\n\n Begin with first response time reports to understand your team’s current performance\n\n3. **Save Your First Report**\n\n When you find a view you like, save it as a report for quick access later\n\n4. **Build Your Dashboard**\n\n Use the board builder to combine multiple reports into a comprehensive view\n\n5. **Set Up Regular Reviews**\n\n Schedule time to review your analytics regularly\n\n 🎦 [See AI insights transform ticket analytics in action.](https://www.loom.com/share/8da07b9fe84146759d4860f8265079cc?sid=5e1470a7-35a3-4a3d-b44a-f7b3a9c04d67)\n\n## What You Can Track\n\n### [Performance Analytics](https://docs.unthread.io/docs/analytics/performance-analytics)\n\nSee how quickly your team responds to customers and resolves issues. Track response times, resolution times, and overall team efficiency to spot areas for improvement.\n\n### [Volume Analytics](https://docs.unthread.io/docs/analytics/volume-analytics)\n\nUnderstand your workload patterns and conversation volumes. Identify when you’re busiest and plan your staffing accordingly.\n\n### [AI Analytics](https://docs.unthread.io/docs/analytics/ai-analytics)\n\nSee how well your AI assistant is performing. Track deflection rates and understand how effectively your AI handles customer inquiries.\n\n### [Board Builder](https://docs.unthread.io/docs/analytics/board-builder)\n\nCreate custom dashboards that combine multiple reports. Great for executives and stakeholders who need a high-level view of everything.\n\n## Your Analytics Dashboard\n\n### Real-Time Updates\n\nYour analytics update in real-time, so you’re always looking at current data. No more wondering if your reports are stale—what you see is what’s happening right now!\n\n### Interactive Dashboards\n\nUse the board builder to create custom dashboards that display multiple reports side by side. This is where the magic happens—your personal mission control for monitoring the metrics that matter most to your team.\n\n### Smart Filtering\n\nFilter your data by assignee, customer, channel, priority, status, and custom fields to focus on specific aspects of your support operations.\n\n### Export Your Data\n\nDownload your analytics data as CSV files for external analysis, presentations, or reporting to stakeholders.\n\n### Business Hours Focus\n\nToggle between all hours and business hours to focus on working time metrics—perfect for operational planning and SLA monitoring.\n\n## How Teams Use Analytics\n\n## ![AnalyticsReportType.gif](https://firebasestorage.googleapis.com/v0/b/trnout-co.appspot.com/o/unthread-unthread-e4pm8%2Fknowledge-base%2FAnalyticsReportType.gif?alt=media)\n\n### Daily Operations: Your Morning Check-in\n\nStart your day by checking your analytics dashboard. Monitor response times and open conversation counts to understand your current workload. Check AI deflection rates and review volume patterns to ensure balanced distribution.\n\n### Weekly Reviews: The Big Picture\n\nSet aside time each week to analyze resolution times and customer satisfaction scores. Review escalation rates and channel performance to identify bottlenecks and celebrate wins.\n\n### Monthly Planning: Strategic Insights\n\nUse monthly analytics reviews to assess overall team performance trends. Review customer satisfaction and sentiment trends to understand long-term patterns.\n\n## \n\n## Getting the Most Out of Analytics\n\n### Start Simple\n\nDon’t try to track everything at once. Begin with 2-3 key metrics that align with your team’s goals, then gradually expand your analysis.\n\n### Set Your Baselines\n\nDocument your current performance levels and set realistic improvement targets. Track your progress over time to measure success.\n\n### Make It a Habit\n\nSchedule regular analytics reviews with your team. Use the data to inform process improvements and recognize achievements.\n\n### Optimize Performance\n\n- Use business hours filtering for operational metrics\n- Limit date ranges for better performance\n- Apply filters early to reduce data volume\n- Save frequently used reports for quick access\n\n## Need Help?\n\nFor technical issues or questions about analytics functionality:\n\n- **In-app Help**: Click on the Unthread icon in the analytics interface\n- **Documentation**: Refer to the detailed guides linked above\n- **Still need assistance?**: Shoot us a note at [hello@unthread.io](mailto:hello@unthread.io) or send us a message in your dedicated Slack channel.\n\n## Related Pages\n\n- [**API Reference**](https://docs.unthread.io/docs/api-docs/api-reference)","2025-09-09T18:48:17.333Z","2026-07-30T19:54:14.714Z","bac5f324-40af-44b9-adbc-8aaafbbbbbd7",[],[],[],"AI Analytics","ai-analytics","## Introduction\n\nNavigate to **Analytics > AI** to view AI performance metrics and understand how your AI assistant is handling customer inquiries.\n\nThis view breaks tickets down by whether agent interaction was needed. For tickets that were deflected, you’ll see a more in-depth grouping.\n\n![ai-deflection-2026-06-04.png](/api/knowledge-base/images/adac55b0-05c0-4edb-a29b-bb998c6cbda8)\n\n## Key metrics: “AI engaged” vs “Deflected conversations”\n\n### AI engaged\n\n**AI engaged** counts conversations where **Unthread AI was engaged** in the conversation.\n\n### Deflected conversations\n\n**Deflected conversations** counts conversations that are **marked as “deflected.”**\n\n### Why the counts can differ\n\nThese counts can differ if your team is **marking tickets as “deflected” via the Unthread API**, even when **Unthread AI is not engaged**. This may happen when an external script/process marks conversations as deflected.\n\n## Deflection Categories\n\nWe’ll highlight the deflection categories below:\n\n- **Closed by Internal User** - The ticket was closed manually by an agent\n- **Closed by Submitter** - The customer closed the ticket themselves after receiving an AI response\n- **Stale Intake** - The user was served a reply by the bot, but there was no explicit indication by the user. This typically indicates that they got the answer that they wanted and then moved on.\n- **Closed by API** - An external script/process you have set up is marking the conversations as deflected\n\n**ℹ️** *AI analytics help you understand your AI assistant’s effectiveness and identify areas where your knowledge base might need improvement.*\n\n## AI Performance Metrics\n\n### Deflection Rate\n\nTrack how often your AI successfully handles inquiries without human intervention. A higher deflection rate means your AI is effectively resolving customer issues independently. The Deflection Rate Percentage is calculated using the number of Deflected Conversation divided by the Total number of conversations during the selected time period.\n\n## AI Generated Response History\n\nHere you’ll find a list of all tickets within a time period (default is 30 days) along with the AI response and any user feedback provided. We intend this list to guide you as an admin to understand where your documentation sources could use some additional context or documents.\n\n### Using the Response History\n\n- **Review AI Responses** - See exactly what your AI assistant is saying to customers\n- **Analyze User Feedback** - Understand which responses received positive or negative feedback\n- **Identify Knowledge Gaps** - Spot areas where your documentation needs improvement\n- **Track Performance Trends** - Monitor how AI effectiveness changes over time\n\n## Related Pages\n\n- [AI Responses](https://docs.unthread.io/docs/unthread-ai/ai-generated-responses)\n- [Analytics Overview](https://docs.unthread.io/docs/analytics/analytics-overview)\n- [Knowledge Base](https://docs.unthread.io/docs/knowledge-base/knowledge-base-setup)","2025-09-09T18:48:12.610Z","2026-10-15T00:06:30.079Z","55b9c5e5-47a6-4514-8c00-bc33f4b161e7",[],[],[],"In-App Support","in-app-support","message-circle","2025-09-09T20:09:11.506Z","2025-10-08T20:23:09.750Z","6ceeb548-f7bc-40ca-80c5-4a09ea9a2206",3,[573,574,575],[],{"_57":594,"_134":595,"_136":-5,"_137":596,"_139":569,"_140":-5,"_141":597,"_143":598,"_22":599,"_24":25,"_145":600,"_147":-5,"_148":601,"_150":602},{"_57":585,"_134":586,"_136":-5,"_137":587,"_139":569,"_140":-5,"_141":588,"_143":589,"_22":590,"_24":25,"_145":591,"_147":-5,"_148":592,"_150":593},{"_57":576,"_134":577,"_136":-5,"_137":578,"_139":569,"_140":-5,"_141":579,"_143":580,"_22":581,"_24":25,"_145":582,"_147":-5,"_148":583,"_150":584},"In-App Chat Support","in-app-chatsupport","![widget-flow.png](/api/knowledge-base/images/7c6dba6e-d784-42d4-a116-b361b7e241ce)\n\nThe in-app chat widget feature allows your customers to get in touch with your support team from your website. The chat widget will appear as a small icon on your website, and when a visitor clicks on it, a chat window will open where they can enter their question or issue. Messages will be posted to Slack and your team will be able to respond in real time directly from the Slack thread.\n\n## How it Works\n\n### Live Chat on Your Site\n\n![website-chat-widget.png](/api/knowledge-base/images/4bdea93f-e242-4bc5-b679-75315149f56d)\n\nWhen embed the in-app chat bubble, your customers have a way to create new [conversations](https://docs.unthread.io/docs/managing-your-inbox/managing-your-inbox-on-the-web) right from your website. You can choose to identify users that are already logged in or ask them to provide a name and email. You can also customize the color and welcome messages to match your brand.\n\n### Creating Slack Thread\n\n![widget-thread.png](/api/knowledge-base/images/dbb076cd-8be6-4b6d-b414-1b2b004b8add)\n\nAll new tickets created from the widget will be posted to an internal thread in Slack. This is where you can easily loop in members of your team. You can also reply directly from the Slack thread by including the “/unthread send” keyword at the end of your message.\n\n### Automations\n\nYou can leverage the existing powerful functionality of Unthread:\n\n- Reply or add internal notes from your inbox\n- Enable [assignment rules and SLAs](https://docs.unthread.io/docs/conversational-ticketing/slas)\n- Set up an [automated response](https://docs.unthread.io/docs/unthread-ai/ai-generated-responses) for all new messages\n- Automatically [apply tags](https://docs.unthread.io/docs/unthread-ai/automatically-tagging-conversations-with-ai) based on question type\n- And more…\n\n### Continuing via Email\n\nIf the user hasn’t read your message within 5 minutes (meaning they may have left the page), then we will automatically send your reply via email. Users can reply to that email to continue the conversation seamlessly.\n\n## Get Started\n\n### Configuring the widget\n\n- Sign in to your Unthread dashboard and **navigate to “Channels” → “In-App Chat”.**\n- On the settings page, you can customize the appearance of the chat widget, including the color and position on your website. You can also customize the greeting message that appears when a user first opens the chat. These settings can be modified later.\n- Select a channel that chat messages will be posted to in Slack.\n- Add assignment and escalation rules.\n- Once you have customized the chat widget to your liking, click on the “Enable” button to generate the code that you will need to add to your website. This will also generate an identity verification secret. See below for how to use this to verify user identities.\n\nℹ️ _✨ Configuration settings can be updated remotely without changing any code on your site!_\n\n### Adding to Your Site\n\n- Copy the auto-generated code and paste it into the HTML of your website. The code should ideally be placed within the `` tag of your website.\n\n- The widget will be hidden by default. In order to show it, you will need to run the following Javascript code somewhere on your website:\n\n ```plaintext\n window.$unthread.inAppChat(\"start\");\n ```\n\n - This code can either be run immediately after the auto-generated snippet or you can wait to run it, for example after the user has logged in.\n\n- If you have a CSP, you’ll want to add `https://YOUR_SUBDOMAIN.unthread.io` to\n\n - script-src\n - connect-src\n - frame-src\n\n- The widget should now be visible and ready for use. By default, new users will be asked to provide their name and email address before they send their first message.\n\n- Optionally, you can pass details about the user when starting up the widget. When starting up the widget, pass a user object in the start call:\n\n ```plaintext\n window.$unthread.inAppChat(\"start\", {\n user: {\n name: \"John Smith\",\n email: \"johnsmith@acme.com\",\n },\n });\n ```\n\n - This will automatically set the name and email of the user. They will not be prompted to enter those fields themselves when they open the widget.\n\n- If you want to clear the chat history when a user logs out, run the following Javascript code on logout:\n\n ```plaintext\n window.$unthread.inAppChat(\"stop\");\n ```\n\n### Verify the Identity of Logged In Users\n\n- For added security, you can also verify that the email address actually belongs to the user. This will require the identity verification secret that was generated on the widget settings page. You will also need to be able to modify the server side code of your website.\n\n- Copy the identity verification secret and put it somewhere secure that is accessible by your website’s server. This secret should never be exposed on the frontend of your website because it can be used to impersonate other users.\n\n- When a user logs into your website, you will use the secret to generate an HMAC of the user’s email address. See below on how to generate the HMAC. The HMAC should be generated on your server and sent to your frontend as part of the login process. The HMAC will be passed as part of the user object passed to the start call.\n\n ```plaintext\n window.$unthread.inAppChat(\"start\", {\n user: {\n name: \"John Smith\",\n email: \"johnsmith@acme.com\",\n verificationHash: \"9l8ugiue98ie9u8ifbmeu897fidhe89u7fi07f\",\n },\n });\n ```\n\n- Never send sensitive information to unverified users.\n\n ### Generating the HMAC verification hash\n\n How you generate the HMAC verification hash depends on what language you use on your server. Here are some examples in different languages: **Javascript (Node.js)**\n\n ```plaintext\n const crypto = require(\"crypto\");\n\n const secret = \"\";\n const email = \"\";\n\n const verificationHash = crypto.createHmac(\"sha256\", secret).update(email).digest(\"hex\");\n ```\n\n **PHP**\n\n ```plaintext\n ';\n $email = '';\n\n $verification_hash = hash_hmac('sha256', $email, $secret);\n ?>\n ```\n\n **Ruby**\n\n ```plaintext\n require 'openssl'\n require 'base64'\n\n secret = ''\n email = ''\n\n OpenSSL::HMAC.hexdigest('sha256', secret, email)\n ```\n\n **Python**\n\n ```plaintext\n import hashlib\n import hmac\n import base64\n\n secret = bytes('', 'utf-8')\n email = bytes('', 'utf-8')\n\n hash = hmac.new(secret, email, hashlib.sha256)\n hash.hexdigest()\n ```\n\n## Using the Unthread SDK\n\nIn addition to `start` and `stop` there are few more functions available in the Unthread SDK: Toggle the visibility of the chat window:\n\n```plaintext\nwindow.$unthread.inAppChat(\"toggle\", \"show\");\nwindow.$unthread.inAppChat(\"toggle\", \"hide\");\n```\n\nToggle the visibility of the message bubble:\n\n```plaintext\nwindow.$unthread.inAppChat(\"toggleBubble\", \"show\");\nwindow.$unthread.inAppChat(\"toggleBubble\", \"hide\");\n```\n\nToggle dark mode:\n\n```plaintext\nwindow.$unthread.inAppChat(\"setDarkMode\", \"dark\");\n```\n\nor\n\n```plaintext\nwindow.$unthread.inAppChat(\"setDarkMode\", \"light\");\n```\n\nLink user to a particular Account:\n\n```plaintext\nwindow.$unthread.inAppChat(\"setAccountId\", \"ACCOUNT_ID_HERE\");\n```\n\n## Sessions and Message History\n\nIf the user has been verified, their full chat history will be available the next time they login to your website. If the user has not been verified, their chat history will only be available within their current chat session. The chat session lasts 1 week from the user’s last activity within the chat. If the user is idle for more than 1 week, their history will be cleared. Additionally, if you call the `stop` function in the SDK or the user clears their cookies, their chat history will also be cleared.\n\nℹ️ _🍪 Speaking of cookies: the widget only uses **first-party cookies**, meaning they cannot track users across different website and are more privacy-centric._\n","2024-01-26T16:43:00.434Z","2026-08-24T14:41:08.678Z","b14c6436-edf4-420e-9a96-17892aee314e",[],[],[],"Embedded Customer Portal","embedded-customer-portal","Embed your Unthread customer portal directly into your own web application so customers never leave your product to get help. The embedded portal supports authenticated access, programmatic navigation, theme customization, and event handling.\n\n## 🔍 How It Works\n\nWhen you embed the portal, a small JavaScript snippet on your page loads the portal inside an invisible `