> ## 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.

# Connect RAUM AI to your Zendesk account

> Authorize RAUM AI to read and update your Zendesk tickets using OAuth or an API token, then configure webhooks so Zendesk sends events to raum automatically.

Connecting Zendesk gives RAUM AI the ability to read incoming tickets, post replies, update ticket fields, change statuses, and apply tags. You can connect during the onboarding wizard or at any time from **Settings → Integrations**. Two authentication methods are available: OAuth (recommended) and API token.

## Choose an authentication method

<Tabs>
  <Tab title="OAuth (recommended)">
    OAuth lets Zendesk handle authorization without requiring you to generate or store tokens manually. RAUM AI receives a scoped access token that you can revoke from the Zendesk admin panel at any time.

    <Steps>
      <Step title="Enter your subdomain">
        In the **Zendesk Subdomain** field, type the subdomain portion of your Zendesk URL. For example, if your Zendesk URL is `acme.zendesk.com`, enter `acme`.
      </Step>

      <Step title="Click Connect with Zendesk">
        Click **Connect with Zendesk**. RAUM AI redirects you to the Zendesk authorization page.
      </Step>

      <Step title="Authorize the connection">
        Log in to Zendesk if prompted, then click **Allow** to grant RAUM AI access to your account.
      </Step>

      <Step title="Return to RAUM AI">
        Zendesk redirects you back to RAUM AI. A green confirmation banner confirms that the connection succeeded.
      </Step>
    </Steps>

    <Tip>
      OAuth is the fastest method and requires no manual token management. If you need to revoke access later, go to **Zendesk Admin → Apps and integrations → OAuth clients**.
    </Tip>
  </Tab>

  <Tab title="API token">
    API token authentication is useful if OAuth is restricted in your Zendesk account or if you prefer explicit credential management.

    <Steps>
      <Step title="Generate a Zendesk API token">
        In Zendesk, go to **Admin → Apps and integrations → Zendesk API**. Enable token access if it is not already enabled, then click **Add API token**. Copy the token — Zendesk only shows it once.
      </Step>

      <Step title="Enter your subdomain">
        In RAUM AI, type the subdomain portion of your Zendesk URL into the **Zendesk Subdomain** field (e.g., `acme` for `acme.zendesk.com`).
      </Step>

      <Step title="Enter your admin email">
        Enter the email address of the Zendesk admin account that owns the API token. This is required for token-based authentication.
      </Step>

      <Step title="Paste the API token">
        Paste the token you copied in step 1 into the **API Token** field. The token is masked and encrypted with AES-256-GCM before storage.
      </Step>

      <Step title="Save">
        Click **Save** or **Complete Registration**. RAUM AI validates the credentials before saving.
      </Step>
    </Steps>

    <Warning>
      API tokens grant access to your entire Zendesk account under the admin's identity. Treat them with the same care as a password. Rotate tokens immediately if you suspect one has been compromised.
    </Warning>
  </Tab>
</Tabs>

## Set up webhooks and triggers

Webhooks let Zendesk push ticket events to RAUM AI in real time so Agent Mode can process tickets automatically. You can create the webhook and triggers during the onboarding wizard (step 5) or from **Settings → Webhook** at any time.

### Auto-create triggers

RAUM AI can provision the webhook endpoint and Zendesk triggers for you automatically:

<Steps>
  <Step title="Open the webhook setup">
    In **Settings → Webhook**, click **Auto-create triggers** (or proceed through step 5 of the onboarding wizard).
  </Step>

  <Step title="Select the trigger types">
    Choose one or more of the following events:

    | Trigger            | When it fires                                        |
    | ------------------ | ---------------------------------------------------- |
    | **Ticket created** | RAUM AI processes new tickets as soon as they arrive |
    | **Ticket solved**  | Captures resolution outcomes for CSAT tracking       |
    | **Ticket rated**   | Syncs CSAT ratings back to RAUM AI analytics         |
  </Step>

  <Step title="Run auto-setup">
    Click **Create selected triggers**. RAUM AI calls the Zendesk API to register the webhook endpoint and create each selected trigger. Results are shown inline — each trigger displays a `created`, `reused`, or `error` status.
  </Step>
</Steps>

### Manual webhook setup

If you prefer to configure the webhook manually in Zendesk:

1. In Zendesk, go to **Admin → Apps and integrations → Webhooks → Create webhook**.
2. Set the endpoint URL to the one shown in RAUM AI under **Settings → Webhook → Webhook URL**.
3. Set the request format to **JSON** and the HTTP method to **POST**.
4. Create a trigger in **Admin → Objects and rules → Triggers** that targets the new webhook for the events you want to capture.

## Troubleshooting

<AccordionGroup>
  <Accordion title="OAuth redirect returns an error">
    Common causes include an incorrect subdomain, Zendesk OAuth being disabled for your account, or a network firewall blocking the redirect. Verify your subdomain contains no spaces or special characters, then try again. If the problem persists, switch to API token authentication.
  </Accordion>

  <Accordion title="API token authentication fails with 401">
    Check that you entered the admin email exactly as it appears in Zendesk (case-sensitive). Confirm that token access is enabled in **Zendesk Admin → Zendesk API**. If you regenerated the token in Zendesk, update it in RAUM AI under **Settings → Integrations**.
  </Accordion>

  <Accordion title="Triggers were created but tickets are not being processed">
    Confirm that the trigger condition in Zendesk matches tickets you expect RAUM AI to receive. Check **Settings → Webhook** in RAUM AI to see recent webhook deliveries and any error responses. Also verify that Agent Mode is enabled in **Settings → AI Mode**.
  </Accordion>

  <Accordion title="Webhook trigger auto-setup shows an 'error' status">
    This usually means the Zendesk API returned a permissions error. Confirm that the connected account has admin-level access. If you are using an API token, check that the token belongs to an admin user, not an agent.
  </Accordion>
</AccordionGroup>