Connect HubSpot

Summary

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 CRM. The assistant uses a verified email or phone only. It does not use an address the customer types in chat.

Who can do this

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.

Before you start

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

Steps

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 CRM 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. Do not look for a pipeline or stage field. New HubSpot tickets land on the first ticket pipeline and first stage in HubSpot. You cannot choose them here.
12. Select Add tool at the bottom. KonversAI saves the tool and opens it with the heading Edit tool.
13. 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 CRM 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.
14. 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.
15. 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.

FAQ

What does the HubSpot CRM tool do?

HubSpot CRM 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 CRM. 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?

Create a HubSpot private app as a HubSpot Super Admin, then paste its access token into Private app access token on the HubSpot CRM 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?

Select Validate and save on the Edit tool screen for HubSpot CRM 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?

Request end-user phone before HubSpot lookup? defaults to Require and validate on a new HubSpot CRM 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?

Contact properties to read loads HubSpot’s list after the HubSpot CRM 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?

The assistant withholds HubSpot contact details when more than one contact matches the verified phone or email. Open HubSpot CRM 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.

Can I choose which HubSpot ticket pipeline KonversAI uses?

No. There is no pipeline or stage field on the HubSpot CRM tool. Select Settings in the left sidebar of the KonversAI console, then select AI tools, then open HubSpot CRM. New tickets land on the first ticket pipeline and first stage in that HubSpot portal. If HubSpot has no ticket pipeline, ticket create fails. Create at least one ticket pipeline in HubSpot, then retry. (Note; This will be expanded in a later iteration. The plan is to let the agent decide what pipeline each ticket will land in.)

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