# Freshservice

Configure Freshservice ticketing integration with Risotto

## Overview

The Freshservice integration provides two-way ticket synchronization between Risotto and your Freshservice service desk. When a request comes through Risotto, a matching ticket appears in Freshservice — and comments, status changes, and assignee updates made in Freshservice sync back to Risotto and Slack.

> **Note:** Freshservice uses **two-way sync**. By default, Risotto polls Freshservice for
> changes every few minutes. Enable **Realtime Updates** during setup to receive
> changes instantly via webhook events.

## How It Works

The integration is configured in two places:

1. **Settings → Integrations → Freshservice**: connect your Freshservice instance to Risotto (once, organization-wide)
2. **Settings → \<department> → Ticket Sync**: add a Freshservice ticket sync per department and configure where that department's tickets go

When a ticket is created in Risotto for a configured department, Risotto:

1. Creates a matching ticket in the department's configured Freshservice workspace
2. Applies the department's default settings (agent group, ticket type)
3. Adds an **Open in Freshservice** link to the **Links** section of the Risotto ticket's detail view

## Prerequisites

> **Warning:** You need a Freshservice admin to set up this integration. The API key must
> belong to an account with the roles in [Choose the account for the API
> key](#choose-the-account-for-the-api-key).

## Choose the account for the API key

Risotto acts in Freshservice as the account that owns the API key. For example, Risotto posts comments and updates tickets as that account. Use an account that belongs to no person, so the integration keeps working when someone leaves. You have two options:

- **A dedicated agent**: a normal Freshservice agent that only Risotto uses.
- **An integration user**: a Freshservice account for API access only. It cannot sign in to the Freshservice portal and does not use an agent license. Integration users are a newer Freshservice feature. Create them in **Global Settings → User Management → Integration Users**.

### Roles the account needs

Give the account both kinds of role. An admin role alone does not let the account see tickets or Solutions articles.

| Role                                                                                                         | Where to set it                                                | Why Risotto needs it                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| An admin role, for example **Account Admin**                                                                 | **Account-wide permissions**                                   | Risotto lists your workspaces when you connect Freshservice. Without an admin role, the connection fails.                                   |
| An agent role, for example **IT Supervisor** or **IT Agent**, with the access level **Across the workspace** | **Workspace permissions**, in each workspace that Risotto uses | Risotto reads and updates tickets, adds comments, and reads Solutions articles. Without an agent role, Freshservice refuses these requests. |

Set the agent role in every workspace that you use for ticket sync, request sources, or a [Freshservice index](https://www.tryrisotto.com/docs/integrations/knowledge/freshservice).

> **Warning:** Use the access level **Across the workspace**. With a narrower access level,
> such as member groups or assigned items, Freshservice refuses requests for the
> other tickets. An integration user cannot join agent groups, so a
> member-groups access level gives it no tickets.

### Set up an integration user

1. **Create the integration user**

   In Freshservice, go to **Global Settings → User Management → Integration
   Users**. Click **Create integration user**, enter a **Display name** (for
   example, `Risotto`), and click **Create**.

2. **Add the admin role**

   On the **Permissions** tab, under **Account-wide permissions**, click **Add
   admin role**. Add **Account Admin** and click **Save**.

3. **Add the agent role in each workspace**

   Under **Workspace**, click **Add to workspace**. Choose the workspace, click
   **Add role**, and add **IT Supervisor**. Click **Save**. Do this for each
   workspace that Risotto uses.

4. **Copy the API key**

   On the integration user's page, find the **API key** card. Reveal the key
   and copy it. Use this key when you connect Freshservice in Risotto.

> **Note:** An integration user cannot join agent groups. To send Freshservice tickets to
> Risotto, add a [request source](#request-sources) for the agent group. Do not
> route tickets by assigning them to the integration user.

### 1. Freshservice API Key

If you use an integration user, copy its key as shown in [Set up an integration user](#set-up-an-integration-user) and go to the next section. For a dedicated agent, sign in to Freshservice as that agent.

1. **Open Profile settings**

   In Freshservice, click your profile picture (top-left) and choose **Profile settings**.

2. **Copy your API Key**

   Find **Your API Key** on the right side. Reveal it, copy it, and store it securely.

   > **Tip:** Don't see an API key? Enable it under **Admin → Agents →** \[your user] **→ Permissions → API Key**. If your account has more than one workspace, the path starts at **Global Settings → Agents**. For an integration user, copy the key from the integration user's page instead.

   > **Warning:** Treat your API key like a password. Store it securely and never share it publicly.

### 2. Freshservice Subdomain

The subdomain of your instance URL. For `https://mycompany.freshservice.com`, the subdomain is `mycompany`.

## Configuration

When connecting Freshservice in Risotto, you'll provide:

| Field         | Description                                 | Example     |
| ------------- | ------------------------------------------- | ----------- |
| **Subdomain** | The subdomain of your Freshservice instance | `mycompany` |
| **API Key**   | API key for the account that Risotto uses   | `aBc123...` |

The connection dialog also includes an **Enable Realtime Updates** checkbox. When checked, Risotto generates a webhook URL and secret for the **Risotto Sync** app, which delivers Freshservice events to Risotto instantly instead of waiting for the next polling cycle.

> **Note:** You don't enter a Workspace ID when connecting Freshservice. Workspaces are
> selected later — per department for outbound ticket creation, and per request
> source for inbound tickets.

## Setup Process

### Step 1: Connect Freshservice to Risotto

1. **Open Integrations settings**

   In your Risotto dashboard, go to **Settings → Integrations** and click the **Freshservice** card. On the **Freshservice API key** card, click **Connect**.

2. **Enter your connection details**

   In the **Connect Freshservice** dialog, enter the **Subdomain** and **API Key**. To get instant updates from Freshservice, check **Enable Realtime Updates**. Click **Save**.

   *Product example: The Connect Freshservice dialog, with the northwind subdomain, an API key, Enable Realtime Updates checked, and Save.*

3. **Install the Risotto Sync app (recommended)**

   If you enabled Realtime Updates, Risotto opens the **Freshservice App Setup** dialog. Click **Install in marketplace** to open the **Risotto Sync** listing in your Freshservice marketplace, and click **Install** there. When Freshservice asks for them, paste the **Webhook URL** and **Webhook secret** from the Risotto dialog. Complete the installation, then click **Done** in the Risotto dialog.

   > **Note:** Use the copy buttons in the Risotto dialog rather than retyping the webhook URL and secret — a typo is the most common cause of a failed app installation.

   > **Tip:** Realtime Updates are optional. Without the app, Risotto still syncs both directions by polling Freshservice every few minutes.

4. **Confirm the connection**

   The **Freshservice API key** card shows **Connected**, your **Site**, and **Realtime updates**. If you enabled Realtime Updates, the row reads **On · waiting for the first update** until the Risotto Sync app delivers its first event. It then shows the time of the most recent update.

   > **Done:** Freshservice is now connected to your organization. Next, configure which departments use it.

### Step 2: Configure a Department

> **Note:** Ticketing in Risotto is configured per department. Each department chooses its
> own ticketing system, and multiple departments can use Freshservice with
> independent configurations.

1. **Open your department**

   Go to **Settings**. Under **Departments**, click a department, then click **Ticket Sync**.

2. **Add Freshservice ticket sync**

   Click **Add ticket sync** and select **Freshservice**.

3. **Configure Freshservice settings**

   In the **Configure Freshservice for \<department>** dialog, set how Risotto creates tickets for this department:

   - **Workspace (Optional)**: where this department's tickets are created. If none is selected, tickets go to your Freshservice primary workspace.
   - **Agent Group (Optional)**: the Freshservice agent group assigned to new tickets
   - **Ticket Type (Optional)**: the type applied to tickets Risotto creates (e.g. Incident or Service Request). One type applies to every ticket in the department. If you leave it empty, Freshservice uses its default type. To give a group of requests a different type, put them in a [sub-department](https://www.tryrisotto.com/docs/dashboard/settings/sub-departments).
   - **Sync priority to Freshservice** (default: off): push each ticket's priority to its Freshservice ticket. Risotto sends the priority that a person set, or else the priority that the AI suggested. **Low**, **Medium**, **High**, and **Urgent** become the Freshservice priorities Low, Medium, High, and Urgent. Risotto sends the priority when it creates the ticket, each time it updates the ticket, and right after it files a service request. It does not change the priority of a ticket that started in Freshservice. The sync goes one way: a priority change in Freshservice does not come back to Risotto. With the switch off, Risotto creates tickets at Low and does not send a priority to service requests.

   *Product example: The Configure Freshservice for IT dialog, with the IT workspace, the Service Desk agent group, the Incident ticket type, and Save.*

   Click **Save**. Then make sure **External ticket sync enabled** is on.

### Choose which tickets sync

The **Only sync escalated tickets** setting on the **Ticket Sync** page of the department decides when Risotto creates the Freshservice ticket:

- **Off** (default): Risotto creates the Freshservice ticket when it creates the Risotto ticket. This includes requests that Risotto resolves without help from your team.
- **On**: Risotto creates the Freshservice ticket only when the ticket escalates to your team.

The Risotto ticket exists in both cases, so you see every conversation in the dashboard.

*Product example: IT's Ticket Sync page: the four sync switches with Only sync escalated tickets on, and the connected Freshservice card.*

The **Prompt for escalation** channel setting in [Request Sources](https://www.tryrisotto.com/docs/dashboard/settings/request-sources#channel-settings) does not change which tickets sync. It only makes Risotto ask the requestor **Yes, escalate** or **No, cancel** before it escalates.

When a request matches an enabled [Service Catalog](https://www.tryrisotto.com/docs/dashboard/settings/service-catalog) item, Risotto files a service request in Freshservice. The service request is a separate Freshservice ticket. The **Ticket Type** setting does not file catalog requests. It sets the type of the ticket that Risotto creates for the conversation. With **Sync priority to Freshservice** on, Risotto also sets the priority of the service request after it files it.

The **Ticket Sync** page of the department shows the switch as **Sync priority**, with **On** or **Off**.

### Step 3: Test the Integration

1. **Create a test ticket**

   Create a ticket through Risotto in the configured department.

2. **Verify in Freshservice**

   Open Freshservice and confirm the ticket appears in the expected workspace with the right defaults. Then reply to the ticket in Freshservice and confirm the comment syncs back to the Risotto ticket.

   > **Done:** If the ticket appears with the correct agent group and ticket type, and replies sync back to Risotto, your integration is working.

> **Tip:** Start with a single department to test the integration before rolling it out
> to additional departments.

## Request Sources

You can also use Freshservice as a request source — tickets created in Freshservice flow into Risotto for AI-powered handling.

1. Navigate to **Settings → Request Sources** and click **Manage in Freshservice**
2. On the **Requests** tab, in the **Freshservice agent groups** section, click **Add Agent Group**
3. In the **Add Freshservice Agent Group** dialog, choose a **Workspace**, an **Agent Group** (or **All agent groups**), and the **Department** for its tickets, then click **Add Agent Group**
4. When a ticket is created in Freshservice, Risotto checks the ticket's initial agent group against your request sources, matching tickets sync into Risotto and receive an AI response

Tickets that don't match any request source are never synced, so you can route specific agent groups to Risotto while leaving the rest of your service desk untouched.

## Troubleshooting

### Connection fails

- Confirm the **Subdomain** is only the subdomain (for example, `mycompany`), not the full URL
- Make sure that the account that owns the API key has an admin role. See [Roles the account needs](#roles-the-account-needs).
- For a dedicated agent, check that the **API Key** permission is on under **Admin → Agents →** \[your user] **→ Permissions**.

### Tickets not appearing in Freshservice

- Verify **External ticket sync enabled** is on for the department and a Freshservice ticket sync is configured
- Confirm the workspace selected in the department's ticket sync settings is the one you expect
- Check that the API key hasn't been rotated or revoked in Freshservice

### Tickets appear in Freshservice, but replies and status changes do not sync

The account that owns the API key has no agent role in the ticket's workspace, or its access level is too narrow. Freshservice refuses the requests from Risotto to read and update the ticket. Add an agent role with the access level **Across the workspace**. See [Roles the account needs](#roles-the-account-needs).

### Tickets created in the wrong workspace

- Review the workspace in the department's ticket sync settings — when none is selected, tickets are created in your Freshservice primary workspace
- Remember each department's configuration is independent — check the specific department

## Best Practices

1. **Use an account that belongs to no person**: Use a dedicated agent or an integration user, not a person's own account. See [Choose the account for the API key](#choose-the-account-for-the-api-key).
2. **Test per department**: Verify each department's configuration with a test ticket before announcing it
3. **Document your workspace mapping**: Keep a record of which department targets which Freshservice workspace

## Related Integrations

- [Ticketing Integrations Overview](https://www.tryrisotto.com/docs/integrations/ticketing/overview)
- [Freshservice Tickets (Knowledge)](https://www.tryrisotto.com/docs/integrations/knowledge/freshservice-tickets) — index solved Freshservice tickets for AI search
- [Jira Integration](https://www.tryrisotto.com/docs/integrations/ticketing/jira) — two-way sync with Jira and Jira Service Management

Source: https://www.tryrisotto.com/docs/integrations/ticketing/freshservice
