The HubSpot integration connects your Newo.ai AI Employee with HubSpot CRM to automate appointment scheduling and contact management. Once connected, the AI Employee can check real-time availability, book and cancel appointments, detect existing contacts, and automatically inject customer context into the agent — all powered by HubSpot Meeting Links and the Contacts API.

Requirements

Before setting up the integration, make sure you have:

An active HubSpot account with Meeting Scheduler enabled
A HubSpot OAuth App with a Client ID and Client Secret
A Meeting Link slug — the URL path of your meeting link (e.g., john-doe from meetings.hubspot.com/john-doe)
An OAuth Redirect URL registered in your HubSpot OAuth App

Step 1: Authorize HubSpot

In the Newo.ai Builder, go to Attributes and set hubspot_client_id, hubspot_client_secret, and hubspot_redirect_url.
Click the HubSpot authorization link provided by the platform.
Log in to your HubSpot account.
Authorize the Newo app and grant the requested scopes.
Copy the authorization code from the redirect URL.
Paste the code into the hubspot_oauth_code attribute.

🗒️ NOTE

The OAuth authorization code is single-use and expires quickly. If the code expires before you publish, repeat the authorization flow to generate a new one.

Step 2: Configure attributes

Set these attributes in the Builder under Attributes, then click Save + Publish All.

Required attributes

Attribute	Description
`hubspot_client_id`	OAuth App Client ID.
`hubspot_client_secret`	OAuth App Client Secret.
`hubspot_redirect_url`	OAuth redirect URL registered in your HubSpot app.
`hubspot_oauth_code`	One-time OAuth authorization code obtained from the authorization flow.
`hubspot_slug_name`	Meeting link URL slug (e.g., `john-doe`). Determines which calendar is used for availability and booking.

Optional attributes

Attribute	Description	Default
`hubspot_base_api_url`	HubSpot API base URL.	`https://api.hubapi.com`
`hubspot_timezone`	Timezone for appointments.	Project timezone
`hubspot_duration`	Slot duration in minutes.	`30`
`hubspot_show_for_days`	Number of days ahead to check for available slots.	`1`
`hubspot_slots_available`	Enable availability checking.	`True`
`hubspot_booking_available`	Enable appointment booking.	`True`
`hubspot_cancelation_available`	Enable appointment cancellation.	`True`

On publish, the platform automatically:

Exchanges the OAuth code for access and refresh tokens
Validates token persistence via a test API call
Creates HTTP connectors for the HubSpot API
Injects booking and availability payload schemas for the AI Employee

What is the meeting link slug?

The slug is the URL path of your HubSpot meeting link. For example, if your meeting link is meetings.hubspot.com/john-doe, the slug is john-doe. Set it in hubspot_slug_name — the integration uses this slug to determine which calendar's busy times to query for availability and which calendar to book against.

What the integration does

The integration handles scheduling and contact management through an event-driven system. When the AI Employee detects certain conversation signals, it triggers the corresponding HubSpot action automatically.

Appointment scheduling

Check availability: The AI Employee queries the meeting link's busy times and returns open time slots when a caller asks about availability. Slot duration is configurable via hubspot_duration.
Book appointment: The AI Employee searches HubSpot contacts by email. If a match is found, the existing contact is used. If not, a new contact is created with name, phone, and email. The meeting is then created and linked to the contact.
Cancel appointment: The AI Employee searches HubSpot meetings by exact start time, then deletes the matching meeting from HubSpot CRM.

🗒️ NOTE

Rescheduling is not directly supported. To reschedule, cancel the existing appointment and book a new one.

Customer context

When a caller's phone number is identified, the integration looks up the matching HubSpot contact and automatically injects their name, email, and upcoming bookings into the agent's prompt. This gives the AI Employee full context before the conversation begins, enabling personalized interactions without the caller having to repeat their information.

At session start, the integration can also silently pre-load availability in the background so the AI Employee is ready to suggest open slots immediately.

Test the integration

Test through the Newo conversation interface (chat or voice channel).

Verify setup

Publish the project and confirm the OAuth token exchange succeeded — check that hubspot_access_token is not empty after publishing.

Existing client detection

Start a conversation from a phone number associated with a known HubSpot contact. Verify that the AI Employee greets the caller by name and has their context pre-loaded in the prompt.

Check availability

Ask: "What slots are available tomorrow?" Verify that the AI Employee returns free time slots calculated from your meeting link's schedule.

Book an appointment

Complete a booking conversation. Verify in HubSpot that:

A contact was created or matched by email.
A meeting was created with the correct date, time, and contact link.

Cancel an appointment

Ask the AI Employee to cancel an existing appointment. Verify the meeting is removed from HubSpot CRM.

⚠️ CAUTION

This integration performs real operations in HubSpot. Contacts and meetings created or deleted through the AI Employee are reflected in the live CRM system.

Troubleshooting

If the integration isn't working as expected:

Missing OAuth credentials: Ensure hubspot_client_id and hubspot_client_secret are set correctly.
Token not obtained: Verify hubspot_access_token is not empty after setup — an empty token indicates the OAuth exchange failed.
Invalid slug: Confirm hubspot_slug_name matches an existing meeting link slug in your HubSpot account.
Feature flags disabled: Check that hubspot_slots_available, hubspot_booking_available, and hubspot_cancelation_available are set to True.
Wrong timezone: Verify hubspot_timezone is set correctly, or clear it to fall back to the project timezone.
Credential changes: Re-publish the project any time credentials are updated.

FAQ

Q: Does the integration import historical HubSpot data?

No. Only meetings created after the integration is activated are managed. Existing client detection retrieves upcoming future meetings for context only — it does not import or manage past records.

Q: Can I connect multiple HubSpot accounts?

Each integration instance supports one HubSpot account and meeting link. To connect multiple accounts or meeting links, create separate integration instances.

Q: How does availability checking work?

The integration queries the HubSpot meeting link's busy times and generates free slots by finding gaps. Slot duration is configurable via hubspot_duration (default: 30 minutes).

Q: What happens if a contact already exists in HubSpot?

The integration searches contacts by email. If a match is found, the existing contact is used for booking. If no match is found, a new contact is created with the caller's name, phone, and email.

Q: How does cancellation find the right meeting?

Cancellation searches HubSpot meetings by exact start time. The meeting ID from the search result is then used to delete the meeting.

Q: What happens if the OAuth token expires?

The integration automatically detects HTTP 401 responses and refreshes the token using the stored refresh token. It retries the failed request up to three times before surfacing an error.

Q: Can the slot duration vary per booking?

Yes. While the default slot duration is set via hubspot_duration, each individual booking request can include a duration override in the payload.

GoHighLevel integration