HubSpot Inbox HITL Integration | Botpress Hub

HubSpot Inbox HITL

v2.0.0
Maintained by Botpress Growth Team

HubSpot Custom Channels HITL (Human-in-the-Loop) Integration

This integration enables Botpress to escalate conversations from a chatbot to a live agent in a HubSpot Inbox via Custom Channels. It uses the HubSpot Custom Channels API to create, send, and manage HITL (Human-in-the-Loop) conversations and agent interactions.

Note: This integration requires one of the following products or higher.

HubSpot Sales Hub - Enterprise

HubSpot Service Hub - Enterprise

Escalate to Human - Phone Number Requirement

To successfully trigger HITL's "Escalate to a Human" card, you must pass a valid phone number including the country code into the "User Email" field.

⚠️ This phone number must match the number of an existing contact in HubSpot. If there’s no match, the escalation will not work.

How It Works

Conversation Start

  • When a user requests live agent support, the bot:
  • Calls HubSpot’s Custom Channels API to start a new conversation thread.
  • Registers the custom channel and sends the initial "Name, title, description" message.

Message Handling

  • All subsequent user messages are:
  • Sent to HubSpot as INCOMING messages through the Custom Channels API.
  • Routed to the appropriate inbox and agent in the HubSpot Conversations UI.

Operator Events Tracking

The integration listens for HubSpot webhook events, including:

  • operatorAssignedUpdate: Fires when an agent joins the thread.
  • operatorSendMessage: Captures replies sent by the agent.
  • operatorConversationCompleted: Fires when the conversation is closed by the agent.

These events are handled in the src/events/ directory and forwarded to Botpress via custom events like hitlAssigned and hitlStopped.

Closing Conversations

  • When an agent marks a conversation as complete, Botpress:
  • Recognizes the event via webhook.
  • Terminates the HITL session and notifies the bot.

HubSpot Inbox HITL Integration Setup Guide

This guide walks you through connecting your HubSpot Inbox with Botpress using OAuth for Human-in-the-Loop functionality.

Loom video walk through setting up the OAuth configuration.

1. Create a HubSpot Developer Account

2. Create a Public App

  • Navigate to Apps > Create app
  • Set the Redirect URL to your Botpress webhook URL
    Example: https://your-botpress-url.com/api/v1/webhooks/hubspot

3. Generate Your Developer API Key

  • In your developer portal, go to Keys
  • Generate a developer_api_key

4. Configure Your App Credentials in Botpress

In your Botpress integration config, paste the following values:

  • developer_api_key
  • app ID
  • client ID
  • client secret

5. Retrieve Your Inbox ID

  • In HubSpot, go to:
    CRMInboxInbox Settings
  • Copy your Inbox ID from the URL:
    Example:
    https://app-na3.hubspot.com/live-messages-settings/341662569/inboxes/1263703960/channels
    Here, the Inbox ID is: 1263703960
  • Paste this Inbox ID into your Botpress integration config.

6. Set App Scopes and Webhook

  • In your public app settings, set the Scopes to:
  conversations.custom_channels.read
  conversations.custom_channels.write
  conversations.read
  conversations.visitor_identification.tokens.create
  conversations.write
  crm.objects.contacts.read
  • Under Webhooks, set the Target URL to your Botpress webhook URL.

7. Subscribe to Webhook Events

Create webhook subscriptions for the following events:

  • conversations.newMessage
  • conversation.propertyChange (AssignedTo, Status)

Get Your OAuth Refresh Token

1. Get the Authorization Code

Open the following URL in your browser (replace values accordingly):

https://app.hubspot.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=conversations.custom_channels.read%20conversations.custom_channels.write%20conversations.read%20conversations.visitor_identification.tokens.create%20conversations.write%20crm.objects.contacts.read&response_type=code

2. Exchange the Code for Tokens

Use the following cURL request to get your tokens:

curl -X POST https://api.hubapi.com/oauth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=YOUR_BOTPRESS_WEBHOOK_URL" \
  -d "code=YOUR_AUTHORIZATION_CODE"

You’ll receive:

  • access_token
  • refresh_token
  • expires_in

Save your refresh_token in your Botpress integration settings.

⚠️ Note: After saving your final integration configuration in Botpress, it may take over a minute for the HubSpot channel to connect. Do not refresh or close the page during this time.


You're All Set!

Your HubSpot inbox is now connected to Botpress HITL via OAuth. You should now be able to receive and respond to conversations within Botpress.