Freshdesk
Let Octocom answer your Freshdesk email tickets as a dedicated bot agent.
Octocom works inside Freshdesk as a dedicated agent: a Freshdesk agent created for the bot, with its own API key. Once connected, you choose which mailboxes it answers. Octocom picks up tickets, replies through Freshdesk, and hands tickets to your team when it can't help. Every decision is recorded on the ticket with a private note or a tag, so your team always sees what happened.
Connecting alone doesn't touch any tickets. Octocom starts answering when you select mailboxes and save.
1. Create the bot agent
In Freshdesk, open Admin -> Team -> Agents -> New agent and set:
- Name: the name your customers should see from the bot, for example "Emma" or "Acme Support". Freshdesk can show it in reply names and signatures.
- Email: an inbox your team can open. Freshdesk sends the invite there. Customers don't see this address.
- Agent type: Support agent, Full-time.
- Role: Administrator. See Why Administrator?
- Ticket scope: Global access, so the bot can see tickets in every group.
- API key access: On. It's off by default, and without it the agent can't create an API key.
2. Copy the bot agent's API key
- Open the invite email from step 1, accept it and set a password.
- Signed in as the bot agent, click the profile picture (top right) -> Profile settings -> View API key, and copy the key.
Use the bot agent's key, not a person's. A person's key stops working when they leave or reset it, and everything Octocom does would show under their name.
3. Save it in Octocom
Open Settings -> Integrations -> Freshdesk, enter your subdomain (the acme in acme.freshdesk.com) and the API key, and click Save.
Octocom checks the key straight away. It must belong to an active, Full-time agent with the Administrator role and Global ticket access. If a setting is missing, the error tells you which one to change.
The key is encrypted and never shown again. To replace it, open API key in the same window and paste a new key for the same agent: Octocom keeps running. A key for a different agent or Freshdesk account stops handling until you save the mailboxes again.
4. Choose what Octocom answers
Mailboxes
Select the Freshdesk mailboxes (support email addresses) Octocom answers. Each becomes an inbox in Octocom's email settings. A mailbox can be answered by one brand only, so the list marks mailboxes another brand already answers. Each mailbox shows the address customers write to, such as contact@yourbrand.com, and the Freshdesk forwarding address it forwards to; search matches either.
Saving with mailboxes selected goes live: within a minute Octocom starts answering. Untick a mailbox, or all of them, to stop.
Which tickets
- Assigned to the bot agent: Octocom answers only tickets assigned to its agent, for example by your Freshdesk automation rules. This gives you full control over which tickets the AI sees. Octocom takes over a ticket assigned to it even if your team replied earlier, and adds a private note saying so. It answers the customer's messages since your team's last reply.
- All unassigned: Octocom answers new unassigned tickets nobody on your team has replied to, and assigns them to its agent. A ticket that is already assigned to someone else, or that a team member already replied to, is tagged and left alone. Private notes don't count as a reply, so a ticket with only private notes (for example from a Freshdesk app) is still picked up. Assigning any ticket to the bot agent still hands it to Octocom.
Only tickets from after you go live are picked up. With All unassigned, you can also pick up recent tickets that are still waiting: choose how many days back (up to 30) and a maximum number. Octocom takes them two a minute, oldest first, after new tickets. They get real replies, so start with a small number.
Merge a customer's repeat emails
Customers often send a second or third separate email a few minutes after the first. Each new email is a new Freshdesk ticket, so without merging Octocom answers each one on its own, and the answers can contradict each other. Turn on Merge a customer's repeat emails (off by default) to answer them once:
- When Octocom is about to pick up a new ticket, it looks for an earlier ticket from the same customer (same email address, ignoring case) in the same mailbox that Octocom picked up in the last 3 days and that is still open or pending in Freshdesk. If there are several, the most recent one is used.
- The new ticket is closed with a private note pointing to the earlier ticket and the
octocom-merged-duplicatetag. It isn't assigned to the bot agent. - The earlier ticket gets a private note with the customer's new message. If Octocom is still answering it, the message joins that conversation and Octocom sends one reply, on the earlier ticket, that covers both messages. If your team has the earlier ticket (after a handoff or a takeover), the bot doesn't reply: the note is for your team, and a pending ticket is reopened so the new message isn't missed.
- Attachments of the new email reach the bot with the message and stay on the closed ticket for your team.
- Tickets assigned to someone else or already answered by your team are left alone as usual, and are never merged.
If the customer writes on the closed duplicate again (for example by replying to it), Freshdesk reopens it and Octocom carries each new message over the same way: it joins the earlier ticket's conversation, the earlier ticket gets a private note with the message, and the duplicate is closed again. A resolved or closed earlier ticket that Octocom handled is reopened, as when the customer replies on it directly. Each message is carried over once.
If Octocom no longer answers the earlier ticket (handed off, taken over by your team, or deleted), the bot doesn't reply. Octocom adds a note with the message to the earlier ticket, if it still exists, and leaves the duplicate open for your team with your handoff group and agent and the octocom-handoff tag, so the customer isn't left unanswered. From then on the duplicate is your team's, as it is once anyone on your team replies on it or assigns it to a person.
If Freshdesk requires fields to close tickets, Octocom closes the duplicate with your resolve fields. If Freshdesk still refuses, the duplicate keeps its note and tag but stays open, so your team can close it. If Octocom can't copy the first message to the earlier ticket, it leaves the duplicate open with your handoff routing instead. Use explain_freshdesk_ticket to see which ticket a duplicate was merged into.
Tickets from automated senders and relays are never merged: one such address often writes about many different customers, as Shopify's customer complaint notices do. That covers addresses such as no-reply@, noreply@, donotreply@, do-not-reply@, mailer-daemon@, postmaster@ or notifications@, Shopify's contact-form relay mailer@shopify.com, and senders you marked with a Use Reply-To as the customer email rule.
Close a customer's older unanswered tickets
When a customer's earlier email sits unanswered in your team's queue and they write again, Octocom picks up the new ticket and answers it, while your team may later answer the older one too. Turn on Close a customer's older unanswered tickets (off by default) to close those older tickets when Octocom picks up the new one. It works the other way round from merging repeat emails, and the two can be on together.
- When Octocom picks up a ticket, it looks up the customer's other tickets (the same Freshdesk contact) once. It closes those created in the last 14 days, in the same mailbox, that are still open or pending, unassigned and have no reply or forward from your team. Private notes don't count as a reply. At most 3 are closed per pickup, the most recent first.
- Their messages go to the bot together with the new ticket's, oldest first, so Octocom answers everything once, in the new ticket. Attachments and pasted images of the older tickets stay on them for your team; the bot sees how many there are.
- Each older ticket is closed with your resolve fields and the
octocom-closed-duplicatetag, and gets a private note pointing to the new ticket. The new ticket gets a private note per closed ticket with the customer's words, and Octocom's conversation lists what was closed. - Never closed: tickets assigned to anyone (including the bot agent), tickets your team replied to or forwarded, tickets Octocom picked up, merged, skipped or handed off, tickets in another mailbox, outbound emails from your team, and tickets from automated senders.
- If Freshdesk refuses to close an older ticket (a required field), it keeps the tag and a note asking your team to close it instead of answering it.
- If the customer replies on a closed older ticket, Freshdesk reopens it for your team as usual; its note says which ticket Octocom answers.
The lookup costs one extra Freshdesk API call per pickup, plus a few for each ticket closed, and stays within your API reserve. If too few calls are left, Octocom picks the ticket up without the lookup, or closes the older tickets on a later poll. Ask Copilot, or set closeOlderDuplicateTickets with the configure_freshdesk MCP tool or the REST API. Use explain_freshdesk_ticket to see which ticket an older ticket was closed for.
API calls left for your other apps
Freshdesk limits how many API calls an account makes per minute (or per hour on some older plans), and the limit is shared with your other Freshdesk apps. Octocom leaves 20% of the calls for them by default: once fewer are left, it pauses picking up and syncing changed tickets until the limit resets, then catches up. Its own replies to tickets it already handles still go out.
If pickup pauses at the end of busy periods and your other apps need fewer calls, lower the reserve. If your other apps run out of calls, raise it. Ask Copilot, or set apiReservePercent (5 to 50) with the configure_freshdesk MCP tool or the REST API. Omitting it keeps the saved value; null resets it to 20. Octocom always leaves at least 10 calls.
Ticket status
- After each bot reply: Resolved (default), Pending, or Open. A customer's reply reopens a resolved ticket and Octocom answers again.
- When Octocom closes: Resolved or Closed, when the conversation closes in Octocom.
Handoff
When the AI can't help, Octocom adds a private note with the reason, adds the octocom-handoff tag, reopens the ticket and releases it: unassigned, or to the agent you choose, optionally in another group. Octocom never takes a ticket back from a person.
Ticket fields
Octocom can set ticket fields at four moments: when it picks a ticket up, with every reply, when it resolves the ticket, and when it hands it off. Built-in fields (Type, Group, Product, Priority) and custom fields both work.
Each field gets either:
- A fixed value, for example Handled by = AI on pickup.
- A conversation metadata key, with an optional fallback value. Your workflows, actions or Python code write the metadata during the conversation (for example
ticket_type= Refund), and Octocom copies it to the ticket. If the key is missing or its value doesn't fit the field, the fallback is used, or the field is left out.
For dropdowns, use the choice exactly as Freshdesk lists it. Group, product and priority also accept their IDs. Values are checked against your Freshdesk fields when you save.
Fields required to close a ticket
Freshdesk can require fields before a ticket can be resolved or closed. If Octocom doesn't set them, closing fails, and you'd often only notice the next day. To prevent that:
- Put every required field under When Octocom resolves a ticket. The settings warn when a required field isn't covered.
- Run the live test (below) before going live and after changing fields.
- If closing still fails in production, Octocom shows the error and the field Freshdesk named in the Freshdesk settings and Check setup, adds a private note on the ticket, and hands the ticket to your team instead of leaving it assigned to the bot.
Live test
Live test in the Freshdesk settings runs everything Octocom does on a real ticket: it creates a labelled test ticket in a mailbox, picks it up with your pickup fields, adds a private note, replies, resolves it with your resolve fields, and hands it off with your handoff routing. It reads each step back from Freshdesk, because your automation rules can change a ticket after Octocom writes to it. Then it deletes the test ticket. The reply goes to an example.com address that receives nothing.
The result shows each step, with Freshdesk's own error message when one fails.
What your team sees in Freshdesk
| Tag | Meaning |
|---|---|
octocom-picked-up | Octocom took the ticket. |
octocom-replied | Octocom replied at least once. |
octocom-resolved | Octocom resolved or closed the ticket. |
octocom-handoff | Octocom handed the ticket to your team. A private note gives the reason. |
octocom-human-takeover | A team member replied, forwarded or reassigned the ticket, so Octocom stopped. A private note says why. |
octocom-skipped-assigned | Not picked up: it was already assigned to someone else (All unassigned mode). |
octocom-skipped-human-reply | Not picked up: a team member had already replied to or forwarded it, or it is an outbound email from your team (All unassigned mode). |
octocom-merged-duplicate | Closed as a duplicate: the same customer's message was merged into their open ticket, which a private note names. |
octocom-closed-duplicate | Closed as a duplicate: an older unanswered ticket of a customer whose newer ticket Octocom answers, which a private note names. |
Private notes are added only when they explain something: a takeover of a ticket your team replied to earlier, a handoff, a human takeover, a ticket Octocom couldn't close, or a merged or closed duplicate (on both tickets). Use the tags in Freshdesk filters and reports to see how many tickets Octocom handles, hands off and skips.
Octocom stops on its own when a team member replies to the customer, forwards the ticket, reassigns or unassigns it, deletes it or marks it as spam. Private notes don't stop Octocom, so your team and Freshdesk apps can add them freely; to take a ticket over, reassign it. Freshdesk automations don't count as a team member.
Troubleshooting
- Check setup in the Freshdesk settings verifies the key and the bot agent, the selected mailboxes, closing fields, field rules, the handoff group and recent sync health, and explains how to fix each problem.
- To find out why a ticket wasn't picked up or answered, ask Copilot, or use the
explain_freshdesk_ticketMCP tool or the REST API (GET /rest/v1/businesses/{businessId}/integrations/freshdesk/tickets/{ticketId}) with the Freshdesk ticket number. - Freshdesk's API allows a limited number of calls, shared with your other apps. Octocom leaves a reserve of the calls free (20% unless you change it), and pauses until the limit resets if it's reached.
Why Administrator?
Octocom lists your support mailboxes so you can choose which ones it answers. It also reads your automation rules and ticket fields to explain why a ticket was or wasn't picked up. Freshdesk's Agent role can't read these. Octocom only works on tickets (replies, notes, tags and assignment) and never changes your Freshdesk settings.
Disconnect
Disconnecting removes the saved key, stops handling and archives the Octocom inboxes. Tickets in Freshdesk aren't changed, so reassign any that were still with the bot agent. Reconnecting starts fresh and never resumes tickets from before.
Ticket details in conversation metadata
Every conversation Octocom answers from a Freshdesk ticket carries the ticket's details as conversation metadata. Octocom refreshes them from Freshdesk with every customer message, before the bot answers, so workflows, condition providers and Python actions see the ticket as it is now.
| Key | Value |
|---|---|
freshdesk:ticketId | The ticket number, for example 4821. |
freshdesk:ticketUrl | Link to the ticket in Freshdesk. |
freshdesk:subdomain | Your Freshdesk subdomain. |
freshdesk:mailboxId | The mailbox the ticket came in through. |
freshdesk:recipient | The mailbox's address, such as contact@yourbrand.com. |
freshdesk:tags | The ticket's tags, comma-separated, without Octocom's own octocom-* tags. |
freshdesk:type | The ticket type, such as Refund. |
freshdesk:priority | 1 low, 2 medium, 3 high, 4 urgent. |
freshdesk:productId | The ticket's product. |
freshdesk:groupId | The ticket's group. |
freshdesk:requesterId | The customer's Freshdesk contact ID. |
freshdesk:companyId | The customer's company. |
freshdesk:cf_* | Each custom field with a value, under its API name, such as freshdesk:cf_order_number. |
Keys other than custom fields are always written, empty when the ticket has no value. Up to 50 custom fields with a value are copied, each up to about 2,000 bytes; a custom field emptied in Freshdesk keeps its last value here.
Use it in Python
Your Python actions can read the subdomain, key and bot agent ID (agentId, for connections made from the Freshdesk settings) with get_integration_credentials and call https://{subdomain}.freshdesk.com/api/v2 with Basic auth, using the key as the username and X as the password. Read the ticket number from freshdesk:ticketId:
import requests
def execute_action(context):
slug = context["conversation"]["businessSlug"]
creds = get_integration_credentials(context)[slug]["freshdesk"]
ticket_id = get_conversation_metadata(context, "freshdesk:ticketId")
if not ticket_id:
return {"error": "This conversation didn't come from Freshdesk."}
response = requests.get(
f"https://{creds['subdomain']}.freshdesk.com/api/v2/tickets/{ticket_id}",
auth=(creds["apiKey"], "X"),
timeout=20,
)
response.raise_for_status()
return {"status": response.json()["status"]}Replies, notes and tags the action writes appear in Freshdesk as the bot agent and don't stop Octocom. Reassigning the ticket to someone else does, as it would for your team.