Creating an inbound lead qualification AI Voice Agent with HubSpot AI Actions

Set up an Inbound AI Voice Agent that qualifies leads and updates their Contact record in HubSpot using HubSpot AI Actions. This article walks through activating the required integration settings, creating and configuring the agent, testing it, and activating it on your call flow.

Note: Throughout this article, we'll use an example based on ACME, a mortgage broker running a social media campaign targeting new customers, whether they're first-home buyers or refinancing. The campaign drives inbound calls to a dedicated number, where an AI Voice Agent answers and qualifies them from there. The agent collects key details and asks whether the caller is ready to apply today or still exploring their options. Callers who are ready to apply are transferred directly to a mortgage consultant while their intent is high. Those still exploring are handled gracefully, with the agent letting them know a consultant will be in touch before ending the call. The details collected during the call update corresponding fields on the contact record in HubSpot using the Get Contact and Update Contact AI Actions.

By implementing this configuration, every inbound lead is answered, qualified, and routed automatically with no manual effort required. High-intent leads reach the right person instantly, lower-intent ones are handled gracefully, and every interaction is centralized in HubSpot. This is particularly valuable during high-volume campaigns, where the agent absorbs the load your team otherwise couldn't.

How it works

This setup can be adapted to suit virtually any scenario, but here's what a typical call flow looks like for the ACME example:

1. A new lead calls the dedicated campaign number and is connected to the AI Voice Agent.
2. The call triggers the creation of a new HubSpot contact record via the HubSpot integration settings.
3. The agent immediately triggers the Get Contact AI Action, retrieving the freshly created HubSpot Contact record before qualification begins.
4. The agent qualifies the caller, including asking whether they're ready to apply today or still exploring their options.
5. If the caller is ready to apply, the agent triggers the Update Contact AI Action to update the Contact record with the captured information, then transfers the call directly to a mortgage consultant.
6. If the caller is still exploring, the agent triggers the Update Contact AI Action to update the Contact record with the captured information, then lets them know a consultant will be in touch before politely ending the call.

Before you begin

This guide assumes the following are already in place:

• You have an active HubSpot account.
• You have an active HubSpot integration on the Aircall Dashboard.
• In the HubSpot integration settings on the Aircall Dashboard, the setting "If number/contact doesn't exist in HubSpot" is set to "Create a new HubSpot Contact."
• The phone number you plan to deploy your AI Voice Agent on is connected to the HubSpot integration where you're configuring AI Actions.
• The first name, last name, phone, city, and lifecycle stage properties exist on the HubSpot Contact object and are available to update.
• You have business hours implemented on the phone number you wish to deploy the AI Voice Agent on.

Step 1: Activate AI Actions and contact creation settings

Enable AI Actions on the specific HubSpot integration you want to connect your AI Voice Agent to. For the ACME use case, this means enabling Get Contact and Update Contact.

Steps:

1. On the Aircall Dashboard, go to Integrations > Apps from the left-hand navigation menu.
2. Find and select your existing HubSpot integration.
3. Click the AI Actions tab in the top navigation bar.
4. Enable Get Contact and Update Contact under AI Voice Agent.

Contact creation in this workflow is handled by a native Aircall x HubSpot integration setting on the Aircall Dashboard, "If number/contact doesn't exist in HubSpot," rather than the Create Contact AI Action. This setting fires as soon as a call connects with the AI Voice Agent, creating a record for any new number.

We deliberately avoided the Create Contact AI Action because using it would require disabling the native setting to prevent duplicate contacts. That's not a safe trade-off on shared numbers: if a line handles both AI agent and team traffic, or both inbound and outbound calls, disabling the setting would silently stop contact creation for everyone else using that number, not just the AI Voice Agent. Since CRM logging depends on the number being connected to the integration in the first place, keeping the native setting on is the only way to guarantee coverage across all call types.

In most cases, this feature is already turned on and in use in your daily workflow. If you're not sure:

Steps:

1. Click Settings on your existing HubSpot integration.
2. Scroll down to find If number/contact doesn't exist in HubSpot.
3. Select Create a new HubSpot contact from the dropdown menu.
4. Click Save.

Note: If you currently don't use this feature in your daily operations and handle contact creation another way, leave this off. If you'd like your AI Voice Agent to create contacts instead, add the Create Contact AI Action and incorporate it into your configuration throughout this guide.

Step 2: Create and configure your AI Voice Agent

Steps:

1. Go to Aircall Dashboard > AI Agents > AI Voice Agents from the left-hand navigation menu.
2. Click Create an AI Voice Agent and select Inbound.

Note: If your dashboard is set to English, you can use the automated Agent Builder to describe your AI Voice Agent's desired behavior in plain language, with the option to incorporate call transcripts to inform the configuration. Some elements will still need to be configured manually, which this guide covers. For more information on using Agent Builder, please see Configuring your AI Voice Agent.

Once the agent is created, it must be configured. Start with these settings:

• Agent profile: sets the agent's core identity.
• Company information: defines how the agent refers to your business.
• Call script (greeting and farewell messages): defines the messages callers hear at the start and end of a call.

Note: If you used Agent Builder, the basic configuration should be populated, but you'll still need to review these steps.

Four configuration settings are especially important for this use case:

Knowledge base

The knowledge base is where you provide the information the agent uses to answer caller questions. It consists of one or more knowledge sources that can be connected to a single agent.

Tip: For best performance, keep the knowledge base focused. Stick to your most frequently asked questions on the topics most relevant to this specific deployment. Overloading the knowledge base can slow down responses and reduce accuracy.

For the ACME mortgages use case, the knowledge base is simple: it covers FAQs related to available services, and branch locations and their opening times.

Note: If you used Agent Builder with call transcripts, a concise FAQ knowledge source will have been generated based on your conversations and prompt. Open it, review it, and add to it or connect additional sources as needed.

Transfer rules

Transfer rules are where you configure how and when the call gets transferred to a live rep or team.

For this use case, a call should only be transferred once the agent has completed the initial qualification and confirmed the lead is ready to apply. To accommodate this, set the transfer timing to After intake questions. This is reinforced further in Conversational guidelines.

Steps:

1. Navigate to Call transfer rules on the left-hand navigation menu of the AI agent.
2. Enable Allow AI Voice Agent to escalate the call by toggling it on.
3. Select After intake questions.
4. Enter your transfer message, this is what your agent says before transferring the call. For example: "I am connecting you to a mortgage consultant now. Please hold."

Note: If you do not wish your agent to do a live transfer to a rep or team, you can skip this step, since transfer is disabled by default on new AI Voice Agents.

Intake flow

Intake questions are where you configure the qualifying questions the agent asks the caller, including the question that determines whether the call is transferred. Some responses are also used to map to specific HubSpot properties when using the Update Contact AI Action.

Tip: Ask no more than five intake questions. Asking too many can lengthen the conversation and frustrate the caller, so stick to what your team actually needs at this stage of the lead cycle.

When a call is transferred, intake questions are passed to the receiving rep for context, and logged in a structured format on the call log in HubSpot and Aircall Workspace once the call ends.

For the ACME use case, the intake questions are:

• What is your first name?
• What is your last name?
• Are you a first-home buyer or refinancing?
• What city are you looking to buy a property in?
• Are you ready to apply for a mortgage today?

Call script - Conversational guidelines

Conversational guidelines let you shape how the agent conducts a conversation, refining tone, defining phrase responses, and directing how it handles edge cases. This is also where you set the if/then logic that enables autonomous decision-making, giving your agent the ability to reason within the guardrails you've set.

For the ACME use case, conversational guidelines reinforce the transfer settings by defining the if/then logic that determines the call outcome. If the lead is ready to apply today, the agent transfers the call to a consultant. If they're still exploring their options, the agent handles the call end-to-end and logs it for a consultant to follow up.

**QUALIFICATION TRANSFER THRESHOLD**.
- If the answer to the intake question "Are you ready to apply for a mortgage today?" is YES, transfer the call immediately
- If the answer is NO: inform the customer a mortgage consultant will be in touch with them shortly and end the call.
- If the answer is vague or unclear, ask them to clarify. If their intent remains unclear after a second attempt, consider the answer NO.
- Do not explain the threshold to the caller under any circumstances

Note: If you opted to disable transferring in the previous step and have the agent handle all calls end-to-end, the above template is not required. Conversational guidelines can instead be used to shape the agent's tone and behavior to suit your use case.

AI actions

Add the AI Actions to your AI Voice Agent.

Steps

1. Navigate to AI actions in the left-hand navigation menu of the AI agent.
2. Click Add action.
3. In the side panel, open the dropdown list and select HubSpot > Get Contact. Click Save action.
4. Repeat for HubSpot > Update Contact.

AI actions conversational guidelines

This is where you define when the agent should use each action, and what to say or do afterward.

For the ACME mortgages use case, the Get Contact action fetches the contact created by the inbound call via the integration setting from Step 1. Since this contact was just created by the Aircall call, its phone field is already populated, so it's used for verification at the start of the call: instead of asking the caller for their number, the agent reads it back from context and asks for a yes or no confirmation. Once confirmed, the agent stores the contact ID for all subsequent actions on the call.

The Update Contact action then maps the intake questions to HubSpot contact properties. This must run after qualification is complete, and before the call is transferred or ends. AI Actions currently only support mapping to standard fields, so the ACME use case maps:

Lifecycle stage differs slightly from the other properties. For lifecycle stage, the update is to a fixed value based on the response, not the response itself. If the caller answers "yes" to "are you ready to apply for a mortgage today," the property is updated to Sales Qualified Lead (internal value: salesqualifiedlead); if "no," it's updated to Marketing Qualified Lead (internal value: marketingqualifiedlead).

The values you use will depend on whether you're on standard or custom lifecycle stages, and where this call sits in your sales cycle. Replace salesqualifiedlead with whatever's relevant to your own use case.

Note: Not every intake question needs to map to a HubSpot property. Some exist purely to give your team context on transfer, or in the call activity logged in HubSpot. Avoid forcing a question into a property mapping if there isn't a natural fit.

Here is a base template you can use to get started:

**Get Contact**
- At the start of the call, use 'Get Contact' to retrieve the contact record created by the inbound call, using the caller's {{phone}} number from context
- Read the number back to the caller in E164 format: "Just to confirm, {{phone}} is the number you're calling from?" and confirm yes or no
- If YES - identity confirmed. Store the contactId for use in later actions and move on to the intake questions.
- If NO - apologise and say "I'm having trouble verifying your details. Someone from our team will follow up with you shortly" and end the call.

**Update Contact**
- Once all intake questions have been answered, use 'Update Contact' with the contactId stored earlier to update the following fields:
  - firstname: caller's answer to "What is your first name?"
  - lastname: caller's answer to "What is your last name?"
  - city: caller's answer to "What city are you looking to buy a property in?"
  - lifecyclestage: do not use the caller's raw response. If the answer to "Are you ready to apply for a mortgage today?" is YES, set lifecyclestage to "salesqualifiedlead". If NO, set lifecyclestage to "marketingqualifiedlead"
- Update Contact must always fire after qualification is complete and before the call branches into a transfer or sign-off, so the contact record is updated regardless of outcome

Step 3: Test your lead qualification agent

Once everything is configured, test your agent thoroughly using the Test call panel on the right-hand side of the agent editor before activating it in your call flow. This simulates a real call experience without firing any call activity to your team or triggering activity in your HubSpot org.

Run through three scenarios to confirm the agent behaves as expected:

• Happy path: call in as a new customer who is ready to apply and confirm the agent transfers the call to a mortgage consultant. Then call in as a caller who is still exploring their options and confirm the agent handles the call end-to-end and closes gracefully.
• Fuzzy path: give a vague or uncertain answer when asked if you're ready to apply, such as "maybe" or "I'm not sure yet," and confirm the agent asks a clarifying question rather than making an assumption about which path to take.
• Unhappy path: push the agent with challenging conditions, such as interrupting mid-response, giving contradictory answers about your readiness to apply, or asking it to do something outside its scope. Confirm the agent handles these gracefully rather than routing incorrectly.

If you encounter unexpected results, identify the issue, make the necessary adjustments, and repeat until you're confident the agent is ready to serve customers.

Step 4: Activate your lead qualification agent

To activate your agent, add it to your call distribution. A few things worth noting before you do:

• If you're using the transfer workflow from this guide, you need a live team available to receive warm leads. We recommend implementing a time rule widget to establish business hours if you haven't already. Place the agent at the start of the call distribution on the Open branch so it receives and qualifies every inbound call, with your live team sitting below it to receive transfers.
• If you want the agent to qualify calls outside of business hours, clone the agent, disable the transfer option, and remove all references to transfers or transferring from the conversational guidelines in both the Call script and AI actions tabs. The cloned agent will handle qualification end-to-end, with your team following up on logged leads during business hours.

For the ACME mortgages use case, the agent is only deployed during business hours. It's placed at the start of the Open branch in the call distribution, with the ACME mortgages team sitting beneath it to receive transferred calls.

Steps:

1. Navigate to Numbers in the left-hand menu and select the relevant number, ensuring it's connected to the relevant HubSpot integration.
2. Click Edit in the top right corner to open the call flow editor.
3. Click the + icon on your opening hours branch to open the widget menu and select AI Voice Agent.
4. Search for and select your routing AI Voice Agent.
5. Add the relevant users or teams under each corresponding transfer branch.
6. Click Publish. Your agent is now live.

Important: Activating this agent affects your live call routing. We strongly recommend deploying it outside of business hours or during a period of low call traffic to minimize disruption.

Important: After deployment, monitor your agent's performance by reviewing calls and using the AI Voice Agent performance dashboard. For more information, please see Track AI Voice Agent's performance.

Best practices

• Keep the native "If number/contact doesn't exist in HubSpot" setting on rather than switching to the Create Contact AI Action, especially on shared numbers, to guarantee CRM coverage across all call types.
• Keep the knowledge base focused on FAQs most relevant to this specific deployment.
• Limit intake questions to five or fewer, and only map questions to HubSpot properties where there's a natural fit.
• Use a fixed value for lifecycle stage updates based on the caller's answer, not their raw response.
• Ensure Update Contact always fires after qualification is complete and before the call branches into a transfer or sign-off, so the record is updated regardless of outcome.
• Test across happy, fuzzy, and unhappy path scenarios before going live.
• Deploy outside business hours or during low call traffic to minimize disruption to live call routing.
• Monitor performance regularly after launch to catch and resolve any unexpected behavior.

FAQs

Why isn't the AI Voice Agent using the Create Contact AI Action?

Using the Create Contact AI Action would require disabling the native "If number/contact doesn't exist in HubSpot" setting to avoid duplicate contacts. On shared numbers, that would silently stop contact creation for other traffic on that line, not just the AI Voice Agent. Keeping the native setting on guarantees coverage across all call types.

Do I need business hours configured to use this agent?

Yes, if you're using the transfer workflow, since a live team needs to be available to receive warm leads. We recommend implementing a time rule widget to establish business hours if you haven't already.

Can this agent qualify leads outside of business hours?

Yes. Clone the agent, disable the transfer option, and remove all references to transfers from the conversational guidelines in both the Call script and AI actions tabs. The cloned agent handles qualification end-to-end, with your team following up on logged leads during business hours.

Does every intake question need to map to a HubSpot property?

No. Some intake questions exist purely to give your team context on transfer, or in the call activity logged in HubSpot. Avoid forcing a question into a property mapping if there isn't a natural fit.

What happens if the agent can't verify the caller's identity?

The agent apologizes, lets the caller know someone from the team will follow up shortly, and ends the call.

What if the caller gives a vague answer about their readiness to apply?

The agent asks them to clarify. If their intent remains unclear after a second attempt, it's treated as a "no," and the caller is told a consultant will follow up.