Integration

Freshdesk, and the contact who has no email address

A Freshdesk integration escalates a Telegram conversation into a ticket and relays agent replies back to the customer. Freshdesk requires a contact identifier and a Telegram user has no email, so a unique external identifier per user is the detail that makes the integration coherent.

Freshdesk integration: auth, limits and availability

Auth model: Basic auth
Rate limit: Per minute per account, varying by plan
GCC availability: No regional restriction; data-centre region fixed at account creation
Data flow: 5 hops, worker-mediated

As of 2025-10-01, Telegram Bot API 13.4

Why this integration exists

Freshdesk turns up in GCC businesses that wanted a helpdesk without the weight of an enterprise one, and the API reflects that: straightforward objects, predictable behaviour and fewer accumulated concepts to learn. For a Telegram integration that is genuinely helpful, because the interesting work is in the relay rather than in the platform.

Contact identity is where the design decision sits. Freshdesk wants an email or a phone number to identify a contact, and a Telegram user reliably has neither. The workable approach is a unique external identifier derived from the Telegram user id, which gives a stable contact without inventing an email address that will bounce and without asking a customer for one before they have been helped.

The other decision is status mapping. Freshdesk statuses mean something to the support team and nothing to the customer, so relaying them verbatim produces messages like "your ticket is now Pending" which reads as a stall. The mapping between internal status and what the customer is told is a copy decision worth making explicitly, because the default of passing it through is worse than saying nothing.

How the data actually moves

The external identifier gives a stable Freshdesk contact for a Telegram user who has no email, without inventing an address that would bounce.

Freshdesk uses HTTP basic authentication with an API key as the username, held as a Worker secret. The key belongs to an agent account, so a dedicated integration agent is used rather than a person's — ticket history then attributes automated activity correctly and survives staff changes.

Auth model: HTTP basic

Their limits, and what they mean for you

Rate limits are applied per minute per account and vary by plan.

A per-minute window is coarser than a per-second one, so a burst is absorbed and a sustained relay is not. Queuing is sized against sustained rate rather than peak.

Contacts are identified by email, phone or a unique external id.

The external id is the correct choice for Telegram users. Fabricating an email address gives a contact that looks complete and produces bounces on every automated notification.

Ticket statuses are configurable and their meaning is defined by your team.

Relaying a raw status to a customer says nothing useful. The mapping from internal status to customer-facing wording is a deliberate copy decision.

Attachment size is capped per ticket and per note.

A photograph relayed from Telegram is comfortably inside it. A batch of images from a customer documenting a problem may not be, and the bot says so rather than failing silently.

How it fails, and what happens when it does

A fabricated email is used and automated notifications bounce.

The external identifier avoids the whole problem. This is the most common Freshdesk integration shortcut and its consequences arrive as deliverability warnings nobody connects to the bot.

Agent replies loop back into the ticket via the bot.

Bot-originated notes are marked and ignored on return. The same echo problem as any two-way relay and the same one-line fix.

A private note is relayed to the customer.

Only public replies cross the boundary. Agents write private notes assuming privacy and the check is explicit rather than inferred.

Ticket status changes to something the customer misreads.

Customer-facing wording is mapped rather than passed through. "Pending" means waiting on the customer to a support team and means being ignored to a customer.

Availability in the UAE and the wider GCC

Global

No regional restriction. Data centre region is selected at account creation and is worth confirming where residency matters.

Small and mid-sized support teams

The intended case, and where the simpler object model pays off against a heavier helpdesk.

Existing Freshdesk customers

The only case in which this is the right choice. Adopting a helpdesk in order to integrate with it is the wrong order.

Free and lower plans

API access and rate limits vary. Confirm before scoping, since limits shape the relay design.

When not to use this integration

Your team is not already on Freshdesk. The integration is worth having; the helpdesk is not worth adopting for it.
You want automatic ticket resolution. Closure is a judgement and automating it produces resolution metrics nobody trusts.
You have no agents to receive escalations. A ticket nobody reads is worse than telling the customer you are closed.
Your support volume is a few conversations a day. A Telegram forum topic covers it at no cost.

What it runs on

Component	Version	Why
Cloudflare Workers	current	Ticket creation, reply relay and webhook handling.
Cloudflare D1	current	Contact map, ticket links and status mapping state.
Zod	4.4	Validation of webhook payloads and API responses.
grammY	1.45	The customer conversation and escalation handoff.

Questions that come up during scoping

How do we create a contact for someone with no email?

With a unique external identifier derived from the Telegram user id. Fabricating an email produces a contact that looks complete and then bounces on every automated notification, and the deliverability warnings are rarely connected back to the bot.

Should we relay ticket status to the customer?

Only through a mapping. "Pending" means waiting on the customer to a support team and means being ignored to a customer, so passing the raw status through is worse than saying nothing.

How does this compare to Zendesk?

A simpler object model and fewer accumulated concepts, which makes the integration quicker. Zendesk has deeper automation and reporting. If you already run one of them, that answers the question; if you run neither, this is not a reason to adopt either.

What stops private notes reaching the customer?

Only public replies are relayed, checked explicitly rather than inferred from formatting. Agents write private notes assuming they stay private, and that assumption has to be enforced rather than hoped for.

Can customers send photographs into a ticket?

Yes, within Freshdesk's attachment caps. A single phone photograph is comfortably inside them; a batch documenting a problem may not be, and the bot says so rather than dropping some silently.

Which account should the integration authenticate as?

A dedicated integration agent. Using a person's API key attributes automated activity to them and stops working when they leave, usually at the least convenient moment.