Hub

The HubSpot integration allows you to connect your Botpress chatbot with HubSpot, a leading CRM and marketing automation platform. With this integration, your chatbot can manage contacts, tickets, and more directly within HubSpot, enabling seamless automation of sales, marketing, and support workflows.

Configuration

To protect the sensitive data in your HubSpot workspace, this integration requires you to create and configure your own private HubSpot app. While we recognize this adds complexity to the setup process, it ensures your data remains secure. We're actively collaborating with HubSpot to streamline this into a one-click setup experience. In the meantime, please follow the steps below to manually configure the integration.

Manual configuration with a custom OAuth app

1. Install the integration in your bot and copy the webhook URL. This URL starts with https://webhook.botpress.cloud/.
2. From your HubSpot settings dashboard, navigate to Account Management > Integrations > Legacy Apps.
3. Create a new Legacy App and make it private.
4. Under the Scopes tab, please add the following scopes:
   • oauth
   • crm.objects.contacts.read
   • crm.objects.contacts.write
   • tickets
   • crm.objects.owners.read
   • crm.objects.companies.read
   • crm.objects.companies.write
   • crm.objects.leads.read
   • crm.objects.leads.write
   • crm.objects.deals.read
   • crm.objects.deals.write
5. Under the Webhooks tab, paste your webhook URL, set Event Throttling to 1, and click Create Subscription.
6. You may now optionally subscribe to webhook events. In the Create new webhook subscriptions dialog, enable expanded object support, then select the events you wish to subscribe to. Currently, the integration supports the following events:
   • Company Created
   • Company Deleted
   • Contact Created
   • Contact Deleted
   • Lead Created
   • Lead Deleted
   • Ticket Created
   • Ticket Deleted
7. You may now click the Create App button to create your Legacy App.
8. From your app's settings page, navigate to the Auth tab and copy the Access Token and Client Secret.
9. Paste the Access Token and Client Secret in Botpress, then save the integration's configuration.

Migrating from 4.x to 5.x

Version 5.x addresses issues that could cause your bot to crash during certain operations. The search actions (Search Contact, Search Deal, Search Lead) now have optional outputs — they return undefined instead of throwing an error when a resource is not found. Make sure to handle this in your bot’s logic to avoid unexpected behavior.

Migrating from 3.x to 4.x

Default properties

The default properties returned when searching for or retrieving a CRM object may have changed. If your bot relied on a property that is now missing, add the property's name to the properties input parameter of the get or search action for the relevant CRM object.

Unified output structure

• All actions now return the CRM object relevant to the action directly within the output schema, ensuring consistency across all action responses. If an object is updated, some properties may not appear in the output. For example, the createTicket action now returns an object with the following structure:

type CreateTicketOutput = {
  ticket: {
    id: string
    subject: string
    category: string
    description: string
    priority: string
    source: string
    properties: Record<string, string>
  }
}

Deal and Lead

• There are now dedicated input parameters for setting and updating the names of deals or leads. The name is also included as a dedicated property of the CRM object in the output.
• You can now specify properties to include in the output when searching for or retrieving a deal or lead.

Ticket

• The category, priority, and source input parameters can now accept any valid string that corresponds to a valid value in your HubSpot account.
• The linearTicketUrl input parameter has been removed, as it may not be a valid property in all HubSpot accounts. If your bot was setting this property, set it as an additional property in the property input parameter.