Initial Freshchat configuration

Before your Ada team can enable the Freshchat integration, complete the following prerequisites in your Freshchat account. This guide assumes an active Freshchat (or Freshworks Customer Service Suite) account with at least one channel and one group that agents are assigned to. Once finished, share the collected information with your Ada representative.

Prerequisites

Confirm the account’s plan includes the following capabilities, which Freshworks may gate by plan tier:

• API access to the Conversations API, used to create users and conversations, relay messages, and resolve conversations.
• Custom app installation through the Freshworks Developer Portal, used to relay conversation events to Ada.

Plan tier names change over time, so verify availability with the Freshworks account representative rather than assuming.

Identify the Freshchat subdomain

Ada calls the Freshchat API at https://<subdomain>.freshchat.com/v2/, so the subdomain must be recorded exactly.

To identify the Freshchat subdomain:

1. In Freshworks Customer Service Suite, open Admin Settings → API Settings and find the full API URL in the APIs for Conversations section. The subdomain is the portion before .freshchat.com.
2. In standalone Freshchat, take the subdomain from the URL used to reach the instance.

Generate a Freshchat API token

Ada authenticates every Conversations API call with a Freshchat API token, sent as a bearer token.

To generate a Freshchat API token:

1. Navigate to the API settings for your product:
   • Freshworks Customer Service Suite: Admin Settings → API Settings → APIs for Conversations.
   • Standalone Freshchat: Admin → Configure → API Tokens.
2. Select Generate Token if no token exists yet.
3. Save the API Key. Share it securely with your Ada team in a later step.

Note the channel names Ada will route to

Each handoff creates a Freshchat conversation on a specific channel (some Freshchat UI versions label these Topics). Ada resolves the channel by name and locale rather than by ID, so the name configured on the handoff block must match the channel name in Freshchat exactly.

To note the channel names Ada will route to:

1. In Freshchat, open Admin Settings → Web Chat Topics and note the exact name of each channel the handoff should route to (for example, Chat with us).
2. Note each channel’s locale. The handoff’s locale must match the locale of the target channel, or the channel is not found and the handoff fails.

Note the group names for the utility actions

If the AI Agent should check agent availability before offering a handoff, Ada can query a Freshchat group for its business hours and its recent average first response time. These actions resolve the group by name (case-insensitive).

To note the group names for the utility actions:

1. In Freshchat, open Admin Settings → Conversation Groups and note the exact name of each group to query.
2. Confirm each group has business hours assigned under Admin Settings → Business Hours. This is what the business-hours check reads.

Install the Ada relay app in Freshchat

The Ada relay app is a Freshchat custom app installed in the account. It receives Freshchat’s conversation events and forwards them to the Ada connector, signing each event and tagging it with the AI Agent’s handle. This is all the app does, but it is required for the integration to function.

Generate the Freshchat relay signing secret

The relay app signs every event it sends to Ada, and Ada rejects any event whose signature does not verify. Before installing the app, generate a random secret of at least 32 characters and store it securely. Enter this value into the app during installation, and share the same value with your Ada team — the two must match exactly.

Publish the app in the Developer Portal

To publish the relay app:

1. In the Freshchat account, open Admin Settings → Marketplace Apps and select Go to Developer Portal. Confirm you are in Freshchat, not Freshdesk (see the callout above). If prompted to choose an account, select the one ending in .myfreshworks.com or .freshchat.com.
2. Select New App, then Custom App.
3. Upload the packed Ada relay app (.zip) provided by your Ada team.
4. Complete the required fields:
   • App Name — a descriptive name, for example Ada Conversation Relay.
   • App Overview and App Description — Relay Freshchat conversation events to Ada.
   • Support Email — help@ada.support.
5. Select Save and Publish, then Continue to Save and Publish.
6. Wait a few minutes for the app status to change from Publish in progress to Published. Refresh the page to see the updated status.

Install and configure the app

To install and configure the relay app:

1. Open Admin Settings → Marketplace Apps → Manage Apps and select the Custom Apps tab.

2. Find the newly published app and select Install.

3. Provide the values the app needs to reach the correct Ada connector:

   Field	Description
   Ada bot handle	The handle of the AI Agent. If the AI Agent is accessed at https://example.eu.ada.support, the handle is example.eu.ada.support.
   Freshchat relay signing secret	The secret generated above. The app uses it to sign each relayed event, and Ada rejects any event whose signature does not verify, so it must match the value shared with your Ada team exactly.

4. Select Install.

Share with your Ada team

Once the prerequisites above are complete, share the following with your Ada representative:

1. Freshchat subdomain (for example, acme112344 for https://acme112344.freshchat.com).
2. Channel name(s) that handoffs should route to, and their locale(s).
3. Group name(s) for the business-hours and first-response-time actions (optional).
4. Freshchat API token — share this securely, not in a shared channel.
5. Freshchat relay signing secret — share this securely, as above.