Freshdesk

Let hires find and read Freshdesk tickets, reply to customers or leave private notes, set status, assign and tag, and be woken when tickets change.

Explore 8 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With Freshdesk connected, a hire can:

find tickets by status, who's assigned, the customer's email, a tag, priority, or what changed since a time,
read a ticket with its whole conversation, private notes marked,
reply to the customer, or leave a private note only your team sees,
set a ticket's status, assign it to an agent or a group, and add tags.

Freshdesk's search looks at a ticket's fields, not the words in it, so a hire finds tickets by those filters and then reads them.

1. Choose who hires reply as

Replies show to your customers under the name of the Freshdesk agent whose API key Roster has. Use an agent named after your team, like Bayt Studio Support, never a made-up person's name.

Sign in to Freshdesk as that agent, click the profile picture at the top right, open Profile settings and copy the API key shown beside the password section.

2. Connect it in Roster

Open Integrations → Tools → Add a tool, search for Freshdesk and choose it.
API key: paste the key you copied.
Freshdesk subdomain: the part before .freshdesk.com in your Freshdesk address, like bayt. Roster always uses the freshdesk.com address, even if your help center has its own domain.
Business name: your business's name, like Bayt Studio.
Click Connect.

3. Give hires access

On the hire's Tools tab, click Give access on Freshdesk:

Read only: it can find and read tickets and see groups, and nothing else.
Read and write: it can also reply, leave notes, set status, assign and tag.
Groups: group names or IDs whose tickets it may see and work on. Leave it empty for every group. A ticket in any other group is refused, even if the hire knows its number, and it can't hand a ticket to a group outside the list.

A hire sees what the agent whose key you used can see in Freshdesk, so an agent limited to some groups there limits the hire too.

First replies wait for approval

The first reply a hire writes to a requester it has never written to waits for a person's approval, even though they opened the ticket. If an agent on your team already replied publicly on the ticket, it doesn't ask. The hire asks in the thread with the ticket and the reply, and when the approver says yes, Roster posts exactly that reply, once. After that, replies to that requester go out without asking. Private notes never ask, and neither do replies to people at your team's own domains.

Customers your team already talks to can be added under Settings → Workspace → People you're already in touch with (more). Approving a first reply adds the requester's address there too.

Watching tickets

A hire's responsibility can watch Freshdesk: it's woken when a ticket in its groups is created or changes, with the list. Checking costs nothing when nothing changed.

Saying it's an AI assistant

A hire never pretends to be a person, and always says it's AI when asked. If you also want it to say so up front, turn on Say it's an AI assistant in first messages to outsiders under Settings → Workspace (more). Then the team's first public reply on a ticket starts with "This is the AI assistant for" and your business name. Private notes are never changed.

If something goes wrong

"Freshdesk returned 401": the API key changed (it changes when the agent resets it). Copy the new one onto the connection.
"Freshdesk returned 429": your Freshdesk plan allows a set number of calls a minute for the whole account. Roster waits and tries again; other apps using the same account share that limit.
A change shows up late in a search: Freshdesk takes a few minutes to index changes for its search. Asking for a customer's tickets by email, or the latest changes, doesn't lag.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Freshdesk and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

API key or access token

In Freshdesk: your profile picture → Profile settings → View API key. Replies show under that agent's name.

No fixed permission list is declared for this connection. Review the sign-in consent screen, the account's roles, and the service's own documentation before connecting.

Connection fields

Freshdesk connection fields
Field	What to provide
API key `apiKey` Required · sealed secret	In Freshdesk: your profile picture → Profile settings → View API key. Replies show under that agent's name.
Freshdesk subdomain `subdomain` Required	The part before .freshdesk.com in your Freshdesk address.
Business name `businessName` Required	Used when hires say they're your business's AI assistant. Never a made-up person's name.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

Freshdesk per-hire limits
Field	What to provide
Groups `groups` Optional	Group names or IDs whose tickets it may see and work on. Leave empty for every group.

Actions

8 actions: 3 only read and 5 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

Find an actionAccess

8 of 8 actions. Open an action for its arguments and full input schema.

search_ticketsRead only

Find tickets, most recently updated first: by status, who's assigned, the customer's email, a tag, priority, or changed since a time. Freshdesk searches fields, not words in the text.

Approval: Uses your workspace and hire approval settings.

Arguments for search_tickets
Argument	Type	Details
`status`Optional	"open" \| "pending" \| "resolved" \| "closed" \| "unsolved"	unsolved: open or pending
`assignee`Optional	string	an agent's email or name, "me", or "none" for unassigned
`requester`Optional	string	the customer's email
`tag`Optional	string	See input schema below.
`priority`Optional	"low" \| "medium" \| "high" \| "urgent"	See input schema below.
`changedSince`Optional	string	See input schema below.
`limit`Optional	integer	See input schema below.Default: `20`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "status": {
      "description": "unsolved: open or pending",
      "type": "string",
      "enum": [
        "open",
        "pending",
        "resolved",
        "closed",
        "unsolved"
      ]
    },
    "assignee": {
      "description": "an agent's email or name, \"me\", or \"none\" for unassigned",
      "type": "string"
    },
    "requester": {
      "description": "the customer's email",
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "tag": {
      "type": "string",
      "pattern": "^[\\w -]{1,80}$"
    },
    "priority": {
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high",
        "urgent"
      ]
    },
    "changedSince": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  }
}

read_ticketRead only

Read a ticket: its details and the whole conversation oldest first, replies and private notes marked.

Approval: Uses your workspace and hire approval settings.

Arguments for read_ticket
Argument	Type	Details
`id`Required	integer	the ticket's number, like 1234

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the ticket's number, like 1234"
    }
  },
  "required": [
    "id"
  ]
}

replyRead and write

Reply to the customer on a ticket (they get it by email or in their chat), optionally setting its status. It goes out in the business's name: write as the business, never sign with a person's name or say you're one.

Approval: when it writes to someone outside your team for the first time.

Arguments for reply
Argument	Type	Details
`id`Required	integer	the ticket's number, like 1234
`text`Required	string	See input schema below.
`status`Optional	"open" \| "pending" \| "resolved"	pending when waiting on the customer

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the ticket's number, like 1234"
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20000
    },
    "status": {
      "description": "pending when waiting on the customer",
      "type": "string",
      "enum": [
        "open",
        "pending",
        "resolved"
      ]
    }
  },
  "required": [
    "id",
    "text"
  ]
}

add_noteRead and write

Leave a private note on a ticket, for the team only; the customer never sees it.

Approval: Uses your workspace and hire approval settings.

Arguments for add_note
Argument	Type	Details
`id`Required	integer	the ticket's number, like 1234
`text`Required	string	See input schema below.

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the ticket's number, like 1234"
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20000
    }
  },
  "required": [
    "id",
    "text"
  ]
}

set_statusRead and write

Set a ticket's status: open, pending (waiting on the customer), resolved or closed.

Approval: Uses your workspace and hire approval settings.

Arguments for set_status
Argument	Type	Details
`id`Required	integer	the ticket's number, like 1234
`status`Required	"open" \| "pending" \| "resolved" \| "closed"	See input schema below.

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the ticket's number, like 1234"
    },
    "status": {
      "type": "string",
      "enum": [
        "open",
        "pending",
        "resolved",
        "closed"
      ]
    }
  },
  "required": [
    "id",
    "status"
  ]
}

assignRead and write

Assign a ticket to an agent (by email or name, or "none") and/or a group (by name). Only groups this hire may use.

Approval: Uses your workspace and hire approval settings.

Arguments for assign
Argument	Type	Details
`id`Required	integer	the ticket's number, like 1234
`agent`Optional	string	an agent's email or name, or "none" to unassign
`group`Optional	string	a group's name

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the ticket's number, like 1234"
    },
    "agent": {
      "description": "an agent's email or name, or \"none\" to unassign",
      "type": "string"
    },
    "group": {
      "description": "a group's name",
      "type": "string"
    }
  },
  "required": [
    "id"
  ]
}

tagRead and write

Add tags to a ticket. Tags already there stay.

Approval: Uses your workspace and hire approval settings.

Arguments for tag
Argument	Type	Details
`id`Required	integer	the ticket's number, like 1234
`tags`Required	string[]	See input schema below.

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the ticket's number, like 1234"
    },
    "tags": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[\\w -]{1,80}$"
      }
    }
  },
  "required": [
    "id",
    "tags"
  ]
}

list_groupsRead only

The Freshdesk groups this hire may use.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}

Watches and incoming events

This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
No incoming webhook handler is declared for this integration.

Limits and troubleshooting

Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
Expired or revoked access: reconnect or replace the key on the connection.
Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

1. Choose who hires reply asCopy Anchor Link

2. Connect it in RosterCopy Anchor Link

3. Give hires accessCopy Anchor Link

First replies wait for approvalCopy Anchor Link

Saying it's an AI assistantCopy Anchor Link

If something goes wrongCopy Anchor Link

Tools and permissions reference

Authentication and requested permissions

API key or access token

Connection fields

Per-hire limits

Actions

Watches and incoming events

Limits and troubleshooting

On this page

1. Choose who hires reply as

2. Connect it in Roster

3. Give hires access

First replies wait for approval

Saying it's an AI assistant

If something goes wrong