Skip to content

Connect HubSpot

Connect HubSpot so your KonversAI assistant can look up a customer in HubSpot and create a support ticket. You do this on the Assistant tools screen in the KonversAI console. Select Settings in the left sidebar, then select AI tools. Add a tool of type HubSpot. The assistant uses a verified email or phone only. It does not use an address the customer types in chat.

A team member with the View tools permission opens the Assistant tools screen in the KonversAI console. A team member with the Modify tools permission adds, edits, validates and deletes. A Tenant Admin holds both permissions, always. Without View tools, the item AI tools does not appear under Settings in the left sidebar. Ask a Tenant Admin to grant Modify tools on the User permissions screen.

Sign in to the KonversAI console and select your tenant. Select Settings in the left sidebar, then select AI tools. The screen heading is Assistant tools.

You also need a HubSpot Super Admin and a HubSpot private app for the portal this tenant should use. Follow HubSpot’s private app instructions for HubSpot’s own screens. Copy the access token. Grant these three scopes on the private app:

  • crm.objects.contacts.read
  • crm.objects.contacts.write
  • tickets

Do not grant extra HubSpot scopes unless KonversAI asks you to. This tool does not use HubSpot custom objects or deals. Do not use a HubSpot marketplace or OAuth app install for this connection.

HubSpot is not behind a feature flag. Shared fields such as Display name, Slug and Usage guidance for the AI assistant work like any other tool. See Give the assistant a tool.

  1. Select Settings in the left sidebar of the KonversAI console, then select AI tools. The screen opens with the heading Assistant tools.
  2. Select + Add tool. The form opens with the heading Add tool.
  3. Select HubSpot in Tool type. You cannot change the type later.
  4. Type a label in Display name. KonversAI fills Slug while you type.
  5. Keep the Enabled checkbox selected.
  6. Open the Secrets card. Select Add secret on Private app access token. Type the token in Value, then select Apply. Treat the token like a password. Do not paste it into chat or a ticket.
  7. Check API base URL in the Configuration card. Leave https://api.hubapi.com unless the HubSpot portal needs the EU host https://api-eu1.hubapi.com.
  8. Set Request end-user email before HubSpot lookup? to Don’t mention or Require and validate. The default is Don’t mention.
  9. Set Request end-user phone before HubSpot lookup? to Don’t mention or Require and validate. The default is Require and validate. If both lists are Require and validate, the customer only needs to verify email or phone, not both.
  10. Optional: type Portal ID and Portal app base URL if operators should open the HubSpot record from the Contacts screen. Example hosts are https://app.hubspot.com and https://app-eu1.hubspot.com.
  11. Select Add tool at the bottom. KonversAI saves the tool and opens it with the heading Edit tool.
  12. Use Contact properties to read after the save. Until then the picker shows Save the tool first to select items from the external system. A new HubSpot tool starts with identity fields: email, first name, last name, phone and mobile phone. Search Available, add extra HubSpot properties this tenant needs, and keep those identity fields selected. HubSpot hides some internal fields from Available. Properties you already saved still show under Selected.
  13. Optional: in Tickets, add HubSpot ticket pipelines to Pipelines to create tickets in. The assistant picks the best matching pipeline for each ticket. Leave the list empty to use the first ticket pipeline in HubSpot. A new ticket always starts in the first stage of its pipeline.
  14. Optional: if you added two or more pipelines, choose Fallback pipeline. KonversAI uses this pipeline when the assistant is not sure which pipeline fits.
  15. Optional: in Tickets, choose Type property to give each ticket a type. The list shows the HubSpot ticket dropdown properties, such as Category or your own Type property.
  16. Optional: add the values the assistant may choose from to Types. The list shows the values of the Type property you chose. When none of them fit the conversation, KonversAI leaves the property empty on the ticket. A new Type property clears Types, so add the values again.
  17. Optional: in What each type means, describe which conversations belong to each type, in your own words. Example: Sales: someone considering buying or applying, asking about content, price or admission. The assistant follows the description when choosing a type. Add one when the type names alone are not enough, for example when questions before a purchase should count as sales.
  18. Optional: add Contact badges. Each entry is a HubSpot property name, or property:Label such as lifecyclestage:Lifecycle stage. Leave the list empty for a name-only Contacts view. A chip appears only when HubSpot has a value.
  19. Select Validate and save. Only the edit screen has this button. Success looks like: HubSpot settings are valid. Contact properties API reachable at https://api.hubapi.com (N properties on first page). The host and the count vary. Validate and save only checks that the token can read contacts. Ticket create can still fail if tickets or contact write is missing.

HubSpot is a tool type on the Assistant tools screen in the KonversAI console. Select Settings in the left sidebar, then select AI tools, then select + Add tool, and choose HubSpot. After a customer verifies email or phone, the assistant can look up that HubSpot contact and read the properties you selected. It can also create a HubSpot support ticket and hand the conversation over. The ticket text includes a conversation summary, the line Created via Konvers.ai, and a conversation link. The assistant does not change other HubSpot contact fields. It creates a HubSpot contact only when none matches, so the ticket can be linked.

Which HubSpot permissions does the private app need?

Section titled “Which HubSpot permissions does the private app need?”

Create a HubSpot private app as a HubSpot Super Admin, then paste its access token into Private app access token on the HubSpot tool in the KonversAI console. Select Settings in the left sidebar, then select AI tools, then open the tool. The private app needs crm.objects.contacts.read, crm.objects.contacts.write, and tickets. Follow HubSpot’s private app instructions for HubSpot’s screens. Do not grant custom-object scopes for this tool.

What do the Validate and save errors mean?

Section titled “What do the Validate and save errors mean?”

Select Validate and save on the Edit tool screen for HubSpot in the KonversAI console. Select Settings in the left sidebar, then select AI tools, then open the tool. Missing required settings: access_token means Private app access token is empty. Add the secret, then select Validate and save again. HubSpot connection check failed: the access token was rejected. Verify the HubSpot private app token and scopes (crm.objects.contacts.read is required; ticket create also needs ticket write + association scopes — not probed here yet). means HubSpot refused the token. Copy a new token from the private app, and confirm crm.objects.contacts.read. api_base_url must be a valid HTTP(S) URL. means API base URL is not an http:// or https:// address. Use https://api.hubapi.com or https://api-eu1.hubapi.com. Could not reach HubSpot (network timeout or connection error). means the host did not answer. Try the other API host, then retry. A green success banner can still hide a missing tickets scope. Ticket create then fails later. Add tickets and crm.objects.contacts.write on the private app, then retry.

Why does the assistant ask the customer to verify a phone number?

Section titled “Why does the assistant ask the customer to verify a phone number?”

Request end-user phone before HubSpot lookup? defaults to Require and validate on a new HubSpot tool. Open the tool from Settings, then AI tools, in the KonversAI console. The assistant then asks the customer to verify a phone number before a HubSpot lookup or ticket. Set the list to Don’t mention if this tenant should not ask for phone. If both email and phone are Require and validate, the customer only needs to verify one of them.

Why can I not pick contact properties until I save?

Section titled “Why can I not pick contact properties until I save?”

Contact properties to read loads HubSpot’s list after the HubSpot tool exists. Select Settings in the left sidebar of the KonversAI console, then select AI tools, then add the tool. The picker shows Save the tool first to select items from the external system. until you select Add tool. Then search Available and move properties to Selected. If Validate and save has not succeeded, the list can also fail to load. Save the token and API base URL first.

What happens when several HubSpot contacts match?

Section titled “What happens when several HubSpot contacts match?”

The assistant withholds HubSpot contact details when more than one contact matches the verified phone or email. Open HubSpot from Settings, then AI tools, in the KonversAI console, after you set the identity lists. The assistant asks the customer to verify the other channel. If several contacts still match, KonversAI does not attach a ticket to an arbitrary contact. Clean duplicate rows in HubSpot. Do not paste HubSpot contact records into the chat to pick one.

How does KonversAI choose the pipeline and type of a HubSpot ticket?

Section titled “How does KonversAI choose the pipeline and type of a HubSpot ticket?”

Open HubSpot from Settings, then AI tools, in the KonversAI console. The Tickets section on the Edit tool screen holds both choices. With pipelines in Pipelines to create tickets in, the assistant picks the pipeline that best matches the conversation. When the assistant is not sure, the ticket lands in Fallback pipeline. With an empty list, the ticket lands in the first ticket pipeline in HubSpot. A new ticket always starts in the first stage of its pipeline. With a Type property and Types chosen, the assistant also sets one of those types on the ticket. Describe the types in What each type means when the type names alone do not say which conversations belong where. When none of the types fit, KonversAI leaves the property empty. KonversAI still creates the ticket without a type if HubSpot cannot load the Type property, or refuses the type, for example because the value was removed in HubSpot. If HubSpot has no ticket pipeline, ticket create fails. Create at least one ticket pipeline in HubSpot, then retry.

Why does lookup still show name and email after I clear Contact properties to read?

Section titled “Why does lookup still show name and email after I clear Contact properties to read?”

An empty Contact properties to read list still uses the identity fields: email, first name, last name, phone and mobile phone. Open HubSpot from Settings, then AI tools, in the KonversAI console. That fallback is expected. Add extra HubSpot properties under Available if the assistant should read more than identity.

Last reviewed . Tell us when a step no longer matches the product.