> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Configure the Freshchat handoff After you complete the [initial configuration](/docs/handoffs/freshchat/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. > **Info** > > 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:** 1. In your handoff answer, add the **Freshchat** block with action **Handoff to a human agent**. 2. 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` 3. 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. > **Warning** > > 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:** 1. 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. 2. Trigger a test handoff from the AI Agent, using an email address you can identify. 3. 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. 4. 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). 5. Send an attachment in each direction. Confirm both arrive. 6. 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. 7. Resolve the conversation in Freshchat. Confirm the handoff ends and the end user can continue chatting with the AI Agent. 8. 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](/docs/handoffs/freshchat/additional-actions). --- Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).