# Actions

> Set up AI Agent actions — Human Handoff, Smart Data Gathering for lead generation, and Custom API Actions to connect external tools.

Define what your Al Agent can do during conversation. From answering questions using real-time API data, collecting leads and market research data, to performing custom tasks.

## Human Handoff

The Human Handoff feature ensures that conversations requiring human attention are seamlessly transferred to a Human Agent.

It is particularly useful for handling questions beyond the AI Agent's Knowledge Base or when users explicitly request to speak to a person. During Human Handoff, the AI Agent pauses, and the Human Agent takes over the conversation via the Inbox.

Here's what happens on the user's side:

1. The user interacts with the AI Agent.
2. If the request is beyond the AI's capability or the user explicitly requests a human, the AI notifies the user about the transfer.
3. The conversation is unassigned from the AI and assigned to a Human Agent.
4. The Human Agent resolves the query or reassigns the AI Agent to continue.

![Human handoff from Visitor perspective.](https://docs.quickchat.ai/_astro/handoff_widget.BgkG8M6x.webp)

And here's what you'll see inside the Quickchat AI interface:

1. The unassigned conversation appears in the Inbox.
2. Your team member reviews the AI Summary to understand the conversation so far.
3. The team member takes over the conversation and handles the user's request.
4. The team member either marks the conversation as resolved or reassigns.

![Human handoff from Quickchat AI's User perspective.](https://docs.quickchat.ai/_astro/interface.aYquez7d.webp)

### Enable Human Handoff

Navigate to **Actions & MCPs** in the left sidebar, find the **Human Handoff** card under **Quickchat AI Actions**, and toggle the switch to "on." Click **Edit Action** to configure the details.

![Enabling human handoff in Quickchat AI's App.](https://docs.quickchat.ai/_astro/handoff_enable.BvVq3NDN.webp)

You can then configure the following options:

**Human Agent's Availability**

Define the availability of Human Agents to ensure that Handoff requests are only initiated during working hours.

- Specify **Working Hours**: Set start and end times and select working days.
- Select **Time Zone**: Ensure the schedule matches your region.
- Configure an **Out-of-Hours Message**: Let users know when no Human Agents are available.

![Configuring Agent availability settings](https://docs.quickchat.ai/_astro/handoff_agents.DuBTGRTe.webp)

### Question

Define the question the AI will ask before initiating Handoff.

**\*Example**: Would you like me to connect you with our Customer Support team?\*

![Configuring handoff question](https://docs.quickchat.ai/_astro/handoff_question.5WmeVKUk.webp)

### Confirmation

Specify the confirmation message sent when the Handoff is initiated.

**\*Example**: I understand. I will transfer you to our Customer Support team. Please wait while I connect you.\*

![Configuring handoff confirmation message](https://docs.quickchat.ai/_astro/handoff_confirmation.DILiKVzw.webp)

### AI Summary

Enable AI Summaries to automatically generate a short note summarizing the conversation so far. This summary provides the Human Agent with all the context needed to quickly address the user's request.

![Configuring AI summary settings](https://docs.quickchat.ai/_astro/handoff_summary.BZhJG5aU.webp)

### Handoff Rules

Describe the situations in which Human Handoff should be triggered. Each rule has a **Name**, a plain-language **Description**, and a **State** toggle so you can enable or disable rules without deleting them.

Quickchat AI ships with a default set of rules covering the most common handoff triggers:

- **Media Message** — the user sent an image, file, or other media the AI can't process.
- **User Frustration** — the user is explicitly angry, frustrated, or dissatisfied.
- **Customer Support Suggestion** — the AI Agent has told the user to contact customer support as the next step, or has clearly ended AI-based assistance.
- **Lack Of Knowledge** — the AI Agent has acknowledged it doesn't have the necessary information.
- **Irrelevant Advice** — the AI Agent has repeatedly tried to help but the user is still not satisfied.

You can toggle any of these on or off, and add your own rules with a custom **Name** and **Description** that tells the AI when to trigger.

:::tip
Write rule descriptions like instructions to the AI. _"The user has explicitly asked for a refund of more than $100"_ is testable; _"escalate VIPs"_ is not (the AI has no way to know who's a VIP unless that's in conversation metadata).
:::

In addition to rules, you can list **Keywords** that will **always** force a Human Handoff regardless of context — useful for compliance words like "lawsuit", "GDPR", or "chargeback" that you never want the AI to handle.

### Topic routing

When Human Handoff fires, **Topic routing** sends the conversation to the human agent best suited to handle that topic instead of leaving it unassigned in a shared queue.

Configure routing by mapping each topic (defined under **Insights → Manage Topics**) to one or more team members. When a handoff is triggered, Quickchat reads the conversation's detected topic and routes the conversation to one of the agents assigned to that topic. If no rule matches, the conversation is left unassigned for any teammate to pick up from the Inbox.

### Email Notifications

Configure email addresses to receive notifications when a new conversation requires a Human Handoff.

Here's how it looks:

![Configuring email notification settings](https://docs.quickchat.ai/_astro/handoff_email.AI8iTEcp.webp)

---

## Smart Data Gathering / Lead Generation

**Smart Data Gathering** allows your AI Agent to collect user information seamlessly during conversations. It engages with users naturally, asking relevant questions to gather details like name, email, phone number, or any other information you require. This data can then be sent to your CRM or other systems, enabling you to follow up effectively and convert potential leads into customers.

### How it works

Smart Data Gathering operates within the existing conversation flow, ensuring that the interaction feels natural and non-intrusive.

When a user interacts with your AI Agent, it:

1. Detects opportunities to collect information, such as when a user expresses interest in your services or products.
2. Asks specific questions tailored to your needs, like:
   - "Can I have your name to better assist you?"
   - "What's the best email to contact you on?"
3. Gathers and stores the responses, making them available for review or integration with your CRM system.

The feature is designed to minimize friction while maximizing the quality of leads captured.

### Setting it up

### Enable Smart Data Gathering

- Navigate to the **Actions & MCPs** tab
- Find **Smart Data Gathering** card
- Toggle the feature on

![Enabling Smart Lead Generation](https://docs.quickchat.ai/_astro/leadgen_enable.C-xDKuYd.webp)

### Data to Collect

Select contact details to capture.

- Email address
- First name
- Phone number

![Selecting data fields to collect](https://docs.quickchat.ai/_astro/leadgen_data2collect.DsayYkv-.webp)

### When to Ask for Data

Define when the AI Agent should ask for contact details.

- After exchanging a few messages
- Immediately after the user expresses interest

![Configuring when to collect data](https://docs.quickchat.ai/_astro/leadgen_when_to_ask.HHWVbm3J.webp)

### How to Ask for Data

Customize how the AI Agent asks for information.

- **Subtle:** Integrates questions naturally into the conversation
- **Direct:** Explicitly requests the information in a straightforward manner

![Configuring data collection approach](https://docs.quickchat.ai/_astro/leadgen_how_to_ask.Dlu-o5LJ.webp)

Smart Lead Generation enables your AI Agent to collect user contact details efficiently while ensuring compliance and providing a seamless conversational experience.

### Exporting the captured contact details

Follow these steps to export the details captured by your AI Agent:

1. Go to the **Inbox**
2. Click the **export file** icon to access export options.
3. Select **Export Gathered Data** from the dropdown menu.
4. Set **Date Range**: Specify the **start** and **end** dates for the data you want to export.
5. Choose **Format**: Select the file format for your export (CSV, XLSX).
6. Download: Click **Download** to save the exported data to your computer.

---

## Custom Actions

Custom Actions let your AI call external tools during a conversation — search internal systems, create tickets, trigger alerts, or fetch fresh data that isn't in the Knowledge Base. Find them in **Actions & MCPs** under the **Custom Actions** section.

Click **+ Add Action** to create one. The dropdown offers three types:

- **API Action** — call any REST endpoint over HTTP. The most general option; use this for anything that has a URL and accepts JSON.
- **HubSpot Action** — pre-built connection to your HubSpot CRM. Use it to look up contacts, deals, or tickets without managing API tokens yourself.
- **Shopify MCP** — connect a Shopify store via the Shopify MCP server so the AI can query products, orders, inventory, and customers. Only one Shopify MCP action per scenario.

:::note
Your plan includes a quota of Custom Actions. The **Remaining: N** counter next to the **+ Add Action** button shows how many you can still create. Upgrade your plan if you need more — [contact us](mailto:contact@quickchat.ai).
:::

### How Custom Actions work

1. You define an action (API Action, HubSpot Action, or Shopify MCP) with a name, a detailed description, and any parameters the AI needs to fill in.
2. During a chat, the AI uses your description and parameter hints to decide when to run the action.
3. Quickchat executes the call and returns the result to the AI. The AI reads the response and replies to the user in natural language.
4. You can test the request from the Action editor before using it in conversations.

:::tip
Write the description as an instruction to the AI. Tell it **when** to use the action, **what** it returns, and any **guardrails** (e.g., "only call when the user provides an order number").
:::

### Create an API Action

1. Go to **Actions & MCPs**.
2. Click **+ Add Action** in **Custom Actions** and choose **API Action**.
3. Fill in **Details**:
   - **Name**: clear and descriptive.
   - **Description**: when to use it and what to include in parameters.
4. Configure **Connection**:
   - **Action Type**: HTTP method (GET, POST, etc.).
   - **Action endpoint URL**: full API URL.
   - **Headers**: add any required headers like `Authorization` or `content-type: application/json`.
5. Define **Parameters**: give each parameter a **name**, **location** (query, body, header, or path), and a **description** that tells the AI how to compose the value.
6. **Test request** and verify the response. Then click **Done**.

:::tip
Any value field (URL, header, body, or query) accepts dynamic placeholders via the **+ Add AI Data** button. You can inject your AI parameters, built-in conversation variables (`{{scenario_id}}`, `{{language}}`, `{{country}}`, ...), and conversation metadata (`{{metadata_*}}`). See [AI Action Variables](/ai-agent/variables/) for the full reference.
:::

### Best practices

- **Be explicit in descriptions**. Tell the AI when to use the action and what each parameter should contain.
- **Keep scopes minimal**. Only include the headers and tokens the endpoint needs. For Jira, use the Basic header derived from your Atlassian email and API token.
- **Test before rollout** using the Test request panel. Confirm status codes and sample payloads look right in the target tool.

#### Tutorials

- [Search Jira tickets in AI conversation](https://quickchat.ai/post/search-jira-tickets-in-ai-conversation)
- [Send Slack notification with an AI Action](https://quickchat.ai/post/slack-notification-ai-action)