Dear Developers,
Apps built for Freshchat Classic use modules, placeholders, and product events specific to that environment. With Freshdesk Omni, the underlying product architecture has changed, and the same app code cannot run interchangeably across both environments.
If you migrate to Freshdesk Omni, Classic apps may fail to validate, install without rendering, or break at runtime when reading agent, conversation, or group context.
This post outlines what is changing, how to migrate, and a practical checklist based on patterns we used while merging Freshchat and Freshdesk builds into a single Omni-ready app.
What is changing?
| Freshchat Classic | Freshdesk Omni (Platform 3.0) |
|---|---|
"product": { "freshchat": { ... } } |
"modules": { "chat_conversation": { ... } } |
| Platform 2.0 / 2.3 | Platform 3.0 |
| Classic-only placeholders | Omni-compatible module placeholders |
loggedInAgent in chat contexts |
loggedInAgent (chat) + loggedInUser (tickets) |
Reference: Platform 3.0 chat_conversation migration guide
What you may see
fdk validatefails:"product" is not supported in platform-version 3.0- App installs but icon never appears: manifest still targets Classic placeholders
- Runtime errors in ticket view: app always calls
loggedInAgentinstead ofloggedInUser - Group mapping always fails: wrong group ID field for Omni vs standalone Freshchat
Migration checklist
1. Enable Platform 3.0 validation
fdk config set --scope local global_apps.enabled true
Update engines to FDK 10.x and Node 24.x.
2. Replace product.freshchat with modules
Before (Classic):
{
"platform-version": "2.3",
"product": {
"freshchat": {
"location": {
"conversation_message_editor": {
"url": "index.html",
"icon": "styles/images/icon1.svg"
}
}
}
}
}
After (Omni):
{
"platform-version": "3.0",
"modules": {
"common": {
"requests": {
"listFreshchatGroups": {},
"listFreshdeskGroups": {},
"whichAccount": {}
}
},
"chat_conversation": {
"location": {
"conversation_message_editor": {
"url": "index.html",
"icon": "styles/images/icon.svg"
}
}
},
"support_ticket": {
"location": {
"ticket_top_navigation": {
"url": "index.html",
"icon": "styles/images/icon.svg"
}
}
}
},
"engines": {
"node": "24.11.0",
"fdk": "10.1.2"
}
}
Include support_ticket only if your app also needs ticket surfaces.
3. Move request templates to modules.common.requests
Template names in manifest.json must match config/requests.json exactly.
4. Detect runtime context (ticket vs conversation)
async function getRuntimeContext(installParams) {
try {
const conversationInfo = await client.data.get("conversation");
const groupId = installParams.isStandalone
? conversationInfo.conversation.assigned_group_id || ""
: conversationInfo.conversation.properties.group || "";
return {
mode: "conversation",
referenceId: conversationInfo.conversation.id,
groupId,
actor: await getConversationActor(),
};
} catch {
const ticketInfo = await client.data.get("ticket");
return {
mode: "ticket",
referenceId: ticketInfo.ticket.id,
groupId: ticketInfo.ticket.group_id || "",
actor: await getTicketActor(),
};
}
}
Use loggedInAgent in conversation context and loggedInUser in ticket context.
5. Fix group mapping for standalone vs Omni
Detect account type at install time (whichAccount → bundle_type). Standalone Freshchat uses group.id; Omni/bundled accounts may need group.chat_group_id or properties.group. Paginate group APIs; do not rely on the first page.
6. Update stylesheet for Platform 3.0
Replace product-specific CSS with freshworks.css in all frontend HTML files.
7. Validate and test
fdk validate
fdk run
fdk pack
Test in both ticket and conversation surfaces if your app registers both modules.
Key highlights
- Classic apps are not automatically compatible with Freshdesk Omni
- Migration requires Platform 3.0 modules, not
product.freshchat - Omni apps often need dual-module manifests (
chat_conversation+support_ticket) - Data methods and group ID fields differ between standalone Freshchat and Omni
- Marketplace publishers should submit an updated Platform 3.0 build for Omni customers
FAQ
Do I need to rebuild from scratch?
Usually no. Update the manifest, placeholders, request declarations, runtime context handling, and stylesheets. Core business logic often stays the same.
Will my Classic installation keep working?
On Freshchat Classic, existing builds may continue to work. After migrating to Freshdesk Omni, treat Classic-targeted apps as incompatible until updated.
Which module do I use for chat UI in Omni?
Use chat_conversation, for example conversation_message_editor. Do not use product.freshchat in Platform 3.0.
Do I always need support_ticket?
Only if the app must also appear in ticket surfaces. Conversation-only apps can ship with chat_conversation alone.
Why does group mapping work in Classic but fail in Omni?
Omni exposes different group identifiers. Detect account type during installation and map IDs accordingly.
Do I need FDK 10.x and Node 24.x?
Strongly recommended for new Platform 3.0 work. See the FDK 10.0.0 announcement.
I published a marketplace app for Freshchat Classic; what now?
Submit an updated Platform 3.0 build with the correct Omni modules and call out Omni compatibility in release notes.
Where can I get help?
Reply here with your manifest.json (redact secrets), the placeholder you expect, any console or validation errors, and fdk validate output.
Next steps
- Audit manifests for
product.freshchator Platform 2.x structure - Migrate to
platform-version: "3.0"with correct modules - Add runtime context detection if serving both tickets and conversations
- Run
fdk validateand test in Omni before go-live - Redeploy or republish the updated build
Docs: chat_conversation migration guide · Platform 3.0 what’s new · Announcements
We’re eager to hear your feedback, especially migration pain points, unclear docs, or placeholders that need better guidance.
Regards,
Team Freshworks Developers