Freshdesk
Connect your Freshdesk helpdesk so agents can answer ticket questions on the call, open tickets for callers, and file every answered call as a ticket.
How it works
Three things become possible once Freshdesk is connected.An agent you grant read can find the caller in your contacts, pull one of their tickets, and list the tickets they have open — so "what is happening with my ticket" gets answered on the call instead of becoming another ticket.An agent you grant write can also open a ticket, change its status, priority or group, and leave a note for whoever picks it up.And every answered call is filed as a ticket after hangup, with the call summary in the description, for the agents you granted write. You get one active Freshdesk connection per workspace, and connecting again replaces it.
Connect Freshdesk
Freshdesk authenticates with an API key, not OAuth — its OAuth flow exists only for apps published on the Freshworks Marketplace. Find your key in Freshdesk under your profile picture, Profile settings, in the *Your API Key* panel.Send it together with the account URL it belongs to. The key alone does not say which helpdesk it opens, so base_url is required and has to be your own https://your-subdomain.freshdesk.com address — nothing else is accepted. The call needs an Aethex API key carrying the integrations:write scope.The Freshdesk key inherits the permissions of the agent it belongs to. Someone who cannot see a group's tickets in Freshdesk will not see them here either, which is the simplest way to keep this connection narrower than your whole helpdesk.
curl -X POST https://api.aethexai.com/api/v1/integrations \
-H "X-API-Key: $AETHEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "freshdesk",
"auth_type": "api_key",
"base_url": "https://acme.freshdesk.com",
"access_token": "'"$FRESHDESK_API_KEY"'"
}'
# Aethex checks the key against your helpdesk before storing it, so a wrong
# key or the wrong account URL comes back as a 422 rather than failing later.Grant agents access
A connection reaches no agent until you say so, and read is the default. A read grant registers the four look-up tools; a write grant adds opening tickets, updating them and leaving notes. The list is declarative — send every agent that should have access, because an agent you leave out is an agent whose access you revoked.Grants are not carried across a reconnect. Nothing can tell re-keying the same helpdesk from swapping in a different one, so grant again afterwards.
curl -X PUT https://api.aethexai.com/api/v1/integrations/$CONNECTION_ID/agents \
-H "X-API-Key: $AETHEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agents": [
{ "agent_id": "<agent-uuid>", "access": "read" }
]
}'What an agent can do
Nine tools reach the agent mid-call, and a tenth is reserved for filing the call afterwards. Narrow the set for a connection by naming the tools you want in config.enabled_tools when you connect; an empty list turns all of them off.
| Tool | What it does | Grant |
|---|---|---|
freshdesk_lookup_contact | Finds the caller in your contacts by phone number or email. | read |
freshdesk_get_ticket | Reads one ticket by number, with its status, priority and requester. | read |
freshdesk_search_tickets | Lists a requester's tickets, optionally only those in one status. | read |
freshdesk_list_groups | Lists the groups a new ticket can be routed to. | read |
freshdesk_create_ticket | Opens a ticket for the caller and reads the number back to them. | write |
freshdesk_update_ticket | Changes a ticket's status, priority, group or tags. | write |
freshdesk_add_note | Adds a note to a ticket, private to your team unless you say otherwise. | write |
freshdesk_create_contact | Registers the caller as a contact by email address. If that address already exists you get that record back rather than a duplicate, with any detail it was missing added; details it already holds are left alone. A caller with no email is registered by opening their ticket instead. | write |
freshdesk_update_contact | Corrects a contact's name, email or phone number. Only the fields given change. | write |
Filing answered calls
Every answered call on an agent you granted write is filed as a Freshdesk ticket after the caller hangs up. The subject names the direction and the caller's number; the description carries the start time, the duration, the outcome and the call summary once the transcript has been analysed. The ticket is tagged aethex and voice-call, so you can keep these out of a view or build one just for them.The source is always Phone, so your own source reporting still means something. The requester is the caller's number, and Freshdesk matches it to an existing contact or creates one — Aethex never creates contacts itself.To turn this off for a connection, name the tools you do want in config.enabled_tools and leave freshdesk_log_call out.
Import contacts as call lists
A Freshdesk connection can also seed call lists from the people on file in your helpdesk. List what you can import with GET /integrations/{id}/imports/entities, see the safe fields with GET /integrations/{id}/imports/fields?entity=contacts, preview a validated sample with POST /integrations/{id}/imports/preview, and read paged rows with POST /integrations/{id}/imports/page. Both phone and mobile are offered as dial sources, in that order of precedence, and your own custom contact fields are offered alongside the standard ones. Sensitive fields such as bank details, tokens and national ids are never offered, and the flow is read-only until you run the import.
Errors
What the connect and grant calls answer, and what to do about it.
Your Aethex API key is missing or wrong, or it does not carry integrations:write.
Send a valid Aethex API key with the integrations scope.
An agent id in the grant list is not yours, or has been deleted. A 404 rather than a 422 on purpose: a 422 would confirm the id exists on somebody else's workspace.
Check the agent ids against your own agent list.
Two connect calls for Freshdesk raced, and the other one created the connection.
Read your integrations list — the connection is already there, so there is nothing to retry.
Freshdesk rejected the key, or base_url is missing, carries a path, or is not a .freshdesk.com address.
Check the key under Profile settings in Freshdesk, and send the account URL with no path after the host.
More than ten connect attempts for this workspace inside a minute.
Wait for the Retry-After interval. Connecting costs a round-trip to Freshdesk plus a write, so it is capped.
Freshdesk was unreachable or returned a server error, or a server-side dependency is not configured.
Retry in a moment. If it persists, Freshdesk is down or the deployment is missing its encryption key.
Limits worth knowing
Where this connection stops, so none of it is a surprise later.
| Limit | Detail |
|---|---|
| API key only | There is no consent flow. Asking for a Freshdesk authorize URL is refused, because Freshdesk's OAuth is available only to Marketplace apps. |
| A phone number does not identify a caller | Freshdesk treats an email address as unique, so registering a caller who already has one returns their record instead of duplicating it — and fills in only what that record was missing, since the address was heard over the phone and could belong to somebody else. Correcting a detail it already holds is a separate, deliberate step. Freshdesk does not constrain phone numbers, deliberately: switchboards and household lines sit on several contacts at once. Registering a caller by number alone is therefore refused — Aethex points the agent at opening a ticket instead, where Freshdesk matches the number to an existing contact, or creates one, on its own side. So a caller with no email still ends up with exactly one record. |
| One helpdesk per connection | base_url has to be your own .freshdesk.com address. A custom helpdesk domain is not accepted, and neither is a URL with a path. |
| One connection per workspace | Connecting Freshdesk again retires the previous connection, and its agent grants with it. |
| Source is always Phone | An agent cannot label a ticket as email or chat, so calls stay identifiable in your reporting. |
| Phone-only callers get named by their number | Freshdesk requires a name whenever a ticket's only requester identifier is a phone number. When an agent has not been told the caller's name, Aethex uses the number as the name rather than failing to file the ticket. |
| Contact matching is exact | Freshdesk strips spaces, brackets, dashes and dots from a phone number when it stores one, and matches the stored form exactly. Aethex sends numbers in that same form so a look-up finds what a ticket created. Its contact search by number also trails a new contact by up to ten seconds (measured), so a caller added mid-call may not be findable for a moment afterwards — which is why nothing decides whether a caller is new from that search. Searching by email address is not affected. |
| Only recent tickets are listed | Freshdesk's ticket list returns tickets created in roughly the last month; older ones are left out. An agent asking what a caller has open therefore sees their recent tickets, and an empty answer means nothing recent rather than nothing at all. |
| Rate limits are account-wide | Freshdesk allows 3,000 to 5,000 API calls an hour depending on your plan, shared with your other integrations, and enforces it per minute — a 50-call window that refills within a minute. A rate-limited tool call tells the agent to stop rather than retrying into the same wall. |