> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raum.am/llms.txt
> Use this file to discover all available pages before exploring further.
# Install the RAUM AI Zendesk app
> Install the RAUM AI app from the Zendesk Marketplace, configure your backend URL and API key, and get AI features live inside every ticket in under 5 minutes.
The RAUM AI Zendesk app is a native Zendesk Framework (ZAF) app that embeds directly inside the Zendesk agent interface. Once installed, it adds an AI toolbar to the ticket reply composer and a real-time analysis panel to the ticket sidebar — no browser extensions, no separate tabs, no copy-pasting.
## Prerequisites
Before installing the app, make sure you have:
* A **RAUM AI account** — sign up at [raum.am/onboarding](https://raum.am/onboarding) if you haven't already
* **Zendesk admin access** to install apps from the Admin Center
* Your RAUM AI **Backend URL**, **API key**, and **Organization ID** — find these in your RAUM AI dashboard under **Settings**
***
## Installation steps
In Zendesk, click the **Admin** icon (the gear) in the left sidebar, then navigate to:
**Apps and integrations → Apps → Zendesk Support apps**
You will see a list of all apps currently installed in your Zendesk account.
The RAUM AI app is distributed as a private app package (`.zip` file).
1. Download the latest `.zip` package from your RAUM AI dashboard under **Settings → Zendesk App**, or from your account manager.
2. In the Zendesk Admin Center, click **Upload private app**.
3. Give the app a name — for example, `RAUM AI Assistant`.
4. Click **Choose file**, select the `.zip` file you downloaded, then click **Upload**.
Zendesk will validate the package and show you the app configuration screen.
During installation, Zendesk prompts you for three required settings. You can find all three values in your RAUM AI dashboard under **Settings**.
| Setting | What to enter | Where to find it |
| ------------------- | ------------------------------------------------------------------ | ---------------------- |
| **Backend URL** | Your RAUM AI backend hostname — **host only, no protocol or path** | Settings → Zendesk App |
| **API Key** | Your organization's RAUM AI API key | Settings → API Keys |
| **Organization ID** | Your RAUM AI organization identifier | Settings → General |
Enter the **Backend URL** as a hostname only — for example, `api.raum.am` — with no `https://` prefix and no trailing path. Zendesk's domain whitelist matches hosts, not full URLs. If you include the protocol, Zendesk will reject outgoing requests with an `InvalidDomain` error.
Click **Install** to finish.
By default, a newly installed private app may not be visible to all roles. To enable it:
1. In the Zendesk Admin Center, go to **People → Roles**.
2. Select the role you want to enable the app for (for example, **Agent** or a custom support role).
3. Under **Apps**, find **RAUM AI Assistant** and enable it.
4. Click **Save**.
Repeat for each role that should have access to the AI features.
Open any ticket in Zendesk as an agent with the enabled role.
Check the following:
* The **ticket editor toolbar** shows the RAUM AI buttons (Generate, Grammar Check, Translate, and others depending on the ticket channel).
* The **ticket sidebar** shows the RAUM AI analysis panel on the right side of the ticket.
If the buttons do not appear, try refreshing the page. If the sidebar panel shows an error, double-check your Backend URL, API Key, and Organization ID in the app settings.
***
## What the app adds to Zendesk
The RAUM AI app registers in two locations inside the Zendesk agent interface: the ticket editor toolbar and the ticket sidebar.
### Ticket editor toolbar
The editor toolbar gives agents a set of AI-powered writing tools that operate on the content of the reply composer. The available buttons depend on whether the ticket is an email ticket or a live chat/messaging conversation.
| Button | What it does |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Generate** | Runs the full four-step pipeline (Understand → Plan → Act → Reply) and streams a complete, context-aware response into the composer. The AI reads the ticket subject, description, conversation history, Zendesk tags, and any connected knowledge base or procedures. |
| **Grammar Check** | Corrects grammar and spelling in the current composer text. Preserves your formatting, tone, and wording choices. Handles up to 5,000 characters. |
| **Translate** | Translates the composer text into a target language. The original text is preserved above a separator, and the translation is appended below. Supports 20+ languages with native-language names in the selector. |
| **Rewrite** | Rewrites the current composer text while keeping the same meaning. Useful for polishing a rough draft. |
| **MCP Execute** | Runs a custom instruction against the ticket using your configured MCP (Model Context Protocol) tool integrations — for example, looking up an order, triggering a refund, or fetching account data from an external system. |
When the ticket comes from a chat, messaging, WhatsApp, SMS, or social channel, the editor switches to chat mode with a set of shorter-form tools:
| Button | What it does |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Quick Reply** | Generates a concise, channel-appropriate response for the current chat message. Streams the reply directly into the composer as it is generated. |
| **Fix** | Fixes grammar and spelling in the current composer text without changing the meaning. |
| **Friendly** | Rewrites the current composer text to sound warmer and more conversational. |
| **Expand** | Expands a short note in the composer into a more complete reply. |
| **Translate** | Translates the composer text, same as in email mode. |
| **Rewrite** | Rewrites the current composer text, same as in email mode. |
All toolbar buttons are disabled while a request is in flight. A **Stop** button appears during generation so agents can cancel a response that is taking too long or going in the wrong direction.
### Ticket sidebar
The ticket sidebar panel shows real-time AI analysis of the current ticket. It updates automatically each time the AI processes a request — no manual refresh needed.
| Element | What it shows |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Sentiment badge** | The customer's detected sentiment: Urgent, Negative, Neutral, or Positive. Displayed as a color-coded pill. |
| **Category pill** | The ticket category detected by the AI (for example, `Billing Dispute`, `Password Reset`, `Shipping ETA`). Displayed next to the sentiment badge. |
| **Summary** | A one- or two-sentence summary of what the customer is asking for. Appears below the pills and is useful when skimming a long conversation thread. |
| **Confidence badge** | The AI's confidence in its generated response: High, Medium, or Low. Color-coded. Does not appear after Translate, Rewrite, or Grammar Check actions, since those do not produce a full AI-generated answer. |
The sidebar updates in real time by listening for the `ai_action_complete` event broadcast by the RAUM AI background process. You do not need to refresh the page or click anything — the sentiment, category, summary, and confidence badge all appear within a second or two of the AI finishing its response.
The sidebar also shows:
* **Suggested articles** from your Zendesk Help Center that are relevant to the current ticket.
* **Suggested macros** from your Zendesk macro library that match the ticket context. Click a macro row to apply it directly to the ticket.
* **Similar tickets** from your ticket history that resemble the current one. Click a row to navigate to that ticket.
* **Feedback buttons** to rate the AI response thumbs-up or thumbs-down. Feedback is logged against the specific AI response and used to surface quality trends in the RAUM AI analytics dashboard.
***
## Troubleshooting
1. Confirm the app is enabled for your Zendesk role. Go to Admin Center → People → Roles, select your role, and check that RAUM AI Assistant is enabled.
2. Refresh the page in your browser.
3. Open the browser developer console (F12) and look for any errors related to the RAUM AI app.
4. Confirm the app is installed in Admin Center → Apps and integrations → Apps → Zendesk Support apps.
1. Go to Admin Center → Apps → RAUM AI Assistant → Settings and verify the **Backend URL** is correct. It should be a hostname only with no `https://` prefix — for example, `api.raum.am`.
2. Verify your RAUM AI service is running by opening `https://{your-backend-url}/api/health` in a browser. You should see `{"status":"ok"}`.
3. Confirm the **API Key** and **Organization ID** match the values in your RAUM AI dashboard.
1. Check that the **API Key** in the app settings matches your current API key in the RAUM AI dashboard under Settings → API Keys.
2. Verify the **Organization ID** is correct.
3. If you recently rotated your API key, update it in the Zendesk app settings: Admin Center → Apps → RAUM AI Assistant → Settings.
The sidebar loads enrichment data (sentiment, category, summary) only after the AI has processed at least one request for the current ticket. Open a ticket, click **Generate**, and the sidebar will populate once the response is ready.
If you have previously processed the ticket and the sidebar is still empty, the enrichment custom fields may not be configured. Contact RAUM AI support to verify your enrichment field IDs are set up correctly for your Zendesk account.
Response time depends on your AI provider and model. For the fastest results:
* Use a faster model for your All-purpose model (for example, `gpt-4o-mini` or `claude-3-5-haiku`).
* Check your AI provider's API status page for outages.
* Verify your RAUM AI backend has sufficient resources if self-hosted.
The Generate action targets under 8 seconds at the 95th percentile. Grammar Check targets under 3 seconds. Translation targets under 4 seconds.
***
## What's next
Review the full setup guide if you haven't completed account creation and Zendesk connection yet.
Learn how to use the AI toolbar effectively as a writing assistant for your support team.
Enable fully autonomous ticket resolution so RAUM AI closes tickets in the background.
Connect external tools so the AI can look up live data during the Act step.