Configure the Gorgias handoff

After you complete the initial configuration and share your credentials, your Ada team will set up the backend integration. When setup is complete, the Gorgias Utilities 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 Gorgias Utilities block

Each handoff is associated with a customer record in Gorgias and creates a ticket, which can optionally be routed to a team. Once your Ada team confirms setup is complete, the Gorgias Utilities app appears in Config → Apps (it has no app-level configuration fields).

To add the Gorgias Utilities block:

In your handoff answer, add the Gorgias Utilities block with action Handoff to a human agent.
The two required Ada ID fields are pre-populated by the block:
- ada_conversation_id → @oauth/conversation_id
- ada_user_id → @oauth/end_user_id
Optionally fill in any of the additional fields documented below.

When a handoff successfully connects to Gorgias, the following meta-variable is set on the conversation and can be used for troubleshooting or reporting:

agent_system_gorgias_conversation_id — the Gorgias ticket ID

Handoff input fields

The Gorgias Utilities block accepts the following input fields.

Field	Required	Description
`ada_conversation_id`	Yes	Conversation ID. Populated by `@oauth/conversation_id`.
`ada_user_id`	Yes	End user ID. Populated by `@oauth/end_user_id`.
`user_email`	No	End user email address. Used to find or create the customer record in Gorgias.
`user_first_name`	No	End user first name.
`user_last_name`	No	End user last name.
`team_name`	No	Gorgias team name to assign the ticket to. Must match an existing team name in Gorgias.
`subject`	No	Ticket subject. Defaults to `Conversation with <email or User>` if omitted.
`tags`	No	Comma-separated list of tag names to apply to the ticket. The `ada_handoff` tag is always added automatically.
`language`	No	Language code for the ticket (e.g. `en`, `fr`).
`chat_summary`	No	Summary of the chat to append after the conversation transcript when creating the ticket.
`keep_agent_conversation_open`	No	If set to `'true'`, the Gorgias ticket is left open when the handoff ends on the Ada side. Defaults to `'false'`, which closes the ticket automatically when the handoff ends.

If a Gorgias customer record already exists with the same email, the integration does not update its first or last name. The user_first_name and user_last_name fields are only used when a new customer record is created. To update an existing record’s name, update it directly in Gorgias.

Custom fields

Gorgias custom fields can also be sent on the ticket. These are configured per AI Agent by your Ada team. See Custom ticket fields for the full pattern.

Test the handoff

Test the integration before placing it in a live handoff. Test in a separate handoff answer before placing the new handoff in any live handoff dialogue.

To test the handoff:

Trigger a test handoff from the AI Agent, for example via a sandbox conversation that escalates to the new handoff answer.
In Gorgias, confirm a new ticket appears with the ada_handoff tag.
As the agent, reply to the ticket. The message appears in the conversation.
Mark the ticket as Done in Gorgias. The conversation resumes, allowing the end user to continue chatting with the AI Agent.

Frequently asked questions

Common questions about configuring the Gorgias handoff are answered below.

How are custom Gorgias fields passed through the handoff?

They are passed via custom_field_<id> keys in the handoff request, where <id> is the Gorgias custom field ID. To expose those fields as labeled inputs in the block, your Ada team adds a per-AI Agent configuration. See Custom ticket fields.

Does the handoff create or update the Gorgias customer record?

The handoff finds or creates a customer record in Gorgias keyed by user_email. If a record is created, user_first_name and user_last_name populate the new record. If a record already exists with the same email, the existing record is used as-is — the first and last name you provide do not overwrite what is already in Gorgias.