Platform
Mga tampok
Ahente Studio
Buuin at i-customize ang iyong ahente nang mabilis
Autonomous Engine
Gamitin LLMs upang gabayan ang mga pag-uusap at gawain
Mga Batayan ng Kaalaman
Sanayin ang iyong bot gamit ang mga custom na mapagkukunan ng kaalaman
Mga mesa
I-store at pamahalaan ang data ng pag-uusap
Mga channel
Whatsapp Emblem
WhatsApp
Instagram Emblem
Instagram
Facebook Messenger logo
Messenger
Slack logo
Slack
Lahat ng channel
Mga pagsasama
Logo ng Hubspot
HubSpot
Notion logo
Notion
Logo ni Jira
Jira
Calendly logo
Calendly
Lahat ng pagsasama
LLM Mga provider
OpenAI logo
OpenAI
Anthropic logo
Anthropic
Groq logo
Groq
HuggingFace logo
Hugging Face
Lahat LLMs
Mga solusyon
Para sa
Enterprise
I-automate ang mga mission-critical production workflow
Mga ahensya
Magbigay ng mga sopistikadong serbisyo ng ahente
Mga developer
Galugarin ang isang matatag na API para sa pagbuo ng ahente
Mga Kwento ng Customer
Tuklasin mula sa matagumpay na mga customer kung paano Botpress ay nagbabago ng negosyo sa buong mundo.
Sa pamamagitan ng Industriya
Ecommerce
Edukasyon
Pananalapi
Hospitality
Lahat ng industriya
Sa pamamagitan ng Kagawaran
Benta
Engineering
produkto
ITSM
Lahat ng departamento
Sa pamamagitan ng Use Case
Shopping Assistant
Lead Generation
Karanasan ng Empleyado
Pamamahala ng Ticket
Lahat ng use case
Mga mapagkukunan
Mahalaga
Academy
Matutong bumuo sa pamamagitan ng mga curated na kurso
Library
Mga mapagkukunan upang mapahusay ang iyong mga daloy ng trabaho sa AI
Blog
Mga insight at update sa Botpress at mga ahente ng AI
gusali
Discord
Sumali sa libu-libong mga kapantay at magbahagi ng mga ideya
Docs
Mga komprehensibong gabay at sanggunian
API
Sangguniang materyal para sa paggamit sa mga panlabas na sistema
LLM Pagraranggo
Ihambing ang pagganap at gastos para sa mga provider ng modelo
Mga video
Mga tutorial, demo, at walkthrough ng produkto
Changelog
Manatiling up-to-date sa pinakabago Botpress mga update
Mga kasosyo
Maging Kasosyo
Sumali sa aming network ng mga sertipikadong eksperto
Mag-hire ng Expert
Kumonekta sa mga kasosyo at consultant
Docs
Enterprise
Pagpepresyo
Mag log in
Makipag-ugnayanMag-sign up
balik sa Hub

HubSpot Inbox HITL

v5.0.1
I-install sa iyong Workspace
Pinapanatili ng 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.](https://www.loom.com/share/4f1671cfd4fd4063b5e8570830100a44?sid=a22987f8-858b-4ef2-a879-ccac762fb6aa)** ###


### 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. Retrieve Your Inbox ID
- In HubSpot, go to:  
  **CRM** → **Inbox** → **Inbox 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):
```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.

> ⚠️ **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.

Bumuo ng Mas mahusay na may Botpress

Gumawa ng mga kamangha-manghang karanasan sa ahente ng AI.

Magsimula - libre ito
Icon ng isang arrow
Matuto pa sa Botpress Academy

Bumuo ng mga ahente ng AI nang mas mahusay at mas mabilis gamit ang aming na-curate na koleksyon ng mga kurso, gabay, at tutorial.

Mag-hire ng Expert

Kumonekta sa aming mga sertipikadong developer para makahanap ng ekspertong tagabuo na nababagay sa iyong mga pangangailangan.

Lahat ng System Operational
SOC 2
Certified
GDPR
Sumusunod
© 2025
Platform
Pagpepresyo
Ahente Studio
Autonomous Engine
Mga Batayan ng Kaalaman
Mga mesa
Hub
Mga pagsasama
Mga channel
LLMs
Mga mapagkukunan
Makipag-usap sa Sales
Dokumentasyon
Mag-hire ng Expert
Mga video
Mga Kwento ng Customer
Sanggunian ng API
Blog
Katayuan
v12 Mga Mapagkukunan
Komunidad
Suporta sa Komunidad
Maging Kasosyo
Maging Ambassador
Maging isang Affiliate
kumpanya
Tungkol sa
Mga karera
Balita at Press
Legal
Pagkapribado
© Botpress 2025