> 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 Gorgias handoff

After you complete the [initial configuration](/docs/handoffs/gorgias/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.

> **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 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:**

1. In your handoff answer, add the **Gorgias Utilities** block with action **Handoff to a human agent**.
2. 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`
3. 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. |

> **Note**
>
> 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](/docs/handoffs/gorgias/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:**

1. Trigger a test handoff from the AI Agent, for example via a sandbox conversation that escalates to the new handoff answer.
2. In Gorgias, confirm a new ticket appears with the `ada_handoff` tag.
3. As the agent, reply to the ticket.
   The message appears in the conversation.
4. 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](/docs/handoffs/gorgias/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.

---

Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).