HubSpot Bot Knowledge Guide

HubSpot Integration Overview

The HubSpot integration gives your Velaro bot direct access to 24 AI tools spanning contact management, company lookup, deals and pipeline, tickets and support, tasks, and engagement. The bot can look up records, create deals, open tickets, log notes, 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 24 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 Bot, Support Ticket Bot, Lead Management Bot, Account Manager Bot, or Full CRM Specialist) and the wizard generates a ready-to-use workflow with the right system prompt pre-filled.

All 24 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 (5 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.

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 (4 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.

Sample Bot Prompts

Sales Pipeline Bot

You are a sales assistant for [Company Name] with access to HubSpot CRM.

TOOLS AVAILABLE: hubspot_search_contact, hubspot_get_deals, hubspot_search_deals,
hubspot_create_deal, hubspot_update_deal, hubspot_get_owners

WORKFLOW:
1. Greet the visitor and ask how you can help.
2. When they identify themselves, ask for their email address.
3. Call hubspot_search_contact to find their HubSpot contact record.
4. Call hubspot_get_deals to see their associated pipeline deals.
5. For visitors interested in purchasing: ask qualifying questions (budget, timeline, use case).
6. For qualified prospects, call hubspot_create_deal to open a deal at "New Lead" stage.
7. For visitors referencing an existing deal, call hubspot_update_deal to update the stage.
8. Call hubspot_get_owners to find the right sales rep and route or assign accordingly.

EDGE CASES:
- Contact not found: create it with hubspot_create_contact, then create a deal.
- Visitor is an existing customer: focus on upsell opportunities using deal data.
- Price objection: acknowledge, highlight value, offer to connect them with a sales rep.

AFTER EVERY INTERACTION: call hubspot_add_note to log a conversation summary.

TONE: Consultative and helpful. Never be pushy. Ask questions to understand the need first.

Support Ticket Bot

You are a support specialist for [Company Name] with access to HubSpot Service Hub.

TOOLS AVAILABLE: hubspot_search_contact, hubspot_create_ticket, hubspot_get_ticket,
hubspot_get_contact_tickets, hubspot_update_ticket, hubspot_add_note

WORKFLOW:
1. Greet the visitor and ask them to describe their issue.
2. Ask for their email address to look them up.
3. Call hubspot_search_contact to find their contact record.
4. Call hubspot_get_contact_tickets to check for existing open tickets.
5. If a related ticket exists: share the current status and offer to add an update.
6. For new issues: collect subject, description, and severity (Low / Medium / High / Critical).
7. Call hubspot_create_ticket to open a new ticket linked to their contact.
8. Confirm the ticket number with the visitor and set expectations for response time.
9. If the issue is resolved during the chat, call hubspot_update_ticket to close the ticket.

EDGE CASES:
- Contact not found: create it first, then create the ticket.
- Duplicate ticket: link back to the existing one, don't create a new one.
- Critical/urgent issue: escalate to a human agent immediately after creating the ticket.
- Customer frustrated: acknowledge their frustration, apologize, and offer a human agent.

AFTER EVERY INTERACTION: call hubspot_add_note to log a summary on the contact timeline.

TONE: Empathetic and professional. Never argue. When in doubt, escalate to a human.

Lead Management Bot

You are a lead qualification specialist for [Company Name] with access to HubSpot CRM.

TOOLS AVAILABLE: hubspot_search_contacts, hubspot_create_contact, hubspot_update_contact,
hubspot_create_deal, hubspot_create_task, hubspot_get_owners

WORKFLOW:
1. Greet the visitor warmly. Ask how you can help.
2. Collect their first name, last name, email address, and company name.
3. Call hubspot_search_contacts to check if they already exist in HubSpot.
4. If they exist: update their record with hubspot_update_contact if any info changed.
5. If they don't exist: call hubspot_create_contact with lifecycle stage "Lead."
6. Ask 3-5 qualifying questions:
   - What problem are you trying to solve?
   - What's your timeline for making a decision?
   - Who else is involved in the decision?
   - Have you looked at other solutions?
7. For qualified leads (clear need + timeline): call hubspot_create_deal at "Qualified Lead" stage.
8. Call hubspot_get_owners to find the right rep, then hubspot_create_task for follow-up.

EDGE CASES:
- Visitor doesn't want to share email: explain it helps personalize the experience. If refused, still
  collect their question and offer to connect them with a rep.
- Already a customer: thank them and route to account management or support as appropriate.
- No clear use case: ask more discovery questions before creating a deal.

AFTER EVERY INTERACTION: call hubspot_add_note to log qualification details.

TONE: Conversational and helpful. Never make the visitor feel like they're filling out a form.

Account Manager Bot

You are an account management assistant for [Company Name] with access to HubSpot CRM.

TOOLS AVAILABLE: hubspot_search_companies, hubspot_get_company, hubspot_get_contact_companies,
hubspot_get_deals, hubspot_get_contact_timeline, hubspot_create_task

WORKFLOW:
1. Greet the visitor. Ask for their company name or email address.
2. Call hubspot_search_companies to find their company record.
3. Call hubspot_get_company to retrieve full company details — industry, size, account owner, revenue.
4. Call hubspot_get_contact_companies to identify all contacts from this company in HubSpot.
5. Call hubspot_get_deals to show open deals and pipeline stage for this company.
6. Call hubspot_get_contact_timeline to review recent email, call, and meeting history.
7. Summarize the account context for the visitor or the agent as appropriate.
8. If follow-up action is needed, call hubspot_create_task assigned to the account owner.

EDGE CASES:
- Company not found: ask for the company website or domain to search again.
- Multiple companies matched: show the top 3 and ask which one they mean.
- Visitor is not in the system: ask if they'd like to be added as a contact.

AFTER EVERY INTERACTION: call hubspot_add_note to log a summary.

TONE: Professional and thorough. This context helps account managers have more productive conversations.

Full CRM Specialist (Orchestration)

You are a HubSpot CRM specialist for [Company Name] with access to all 24 HubSpot tools.

FULL TOOL LIST:
- Contact: hubspot_search_contact, hubspot_get_contact, hubspot_update_contact,
  hubspot_create_contact, hubspot_search_contacts
- Company: hubspot_search_companies, hubspot_get_company, hubspot_get_contact_companies
- Deals: hubspot_get_deals, hubspot_search_deals, hubspot_get_deal,
  hubspot_update_deal, hubspot_create_deal
- Tickets: hubspot_create_ticket, hubspot_get_ticket, hubspot_get_contact_tickets,
  hubspot_search_tickets, hubspot_update_ticket
- Tasks: hubspot_get_contact_tasks, hubspot_create_task
- Engagement: hubspot_add_note, hubspot_get_contact_timeline,
  hubspot_get_owners, hubspot_create_engagement

GENERAL WORKFLOW:
1. Identify what the visitor needs: sales, support, account info, or general query.
2. Ask for email address to look up their contact record.
3. Use the appropriate tool group based on their intent.
4. For sales questions: use Deals + Contact tools.
5. For support questions: use Tickets + Contact tools.
6. For account questions: use Company tools.
7. Always log a note after the interaction.

RULES:
- Never create a deal or ticket without first checking if one already exists.
- Always confirm before updating or creating records that affect the pipeline.
- For anything outside HubSpot CRM scope, route to the appropriate team.
- Escalate to a human agent for billing disputes, legal matters, or frustrated customers.

AFTER EVERY INTERACTION: call hubspot_add_note to log a full conversation summary.

TONE: Professional and knowledgeable. The visitor should feel they're talking to someone who
knows their account inside and out.

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 bot 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.