> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns. > > **Recommended**: > ```bash > npx @scalekit-inc/cli setup > ``` > > Global: > ```bash > npm install -g @scalekit-inc/cli > scalekit setup > ``` > > Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for 40+ agents. > Features: full-stack-auth, agent-auth, mcp-auth, modular-sso, modular-scim. > [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # Freshdesk connector Connect to Freshdesk. Manage tickets, contacts, companies, and customer support workflows **Authentication:** Basic Auth **Categories:** Customer Support, Communication 1. ### Install the SDK ### Node.js ```bash frame="terminal" npm install @scalekit-sdk/node ``` ### Python ```bash frame="terminal" pip install scalekit ``` Full SDK reference: [Node.js](/agentkit/sdks/node/) | [Python](/agentkit/sdks/python/) 2. ### Set your credentials Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**. ```sh showLineNumbers=false title=".env" SCALEKIT_ENVIRONMENT_URL= SCALEKIT_CLIENT_ID= SCALEKIT_CLIENT_SECRET= ``` ## What you can do Connect this agent connector to let your agent: - **Create time entry, ticket note, solution article** — Log a time entry against a ticket for billing or effort tracking - **List time entries, solution articles, satisfaction ratings** — Retrieve time entries logged across tickets, with filtering by agent, company, and execution date range - **Filter tickets** — Search tickets using Freshdesk's structured query syntax (field:value expressions combined with AND/OR), for filtering beyond what List Tickets' predefined filters support - **Forward ticket** — Forward a ticket's conversation to one or more external email addresses, optionally including the full ticket thread - **Delete ticket, contact, company** — Move a ticket to the trash in Freshdesk - **Update contact, company, agent** — Update an existing contact in Freshdesk ## Common workflows export const sectionTitle = 'Common workflows' ## Proxy API call **Don't worry about your Freshdesk domain in the path.** Scalekit automatically resolves `{{domain}}` from the connected account's configuration and constructs the full URL for you. For example, if your Freshdesk domain is `mycompany.freshdesk.com`, a request with `path="/v2/agents/me"` will be sent to `https://mycompany.freshdesk.com/api/v2/agents/me` automatically. ### Node.js ```typescript const result = await actions.request({ connectionName: 'freshdesk', identifier: 'user_123', path: '/v2/agents/me', method: 'GET', }); console.log(result); ``` ### Python ```python result = actions.request( connection_name='freshdesk', identifier='user_123', path="/v2/agents/me", method="GET", ) print(result) ``` ## Execute a tool ### Node.js ```typescript const result = await actions.executeTool({ connector: 'freshdesk', identifier: 'user_123', toolName: 'freshdesk_agent_create', toolInput: {}, }); console.log(result); ``` ### Python ```python result = actions.execute_tool( connection_name='freshdesk', identifier='user_123', tool_name='freshdesk_agent_create', tool_input={}, ) print(result) ``` ## Tool list Use the exact tool names from the **Tool list** below when you call `execute_tool`. If you're not sure which name to use, list the tools available for the current user first. ## Tool list ### `freshdesk_agent_create` Create a new agent in Freshdesk. Email is required and must be unique. Agent will receive invitation email to set up account. At least one role must be assigned. Parameters: - `email` (`string`, required): Email address of the agent (must be unique) - `role_ids` (`array`, required): Array of role IDs to assign to the agent (at least one required) - `ticket_scope` (`number`, required): Ticket permission level (1=Global Access, 2=Group Access, 3=Restricted Access) - `agent_type` (`number`, optional): Type of agent (1=Support Agent, 2=Field Agent, 3=Collaborator) - `focus_mode` (`boolean`, optional): Focus mode setting for the agent - `group_ids` (`array`, optional): Array of group IDs to assign the agent to - `language` (`string`, optional): Language preference of the agent - `name` (`string`, optional): Full name of the agent - `occasional` (`boolean`, optional): Whether the agent is occasional (true) or full-time (false) - `signature` (`string`, optional): Agent email signature in HTML format - `skill_ids` (`array`, optional): Array of skill IDs to assign to the agent - `time_zone` (`string`, optional): Time zone of the agent ### `freshdesk_agent_delete` Delete an agent from Freshdesk. This action is irreversible and will remove the agent from the system. The agent will no longer have access to the helpdesk and all associated data will be permanently deleted. Parameters: - `agent_id` (`number`, required): ID of the agent to delete ### `freshdesk_agent_get` Retrieve details of a specific agent by ID, including their roles, groups, skills, ticket scope, and contact information. Parameters: - `agent_id` (`number`, required): ID of the agent to retrieve ### `freshdesk_agent_update` Update an existing agent in Freshdesk. Only the fields provided are changed. Use this to change an agent's role, ticket scope, group/skill assignments, or contact details. Parameters: - `agent_id` (`number`, required): ID of the agent to update - `agent_type` (`number`, optional): Type of agent (1=Support Agent, 2=Field Agent, 3=Collaborator) - `email` (`string`, optional): Email address of the agent - `focus_mode` (`boolean`, optional): Focus mode setting for the agent - `group_ids` (`array`, optional): Array of group IDs to assign the agent to - `language` (`string`, optional): Language preference of the agent - `mobile` (`string`, optional): Mobile phone number of the agent - `name` (`string`, optional): Full name of the agent - `occasional` (`boolean`, optional): Whether the agent is occasional (true) or full-time (false) - `phone` (`string`, optional): Telephone number of the agent - `role_ids` (`array`, optional): Array of role IDs to assign to the agent - `signature` (`string`, optional): Agent email signature in HTML format - `skill_ids` (`array`, optional): Array of skill IDs to assign to the agent - `ticket_scope` (`number`, optional): Ticket permission level (1=Global Access, 2=Group Access, 3=Restricted Access) - `time_zone` (`string`, optional): Time zone of the agent ### `freshdesk_agents_list` Retrieve a list of agents from Freshdesk with filtering options. Returns agent details including IDs, contact information, roles, and availability status. Supports pagination with up to 100 agents per page. Parameters: - `email` (`string`, optional): Filter agents by email address - `mobile` (`string`, optional): Filter agents by mobile number - `page` (`number`, optional): Page number for pagination (starts from 1) - `per_page` (`number`, optional): Number of agents per page (max 100) - `phone` (`string`, optional): Filter agents by phone number - `state` (`string`, optional): Filter agents by state (fulltime or occasional) ### `freshdesk_canned_response_create` Create a new canned response template that agents can insert into ticket replies. Must belong to an existing canned response folder. Parameters: - `content_html` (`string`, required): HTML content of the canned response - `folder_id` (`number`, required): ID of the canned response folder this response belongs to - `title` (`string`, required): Title of the canned response - `group_ids` (`array`, optional): Array of group IDs that can use this response, when visibility is 2 - `visibility` (`number`, optional): Who can see this canned response. 0=personal, 1=all agents, 2=specific groups ### `freshdesk_canned_response_folders_list` Retrieve all canned response folders, each including the canned responses stored inside it. Use a folder ID with Create Canned Response. ### `freshdesk_companies_list` Retrieve a paginated list of all companies in the Freshdesk account. Parameters: - `page` (`number`, optional): Page number for pagination (starts from 1) - `per_page` (`number`, optional): Number of companies per page (max 100) ### `freshdesk_company_create` Create a new company in Freshdesk. Name is required. Use domains to auto-associate contacts and tickets whose email domain matches. Parameters: - `name` (`string`, required): Name of the company - `custom_fields` (`object`, optional): Key-value pairs containing custom field names and values - `description` (`string`, optional): Description of the company - `domains` (`array`, optional): Array of email domains associated with the company - `health_score` (`string`, optional): Health score label for the company - `industry` (`string`, optional): Industry the company operates in - `note` (`string`, optional): Internal note about the company ### `freshdesk_company_delete` Delete a company from Freshdesk. This action is irreversible; contacts and tickets associated with the company are not deleted but lose their company association. Parameters: - `company_id` (`number`, required): ID of the company to delete ### `freshdesk_company_get` Retrieve details of a specific company by ID, including custom fields, domains, and health score. Parameters: - `company_id` (`number`, required): ID of the company to retrieve ### `freshdesk_company_update` Update an existing company in Freshdesk. Only the fields provided are changed. Parameters: - `company_id` (`number`, required): ID of the company to update - `custom_fields` (`object`, optional): Key-value pairs containing custom field names and values - `description` (`string`, optional): Description of the company - `domains` (`array`, optional): Array of email domains associated with the company - `health_score` (`string`, optional): Health score label for the company - `industry` (`string`, optional): Industry the company operates in - `name` (`string`, optional): Name of the company - `note` (`string`, optional): Internal note about the company ### `freshdesk_contact_create` Create a new contact in Freshdesk. Email and name are required. Supports custom fields, company assignment, and contact segmentation. Parameters: - `email` (`string`, required): Email address of the contact - `name` (`string`, required): Full name of the contact - `address` (`string`, optional): Address of the contact - `company_id` (`number`, optional): Company ID to associate with the contact - `custom_fields` (`object`, optional): Key-value pairs for custom field values - `description` (`string`, optional): Description about the contact - `job_title` (`string`, optional): Job title of the contact - `language` (`string`, optional): Language preference of the contact - `mobile` (`string`, optional): Mobile number of the contact - `phone` (`string`, optional): Phone number of the contact - `tags` (`array`, optional): Array of tags to associate with the contact - `time_zone` (`string`, optional): Time zone of the contact ### `freshdesk_contact_delete` Soft-delete a contact in Freshdesk, moving it to the trash. The contact can be restored from the trash within Freshdesk before it is permanently purged. Parameters: - `contact_id` (`number`, required): ID of the contact to delete ### `freshdesk_contact_get` Retrieve details of a specific contact by ID, including custom fields and associated company. Parameters: - `contact_id` (`number`, required): ID of the contact to retrieve ### `freshdesk_contact_update` Update an existing contact in Freshdesk. Only the fields provided are changed. Parameters: - `contact_id` (`number`, required): ID of the contact to update - `company_id` (`number`, optional): Company ID to associate with the contact - `custom_fields` (`object`, optional): Key-value pairs for custom field values - `description` (`string`, optional): Description about the contact - `email` (`string`, optional): Email address of the contact - `job_title` (`string`, optional): Job title of the contact - `mobile` (`string`, optional): Mobile number of the contact - `name` (`string`, optional): Full name of the contact - `phone` (`string`, optional): Phone number of the contact - `tags` (`array`, optional): Array of tags to associate with the contact ### `freshdesk_contacts_list` Retrieve a list of contacts with filtering and pagination. Supports filtering by email, phone, mobile, company, and state. Parameters: - `company_id` (`number`, optional): Filter by company ID - `email` (`string`, optional): Filter by contact email - `mobile` (`string`, optional): Filter by mobile number - `page` (`number`, optional): Page number for pagination (starts from 1) - `per_page` (`number`, optional): Number of contacts per page (max 100) - `phone` (`string`, optional): Filter by phone number - `state` (`string`, optional): Filter by contact state - `updated_since` (`string`, optional): Filter contacts updated since this timestamp (ISO 8601) ### `freshdesk_group_create` Create a new agent group in Freshdesk for routing and organizing tickets. Name is required. Parameters: - `name` (`string`, required): Name of the group - `agent_ids` (`array`, optional): Array of agent IDs to add to the group - `description` (`string`, optional): Description of the group - `escalate_to` (`number`, optional): Agent ID to escalate unassigned tickets to after the unassigned_for period - `unassigned_for` (`string`, optional): Time after which an unassigned ticket in this group is escalated ### `freshdesk_groups_list` Retrieve a list of all agent groups in Freshdesk, including group membership and escalation settings. ### `freshdesk_roles_list` Retrieve a list of all roles from Freshdesk. Returns role details including IDs, names, descriptions, default status, and timestamps. This endpoint provides information about the different permission levels and access controls available in the Freshdesk system. ### `freshdesk_satisfaction_ratings_list` Retrieve customer satisfaction survey ratings submitted across tickets, optionally filtered to ratings created since a given time. Parameters: - `created_since` (`string`, optional): Only return ratings created since this timestamp (ISO 8601) - `page` (`number`, optional): Page number for pagination (starts from 1) ### `freshdesk_solution_article_create` Create a new knowledge base article inside a solution folder. Status controls whether it is a draft or published. Parameters: - `description` (`string`, required): HTML content of the article body - `folder_id` (`number`, required): ID of the solution folder to create the article in - `title` (`string`, required): Title of the article - `status` (`number`, optional): Publication status of the article. 1=Draft, 2=Published - `tags` (`array`, optional): Array of tags to associate with the article ### `freshdesk_solution_articles_list` Retrieve all knowledge base articles inside a specific solution folder. Parameters: - `folder_id` (`number`, required): ID of the solution folder to list articles from - `page` (`number`, optional): Page number for pagination (starts from 1) - `per_page` (`number`, optional): Number of articles per page (max 100) ### `freshdesk_ticket_create` Create a new ticket in Freshdesk. Requires either requester_id, email, facebook_id, phone, twitter_id, or unique_external_id to identify the requester. Parameters: - `cc_emails` (`array`, optional): Array of email addresses to be added in CC - `custom_fields` (`object`, optional): Key-value pairs containing custom field names and values - `description` (`string`, optional): HTML content of the ticket describing the issue - `email` (`string`, optional): Email address of the requester. If no contact exists, will be added as new contact. - `group_id` (`number`, optional): ID of the group to which the ticket has been assigned - `name` (`string`, optional): Name of the requester - `priority` (`number`, optional): Priority of the ticket. 1=Low, 2=Medium, 3=High, 4=Urgent - `requester_id` (`number`, optional): User ID of the requester. For existing contacts, can be passed instead of email. - `responder_id` (`number`, optional): ID of the agent to whom the ticket has been assigned - `source` (`number`, optional): Channel through which ticket was created. 1=Email, 2=Portal, 3=Phone, 7=Chat, 9=Feedback Widget, 10=Outbound Email - `status` (`number`, optional): Status of the ticket. 2=Open, 3=Pending, 4=Resolved, 5=Closed - `subject` (`string`, optional): Subject of the ticket - `tags` (`array`, optional): Array of tags to be associated with the ticket - `type` (`string`, optional): Helps categorize the ticket according to different kinds of issues ### `freshdesk_ticket_delete` Move a ticket to the trash in Freshdesk. Trashed tickets can be restored within 30 days via the Freshdesk UI before being permanently purged. Parameters: - `ticket_id` (`number`, required): ID of the ticket to delete ### `freshdesk_ticket_forward` Forward a ticket's conversation to one or more external email addresses, optionally including the full ticket thread. Parameters: - `body` (`string`, required): HTML content of the forward message - `ticket_id` (`number`, required): ID of the ticket to forward - `to_emails` (`array`, required): Array of email addresses to forward the ticket to - `bcc_emails` (`array`, optional): Array of email addresses to BCC on the forward - `cc_emails` (`array`, optional): Array of email addresses to CC on the forward - `quoted_conversation` (`boolean`, optional): If true, includes the full ticket thread in the forwarded email ### `freshdesk_ticket_get` Retrieve details of a specific ticket by ID. Includes ticket properties, conversations, and metadata. Parameters: - `ticket_id` (`number`, required): ID of the ticket to retrieve - `include` (`string`, optional): Additional resources to include (stats, requester, company, conversations) ### `freshdesk_ticket_note_create` Add a note to a ticket conversation in Freshdesk. Notes are internal by default (visible only to agents); set private to false to create a public note visible to the customer. Parameters: - `body` (`string`, required): HTML content of the note - `ticket_id` (`number`, required): ID of the ticket to add the note to - `incoming` (`boolean`, optional): If true, marks the note as a third-party contribution added from outside Freshdesk - `notify_emails` (`array`, optional): Array of email addresses to notify about this note - `private` (`boolean`, optional): If true, the note is only visible to agents. Defaults to true. - `user_id` (`number`, optional): ID of the agent creating the note ### `freshdesk_ticket_update` Update an existing ticket in Freshdesk. Note: Subject and description of outbound tickets cannot be updated. Parameters: - `ticket_id` (`number`, required): ID of the ticket to update - `custom_fields` (`object`, optional): Key-value pairs containing custom field names and values - `description` (`string`, optional): HTML content of the ticket (cannot be updated for outbound tickets) - `group_id` (`number`, optional): ID of the group to which the ticket has been assigned - `name` (`string`, optional): Name of the requester - `priority` (`number`, optional): Priority of the ticket. 1=Low, 2=Medium, 3=High, 4=Urgent - `responder_id` (`number`, optional): ID of the agent to whom the ticket has been assigned - `status` (`number`, optional): Status of the ticket. 2=Open, 3=Pending, 4=Resolved, 5=Closed - `subject` (`string`, optional): Subject of the ticket (cannot be updated for outbound tickets) - `tags` (`array`, optional): Array of tags to be associated with the ticket ### `freshdesk_tickets_filter` Search tickets using Freshdesk's structured query syntax (field:value expressions combined with AND/OR), for filtering beyond what List Tickets' predefined filters support. Supports fields like agent_id, group_id, priority, status, tag, type, due_by, fr_due_by, created_at, updated_at, closed_at, and custom fields. Returns up to 30 results per page across a maximum of 10 pages. Parameters: - `query` (`string`, required): Query expression to filter tickets, e.g. "priority:3 AND status:2". Must be enclosed in double quotes and be 512 characters or fewer. - `page` (`number`, optional): Page number for pagination (1-10) ### `freshdesk_tickets_list` Retrieve a list of tickets with filtering and pagination. Supports filtering by status, priority, requester, and more. Returns 30 tickets per page by default. Parameters: - `company_id` (`number`, optional): Filter by company ID - `email` (`string`, optional): Filter by requester email - `filter` (`string`, optional): Filter name (new_and_my_open, watching, spam, deleted) - `include` (`string`, optional): Additional resources to include (description, requester, company, stats) - `page` (`number`, optional): Page number for pagination (starts from 1) - `per_page` (`number`, optional): Number of tickets per page (max 100) - `requester_id` (`number`, optional): Filter by requester ID - `updated_since` (`string`, optional): Filter tickets updated since this timestamp (ISO 8601) ### `freshdesk_tickets_reply` Add a public reply to a ticket conversation. The reply will be visible to the customer and will update the ticket status if specified. Parameters: - `body` (`string`, required): HTML content of the reply - `ticket_id` (`number`, required): ID of the ticket to reply to - `bcc_emails` (`array`, optional): Array of email addresses to BCC on the reply - `cc_emails` (`array`, optional): Array of email addresses to CC on the reply - `from_email` (`string`, optional): Email address to send the reply from - `user_id` (`number`, optional): ID of the agent sending the reply ### `freshdesk_time_entries_list` Retrieve time entries logged across tickets, with filtering by agent, company, and execution date range. Parameters: - `agent_id` (`number`, optional): Filter by the agent who logged the time - `billable` (`boolean`, optional): Filter by billable status - `company_id` (`number`, optional): Filter by company - `executed_after` (`string`, optional): Filter entries executed after this timestamp (ISO 8601) - `executed_before` (`string`, optional): Filter entries executed before this timestamp (ISO 8601) - `page` (`number`, optional): Page number for pagination (starts from 1) ### `freshdesk_time_entry_create` Log a time entry against a ticket for billing or effort tracking. Parameters: - `ticket_id` (`number`, required): ID of the ticket to log time against - `time_spent` (`string`, required): Time spent, formatted as hh:mm - `agent_id` (`number`, optional): ID of the agent who performed the work - `billable` (`boolean`, optional): Whether this time entry is billable - `executed_at` (`string`, optional): When the work was performed (ISO 8601). Defaults to now. - `note` (`string`, optional): Note describing the work done --- ## More Scalekit documentation | Resource | What it contains | When to use it | |----------|-----------------|----------------| | [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content | | [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas | | [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |