HubSpot Help Desk HITL Integration

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 Help Desk via Custom Channels. It uses the HubSpot Custom Channels API to create, send, and manage HITL (Human-in-the-Loop) conversations and agent interactions. Both email address and phone number are supported as inputs, however the contact has to be created in the HubSpot CRM with the respective email/phone number.

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 Help Desk 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 Help Desk HITL Integration Setup Guide

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

1. Create a HubSpot Developer Account

Go to HubSpot Developer and sign up or log in.

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

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

3. Retrieve Your Help Desk ID

Run the following curl command to fetch all inboxes/help desks from HubSpot:

curl --request GET \
  --url https://api.hubapi.com/conversations/v3/conversations/inboxes \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN'

Look for the id field associated with "type": "HELP_DESK" in the response. This is your Help Desk (Inbox) ID.

Example Response:

{
  "total": 2,
  "results": [
    {
      "id": "1431487392",
      "name": "Inbox",
      "createdAt": "2025-05-16T03:42:04.565Z",
      "updatedAt": "2025-05-16T03:42:04.565Z",
      "type": "INBOX",
      "archived": false
    },
    {
      "id": "1431487401",
      "name": "Help Desk",
      "createdAt": "2025-05-16T03:42:05.461Z",
      "updatedAt": "2025-05-16T03:42:05.461Z",
      "type": "HELP_DESK",
      "archived": false
    }
  ]
}

In this example, the Help Desk ID is: 1431487401

Paste this Help Desk ID into your Botpress integration config.

⚠️ 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 Help Desk is now connected to Botpress HITL via OAuth. You should now be able to receive and respond to conversations within Botpress.

# 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 Help Desk via Custom Channels. It uses the HubSpot Custom Channels API to create, send, and manage HITL (Human-in-the-Loop) conversations and agent interactions. Both email address and phone number are supported as inputs, however the contact has to be created in the HubSpot CRM with the respective email/phone number. ## 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 Help Desk 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 Help Desk HITL Integration Setup Guide This guide walks you through connecting your HubSpot Help Desk with Botpress using OAuth for Human-in-the-Loop functionality. ### 1. Create a HubSpot Developer Account - Go to [HubSpot Developer](https://developers.hubspot.com/) and sign up or log in. ### 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. 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. ### 6. 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): ```bash 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: ```bash 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. ### 3. Retrieve Your Help Desk ID Run the following `curl` command to fetch all inboxes/help desks from HubSpot: ```bash curl --request GET \ --url https://api.hubapi.com/conversations/v3/conversations/inboxes \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' ``` Look for the `id` field associated with `"type": "HELP_DESK"` in the response. This is your Help Desk (Inbox) ID. #### Example Response: ```json { "total": 2, "results": [ { "id": "1431487392", "name": "Inbox", "createdAt": "2025-05-16T03:42:04.565Z", "updatedAt": "2025-05-16T03:42:04.565Z", "type": "INBOX", "archived": false }, { "id": "1431487401", "name": "Help Desk", "createdAt": "2025-05-16T03:42:05.461Z", "updatedAt": "2025-05-16T03:42:05.461Z", "type": "HELP_DESK", "archived": false } ] } ``` In this example, the Help Desk ID is: `1431487401` Paste this Help Desk ID into your Botpress integration config. > ⚠️ **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 Help Desk is now connected to Botpress HITL via OAuth. You should now be able to receive and respond to conversations within Botpress.

HubSpot Help Desk HITL