Configure the Kustomer handoff

After you complete the initial configuration and share your credentials, your Ada team will set up the backend integration. When that is complete, the Kustomer Utilities app will appear in Config → Apps in your AI Agent dashboard, and you can begin configuring 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. The Kustomer Utilities app has no app-level configuration fields — it is configured within a handoff.

Add the Kustomer Utilities block

Each handoff in Kustomer creates a Conversation associated with a Customer, optionally routed to a Queue. When a handoff successfully connects to Kustomer, the conversation transcript, plus any chat summary, is sent as the initial message in the Kustomer conversation.

To add the Kustomer Utilities block:

In your handoff answer, add the Kustomer Utilities block with action Handoff to 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 in the table below.

When a handoff successfully connects to Kustomer, the following meta-variables are set on the conversation and can be used for troubleshooting or reporting:

agent_system_kustomer_conversation_id — the Kustomer conversation ID
agent_system_kustomer_user_id — the Kustomer customer (contact) ID

Handoff input fields

The Kustomer 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 in Kustomer.
`user_phone`	No	End user phone number. Used to find or create the customer in Kustomer.
`user_first_name`	No	End user first name.
`user_last_name`	No	End user last name.
`queue_id`	No	Kustomer Queue ID to route the conversation to. Find this in Kustomer under Settings → Platform → Routing → Queues.
`subject`	No	Conversation subject or name shown in Kustomer.
`tags`	No	Comma-separated list of tag names to apply to the Kustomer conversation.
`chat_summary`	No	Summary text appended to the conversation transcript sent to Kustomer.
`keep_agent_conversation_open`	No	If set to `'true'`, the Kustomer conversation is left open when the handoff ends. Defaults to `'false'`, which closes the Kustomer conversation automatically when the handoff ends.

Custom attributes

Kustomer custom attributes — both conversation-level and contact-level — can be sent on the handoff. Because Kustomer requires typed custom attributes, each attribute name must include a type suffix. See Custom attributes for the full pattern.

Test the integration

After your Ada team confirms the installation is complete and you have set up the Kustomer Outbound Webhook, walk through the following sequence to verify the integration end-to-end.

To test the integration:

Trigger a test handoff from the AI Agent (for example, via a conversation that escalates to a test handoff answer).
In Kustomer, verify a new conversation appears, routed to the Queue you specified (if any). The conversation should include the Ada transcript as the initial message.
As the agent, send a reply in Kustomer. The message appears in the conversation.
Mark the conversation as Done in Kustomer (or snooze it, if snooze-as-close is enabled). The conversation resumes, allowing the end user to continue chatting with the AI Agent.

Frequently asked questions

Common questions about configuring and operating the Kustomer handoff are answered below.

How do I find the Kustomer Queue ID?

In Kustomer, navigate to Settings → Platform → Routing → Queues, click on the queue you want chats to route through, and copy the ID from the URL (the UUID after /queues/).

How are custom attributes passed through the handoff?

Custom attributes are configured per AI Agent by your Ada team, using type-suffixed keys (Str, Txt, Num, or Bool) with either an attribute_ prefix (conversation attributes) or a contact_attribute_ prefix (contact attributes). See Custom attributes.

Does the handoff create or update a customer record in Kustomer?

The handoff will find or create a customer in Kustomer keyed by user_email (or user_phone if email isn’t provided). If a customer is created, user_first_name, user_last_name, and any contact attributes populate the new record. If a customer already exists, the contact attributes are updated on the existing record.

What happens when the Kustomer agent snoozes the conversation?

By default, snoozing closes the handoff, so the end user can resume chatting with the AI Agent. If your team requested that snooze-as-close be disabled, snoozing has no effect on Ada — only marking the conversation as Done closes the handoff.

Can the snooze behavior be changed after installation?

Yes, but it requires your Ada team to update the configuration — there is no dashboard setting for it. Contact your Ada representative to change it.