Configure the Freshchat handoff

After you complete the initial configuration and share your credentials, your Ada team completes the backend integration setup. When setup is complete, the Freshchat app appears in Config → Apps in your AI Agent dashboard, and you can configure the handoff block.

Your Ada team will complete the backend integration setup. Contact your Ada representative to confirm when this step is finished before proceeding.

Add the Freshchat block

In Freshchat, each handoff finds or creates a user by email, then opens a new conversation on a named channel that includes the AI Agent’s transcript. Ada bidirectionally relays text messages and attachments between the end user and the human agent until the agent resolves the conversation.

To add the Freshchat block:

In your handoff answer, add the Freshchat block with action Handoff to a human agent.
The two required Ada ID fields are pre-filled by the block:
- ada_conversation_id → @oauth/conversation_id
- ada_user_id → @oauth/end_user_id
Set the remaining required inputs — locale, channel_name, and email_address — then map AI Agent variables into any of the optional fields in the table below.

An end-user email address is required. Freshchat user identity is keyed entirely on email: Ada looks up the Freshchat user by email and creates one if none exists. An end user whose email has not been collected cannot be handed off, so collect it earlier in the conversation before this block runs.

Handoff input fields

The Freshchat block accepts the following input fields.

Field	Required	Description
`ada_conversation_id`	Yes	Ada conversation ID. Pre-filled with `@oauth/conversation_id`.
`ada_user_id`	Yes	Ada end user ID. Pre-filled with `@oauth/end_user_id`.
`locale`	Yes	Language code, pre-filled with `en-us`. Scopes the channel lookup — it must match the locale of the target channel in Freshchat, or the channel is not found and the handoff fails.
`channel_name`	Yes	The name of the Freshchat channel to route the conversation to, pre-filled with `Chat with us`. Must match the channel name in Freshchat exactly.
`email_address`	Yes	End-user email. Used to find or create the Freshchat user the conversation is opened as. Pass it lowercased — inconsistent casing between handoffs can create duplicate Freshchat users for the same person.
`first_name`	No	End-user first name, set on the Freshchat user record.
`last_name`	No	End-user last name, set on the Freshchat user record.
`phone_number`	No	End-user phone number, set on the Freshchat user record.
`chat_summary`	No	Summary text appended after the conversation transcript in the opening message the agent sees.
`agent_name_override`	No	Static display name shown in Ada for all agent messages, useful when a static label such as “Agent” or “Support” is preferred. If left empty, Ada uses the Freshchat agent’s first and last name, or the literal word `Agent` if the record has neither.
`keep_agent_conversation_open`	No	`true` or `false` (default). When `true`, ending the handoff on the Ada side leaves the Freshchat conversation open and posts a system message noting the end user has left, instead of resolving the conversation — useful when agents are expected to wrap up in Freshchat themselves.
`custom_user_attributes`	No	JSON object of custom user properties, for example `{"tier": "gold"}`. Written to the Freshchat user record on every handoff.
`custom_conversation_attributes`	No	JSON object of custom conversation properties, for example `{"order_id": "1234"}`. Set on the Freshchat conversation at creation.

Custom properties

Both custom-property inputs take a flat JSON object of string keys to string values. Nested objects, arrays, numbers, and booleans are rejected.

For agents to see custom conversation properties in the agent desktop, those properties must already be defined in the Freshchat account. Custom user properties appear on the user record.

Conversation meta-variables

The connector writes Freshchat identifiers back to the end user’s metadata, where they are available as AI Agent variables. They are useful for troubleshooting a specific conversation and for tying Ada conversations to Freshchat records in reporting.

Variable	Description
`agent_system_freshchat_conversation_id`	The Freshchat conversation opened for the handoff. Written when the handoff is created — this is the value to use when tying an Ada conversation to a Freshchat record.
`agent_system_freshchat_user_id`	The Freshchat user the conversation was opened as. Written when the handoff is created.
`agent_system_freshchat_agent_id`	The Freshchat agent who most recently replied. Updated on each agent message.

Test the handoff

After your Ada team confirms the configuration is complete and the relay app is installed, walk through the following sequence to verify the integration end-to-end.

To test the handoff:

Confirm the channel name and locale in the block match a real channel in Freshchat (Admin Settings → Channels). A mismatch is the most common cause of a failed first handoff.
Trigger a test handoff from the AI Agent, using an email address you can identify.
In Freshchat, verify a new conversation appears on the expected channel, opened as the end user, with the AI Agent’s transcript as its first message.
As the agent, accept the conversation and send a reply. The message appears in the Ada conversation, attributed to the agent’s name (or to agent_name_override, if set).
Send an attachment in each direction. Confirm both arrive.
Send a further message as the end user. Confirm it appears in Freshchat attributed to that user, not as a private note or a system message.
Resolve the conversation in Freshchat. Confirm the handoff ends and the end user can continue chatting with the AI Agent.
If keep_agent_conversation_open is true, end the chat from the Ada side. Confirm the Freshchat conversation stays open, with a system message noting the end user has left posted into it.

Frequently asked questions

Common questions about configuring the Freshchat handoff are answered below.

How does Ada decide which Freshchat user a conversation belongs to?

By email. Ada looks up the Freshchat user matching email_address, updates their name, phone number, and custom user properties, and creates the user if no match exists. Subsequent end-user messages are posted as that user, which is why the email address is required.

Why is the channel resolved by name instead of by ID?

It lets the block be configured without needing Freshchat API IDs. Ada resolves the name to a channel ID through a locale-scoped lookup and caches the result for 30 days. If a channel is renamed or recreated in Freshchat, the cached ID can remain in use until the cache entry expires.

What ends the handoff?

Either side. An agent resolving the conversation in Freshchat ends the handoff; the end user ending the chat in Ada resolves the Freshchat conversation, unless keep_agent_conversation_open is true.

What happens on a second handoff in the same conversation?

A new Freshchat conversation is created, seeded only with the messages exchanged since the previous handoff ended — the agent is not re-sent the earlier transcript.

Can the AI Agent check whether agents are available before offering a handoff?

Yes. See Additional actions.