HubSpot Integration

What the AI can do

Summary

HubSpot Integration connects HubSpot Meetings + CRM with Newo Platform.

It currently supports:

• checking appointment availability from a HubSpot meeting link
• creating bookings with contact lookup / contact creation in HubSpot CRM
• cancelling existing meetings by exact booking datetime
• existing customer lookup by phone/email with prompt injection
• storing upcoming bookings in persona data
• optional outbound conversation note sync after phone sessions
• optional default canvas seeding for booking and cancellation scenarios

This integration is designed for service businesses and sales teams that use a single HubSpot meeting link and want an AI agent to handle appointment availability, booking, and cancellation through chat or voice.

Common use cases

• When a customer asks about available times -> the agent checks HubSpot meeting-link availability and returns free slots
• When a customer wants to book an appointment -> the agent finds or creates a HubSpot contact and submits the booking
• When a customer wants to cancel an appointment -> the agent finds the matching HubSpot meeting by start time and deletes it
• When the platform detects a caller's phone number -> the integration looks up the existing HubSpot contact and injects customer context
• When a future meeting exists for that contact -> the integration stores it in persona bookings
• When an outbound phone session ends -> the integration can write a HubSpot note with transcript/summary

Features at a glance

Feature	Supported	Notes
Check Availability	✅	Uses HubSpot meeting-link booking endpoint
Book Appointment	✅	Searches contact by email, creates contact if missing, then books
Cancel Appointment	✅	Finds meeting by exact start datetime, then deletes it
Existing Client Detection	✅	Searches HubSpot contacts by phone/email
Existing Booking Storage	✅	Saves future meetings into persona bookings
Silent Availability Preload	✅	session_started can trigger a silent availability check
Outbound Conversation Note Sync	✅	Only for Outgoing Phone sessions and when enabled
Canvas Auto Setup	✅	Seeds default booking/cancellation scenarios when enabled
Multi-Calendar / Multi-Slug	❌	Single hubspot_slug_name
Native Reschedule Flow	❌	Use cancel + rebook flow
Deal / Pipeline Automation	❌	Not implemented in current agent flows

Before You Start

Before setup:

• active HubSpot account
• HubSpot Meetings enabled
• one working meeting link slug
• either:
  • one OAuth authorization code from the Newo-provided HubSpot auth link
  • or one HubSpot Service Key (PAT-style token) with the scopes your booking flows require
• correct business timezone

Current setup supports two authentication modes:

• OAuth
• Token

Setup

Create the Newo project

If this project already exists in Newo Builder, skip this subsection and continue with the integration-specific settings below.

1. In Newo Builder, open the projects list and click Create Project (or Create New Project from the top-right menu).

2. Fill IDN and Title. The exact names do not matter; use any clear names your team will recognize.
3. In Registry, choose the release channel:
   • staging — the newest module fixes appear here first. Use it when you need the latest fix, but expect possible unfinished changes.
   • production — the final stable version for live projects.
4. In Module, select the module for this integration.

5. Leave Module version on Latest version unless support tells you to pin a specific version, then click Create.

3.1 Step 1 — Choose Authentication Method

Set hubspot_auth_type to one of:

• OAuth
• Token

3.2 OAuth Setup

If you use OAuth:

1. Open the authorization link from the hubspot_oauth_code attribute description in Newo.
2. Approve access in HubSpot.
3. Copy the returned OAuth code.
4. Paste it into hubspot_oauth_code.

During setup, the integration uses that code when creating the HubSpot connector and then also triggers the connector's authorization_code action.

3.3 Token Setup

1. Open HubSpot.
2. Go to Settings > Integrations > Service Keys.
3. Create a new key with the CRM / Meetings permissions your flow needs.
4. Copy the generated token.

3.4 Step 2 — Find the Meeting Link Slug

Example:

• full link: https://meetings-eu1.hubspot.com/test-meetings-page
• slug: test-meetings-page

Put only the last path segment into hubspot_slug_name.

3.5 Step 3 — Configure Attributes in Newo

Open Newo -> Projects -> Builder / Attributes and set:

Attribute	Required	Description
hubspot_auth_type	✅	OAuth or Token
hubspot_oauth_code	Required for OAuth	One-time OAuth code copied from the HubSpot authorization page
hubspot_service_key	Required for Token	HubSpot Service Key / PAT
hubspot_slug_name	✅	HubSpot meeting link slug
hubspot_base_api_url	❌	Defaults to https://api.hubapi.com
hubspot_timezone	❌	Defaults to project business timezone
hubspot_duration	❌	Slot length in minutes, default 30
hubspot_show_for_days	❌	Search window in days, default 1
hubspot_slots_available	❌	Enable / disable availability flow
hubspot_booking_available	❌	Enable / disable booking flow
hubspot_cancelation_available	❌	Enable / disable cancellation flow
hubspot_sync_conversation	❌	Enable / disable outbound phone note sync
hubspot_setup_scenarios	❌	Auto-add default booking/cancellation scenarios to canvas

Hidden/system attributes are managed by setup automatically, for example:

• hubspot_override_agent_attributes
• setup_persona_id

3.6 Step 4 — Publish

On publish, the current setup logic:

• syncs project attributes and tool-gating attributes
• injects booking and availability payload schemas
• ensures both api and http connector entries exist for hubspot_connector
• creates / reuses the setup persona
• validates the HubSpot connection with: the lookup request

Operational note:

• OAuth requests use the api connector path
• Token requests use the http connector path with Authorization: Bearer <hubspot_service_key>

If hubspot_setup_scenarios = True, the integration also participates in workflow-builder canvas setup during canvas setup.

4. How It Works

4.4 Overall Sequence

5. Canvas Setup

canvas setup exists and auto-runs on:

• gm_workflow_builder_canvas_built

Current behavior:

• SetupLibrarySkill seeds custom hubspot_* intents and scenarios into the library
• Publish All adds common appointment and cancellation items to the active canvas
• auto-setup is controlled by visible attribute: hubspot_setup_scenarios

How to test that everything works

6.1 Conversation Testing

Recommended live checks:

1. publish the integration
2. verify setup validation succeeds
3. ask for availability on a concrete date/time
4. book a new customer with email + phone
5. cancel by exact appointment datetime
6. test existing-client lookup by known phone number

6.2 Webhook Test Events

The integration also exposes test hooks for direct flow testing:

Event	Flow	Purpose
availability_wh	AvailabilityFlow	Trigger availability test payload
book_wh	BookingFlow	Trigger booking test payload
cancel_wh	CancellationFlow	Trigger cancellation test payload

6.3 What to Verify

• SetupFlow: token validation request succeeds
• Canvas setup: default items are added when hubspot_setup_scenarios=True
• AvailabilityFlow: returned slots match the current meeting-link behavior
• BookingFlow: contact search/create works and booking endpoint accepts the chosen time
• CancellationFlow: meeting search finds the correct meeting and delete succeeds
• ExistingClientFlow: ExistingCustomerInfo appears and future bookings are stored

6.4 Troubleshooting

If setup fails:

• if using OAuth, confirm hubspot_oauth_code was pasted correctly and connector authorization completed
• if using Token, confirm hubspot_service_key is valid
• confirm the OAuth app / token has the scopes needed by your booking flows
• confirm hubspot_base_api_url is correct

If availability works but booking fails:

• verify the chosen time is still valid for the meeting link
• verify timezone alignment between hubspot_timezone, user request, and HubSpot meeting settings
• note that the current implementation computes free slots from allUsersBusyTimes; HubSpot may still reject a time if it does not fit the meeting link's live availability settings

If existing-client lookup does nothing:

• confirm the incoming phone number/email matches a HubSpot contact
• confirm the contact has future meetings associated to it

If outbound note sync does nothing:

• confirm hubspot_sync_conversation=True
• confirm the session channel is exactly Outgoing Phone

FAQ

Q: What authentication method does the current setup use?
A: The current setup supports both OAuth and Token through hubspot_auth_type.

Q: What does OAuth mode require from the user?
A: In the current implementation, the user opens the auth link from hubspot_oauth_code, approves HubSpot access, copies the returned code, and pastes it into hubspot_oauth_code.

Q: Does the current runtime use api or http routing?
A: OAuth uses the api path. Token uses the http path with a bearer token header.

Q: How are contacts matched during booking?
A: Booking first searches HubSpot contacts by email. If no contact is found, a new contact is created.

Q: How does cancellation identify the meeting to delete?
A: It converts the requested local datetime to UTC, searches meetings by exact hs_meeting_start_time, then deletes the found meeting ID.

Q: What customer context is injected into the prompt?
A: ExistingClientFlow injects ExistingCustomerInfo role="context" and stores future meetings in persona bookings.

Q: Why can availability say a slot is open but booking still fail?
A: The current availability logic derives free slots from allUsersBusyTimes. HubSpot booking still validates the submitted startTime against its own live meeting-link availability settings.

Q: Can I disable the default canvas scenarios?
A: Yes. Set hubspot_setup_scenarios to False.

Q: What is the meeting slug?
A: It is the last path segment of your HubSpot meeting link, stored in hubspot_slug_name.