HubSpot Integration Overview

The HubSpot integration gives your Velaro AI agent direct access to 29 AI tools spanning contact management, company lookup, deals and pipeline, tickets and support, tasks, engagement, quotes, sequences, form submissions, and meeting history. The AI agent can look up records, create deals, open tickets, log notes, send quote links, enroll contacts in email sequences, and surface real-time HubSpot data — all without a human agent.

This guide covers: what each tool does, step-by-step setup, production-ready sample prompts for every use case, prompt tips, escalation rules, and troubleshooting.

Quick Setup (3 Steps)

Step 1 — Connect HubSpot

Go to Integrations → HubSpot and click Connect HubSpot. You'll be redirected to HubSpot's OAuth screen. Approve the permissions and you'll return to Velaro with an active connection. You can connect multiple HubSpot portals for different brands or regions.

Step 2 — Enable AI Skills

Go to Bots → AI Training → Skills and turn on the HubSpot AI skill group. All 29 tools activate at once — no per-tool configuration required.

Step 3 — Launch Starter Wizard

Go to Integrations → HubSpot → Launch Starter Wizard. Pick a pre-built template (Sales Pipeline AI Agent, Support Ticket AI Agent, Lead Management AI Agent, Account Manager AI Agent, or Full CRM Specialist) and the wizard generates a ready-to-use workflow with the right system prompt pre-filled.

All 29 AI Tools

Contact Management (5 tools)

hubspot_search_contact — Find a HubSpot contact by email or phone. Returns name, company, lifecycle stage, and deal info. Use this first when a visitor identifies themselves.

hubspot_get_contact — Fetch the full contact record including all HubSpot properties, associated deals, and complete activity history. Call after hubspot_search_contact to get full details.

hubspot_update_contact — Update contact properties such as lifecycle stage, job title, phone number, or owner. Always confirm with the visitor before updating.

hubspot_create_contact — Create a new HubSpot contact from visitor data collected during the conversation. Set lifecycle stage to "Lead" for new prospects.

hubspot_search_contacts — Advanced multi-filter search across contacts — by name, company, owner, lifecycle stage, or date range. Use when a single email search isn't enough.

Company (3 tools)

hubspot_search_companies — Find companies in HubSpot by name or domain. Returns industry, employee count, and associated contacts. Use to identify B2B accounts.

hubspot_get_company — Retrieve the full company record including all properties, associated contacts, linked deals, and account owner. Use after hubspot_search_companies for complete details.

hubspot_get_contact_companies — List all companies associated with a specific contact. Useful when a contact is linked to multiple accounts or subsidiaries.

Deals & Pipeline (7 tools)

hubspot_get_deals — List all deals associated with a contact — shows pipeline stage, amount, and close date. Use to understand the contact's purchase history and active opportunities.

hubspot_search_deals — Find deals by name, stage, pipeline, or associated contact. Use when you need to search across deals rather than retrieve for one contact.

hubspot_get_deal — Retrieve full deal record: amount, pipeline stage, close date, associated contacts, and deal owner. Use when the visitor references a specific deal.

hubspot_update_deal — Update a deal's stage, amount, close date, or owner based on conversation signals. Always confirm changes with the customer before executing.

hubspot_create_deal — Create a new deal in HubSpot and associate it with a contact and company. Use when a prospect expresses clear purchase intent.

hubspot_get_pipeline_stages — Retrieve the live list of pipeline stages for a given pipeline. Always call this before creating or updating a deal so stage names match exactly what HubSpot expects.

hubspot_create_quote — Generate a HubSpot quote linked to a deal and return a shareable link. Send the link in chat to let prospects review and accept pricing without leaving the conversation.

Tickets & Support (5 tools)

hubspot_create_ticket — Create a HubSpot Service Hub support ticket linked to the contact and conversation. Captures subject, description, and priority.

hubspot_get_ticket — Retrieve a support ticket by ID — status, priority, pipeline stage, and description. Use when the visitor asks about an existing ticket.

hubspot_get_contact_tickets — List all support tickets associated with a contact. Use to check for existing open tickets before creating a new one — avoids duplicates.

hubspot_search_tickets — Find tickets by subject, status, priority, or pipeline stage. Use for broader ticket searches not tied to a single contact.

hubspot_update_ticket — Update a ticket's status, priority, owner, or pipeline stage. Use when a ticket is resolved during the conversation or needs reassignment.

Tasks (2 tools)

hubspot_get_contact_tasks — Retrieve open and completed tasks associated with a contact. Use to understand what follow-up actions are already scheduled.

hubspot_create_task — Create a follow-up task in HubSpot — assigned to an owner with due date and subject. Use to schedule sales or support follow-ups without leaving the conversation.

Engagement & Team (7 tools)

hubspot_add_note — Attach a note (conversation summary, key details, or full transcript) to a contact's activity timeline. Call this after every interaction.

hubspot_get_contact_timeline — Retrieve recent engagements on a contact — emails, calls, meetings, and notes. Use to understand conversation history before responding.

hubspot_get_owners — List HubSpot users (owners/reps) with their IDs. Use to assign contacts, deals, or tickets to the right person, or to route a chat to a specific rep.

hubspot_create_engagement — Create an engagement record (call or meeting) on a contact to log conversation activity in the HubSpot timeline.

hubspot_enroll_sequence — Enroll a contact in a HubSpot email sequence for automated post-chat follow-up. Useful for nurturing leads or sending onboarding emails after a qualifying conversation.

hubspot_get_form_submissions — Retrieve the forms a contact has submitted (pricing requests, demo sign-ups, newsletter opt-ins). Use to personalize the conversation based on what the visitor has already expressed interest in.

hubspot_get_meetings — List upcoming and past meetings associated with a contact. Use to reference prior touchpoints and avoid asking for context the visitor has already provided.

Conversation Sidebar Panel

When an agent opens a conversation, Velaro automatically looks up the visitor by email or phone in HubSpot and shows a live panel in the right sidebar.

What the panel shows:

• Contact card — name, company, lifecycle stage, phone, and email from the matching HubSpot Contact record
• Tickets tab — all open HubSpot Service Hub support tickets linked to the contact, with ticket subject, pipeline stage, and priority. Requires a HubSpot Service Hub CRM seat. The tab auto-hides if no tickets exist — no empty state shown.
• Manual search — agents can search for any contact by name or email if the auto-lookup doesn't find a match.

Writing Instructions for Your AI Agent

Your AI agent works best with short, plain instructions. You do not need a long script. Cover these points and let the connected HubSpot skills do the rest:

• Role — say who the AI agent is and what it helps with, such as qualifying leads, answering account questions, or logging support requests.
• What it can look up — name the HubSpot areas it should use, such as contacts, accounts, deals, or cases.
• When to hand off — decide when a person should take over, such as a pricing negotiation, a complaint, or two attempts without a resolution.
• What it should never do — for example, sharing private account details or promising discounts or delivery dates.
• Tone and channel — keep replies short and friendly, and shorter still for text messages or phone calls.

Start simple, test it in the simulator, and add detail only where you see a gap.

Prompt Tips

Start with contact lookup: always call hubspot_search_contact or hubspot_get_contact_by_email first before calling any other tools. Most tools are more useful once you have the contact ID.

Check before creating: always use hubspot_get_contact_tickets or hubspot_get_deals before creating new records — avoids duplicates that frustrate customers and clutter the CRM.

Log every interaction: add hubspot_add_note to the end of every workflow. This keeps the HubSpot timeline complete and gives your sales/support team full context after every chat.

Assign to the right owner: use hubspot_get_owners to list available reps, then assign deals, tickets, or tasks to the right person based on territory, team, or workload.

Pipeline stage discipline: when creating deals, be specific about the stage name — it must match an existing stage in your HubSpot pipeline exactly. Ask the visitor qualifying questions to determine the right stage.

Escalation Rules

Escalate to a human agent immediately when:

• The visitor is angry, frustrated, or threatening escalation
• The issue involves a refund, billing dispute, or contractual matter
• The visitor asks to speak with a specific person
• The AI agent has called 3+ tools without resolving the issue
• The visitor's account shows a Critical or high-priority open ticket

Troubleshooting

Contact not found: ask for an alternative identifier (company name, phone number). If still not found, offer to create a new contact and confirm their details.

Deal not found: try hubspot_search_deals with the company name or broader search terms. If the deal doesn't exist, ask if they'd like to create one.

Tool returns empty results: the visitor may be in HubSpot under a different email or company name. Try hubspot_search_contacts with a name instead of email.

HubSpot connection error: if tools are failing, check Integrations → HubSpot to confirm the connection is still active. OAuth tokens expire — click Reconnect if needed.

Permissions error: some HubSpot portals restrict API access by role. Ensure the connected HubSpot account has Sales and Service Hub access.