Platform
Ciri
Studio Ejen
Bina dan sesuaikan ejen anda dengan pantas
Enjin Autonomi
guna LLMs untuk membimbing perbualan dan tugasan
Pangkalan Pengetahuan
Latih bot anda dengan sumber pengetahuan tersuai
Jadual
Menyimpan dan menguruskan data perbualan
Saluran
Whatsapp Lambang
WhatsApp
Instagram Lambang
Instagram
Facebook Messenger logo
Messenger
Slack logo
Slack
Semua saluran
Integrasi
Logo Hubspot
HubSpot
Notion logo
Notion
Logo Jira
Jira
Calendly logo
Calendly
Semua integrasi
LLM Pembekal
OpenAI logo
OpenAI
Anthropic logo
Anthropic
Groq logo
Groq
Logo HuggingFace
Hugging Face
Semua LLMs
Penyelesaian
Bagi
Perusahaan
Automasi aliran kerja pengeluaran kritikal misi
Agensi
Menyediakan perkhidmatan ejen yang canggih
Pemaju
Terokai API yang teguh untuk pembangunan ejen
Cerita Pelanggan
Ketahui daripada pelanggan yang berjaya bagaimana Botpress mengubah perniagaan di seluruh dunia.
Mengikut Industri
E-dagang
Pendidikan
Kewangan
Hospitaliti
Semua industri
Mengikut Jabatan
Jualan
Kejuruteraan
Produk
ITSM
Semua jabatan
Mengikut Kes Penggunaan
Pembantu Beli-belah
Penjanaan Utama
Pengalaman Pekerja
Pengurusan Tiket
Semua kes penggunaan
Sumber
Penting
Academy
Belajar membina melalui kursus yang dipilih susun
Perpustakaan
Sumber untuk meningkatkan aliran kerja AI anda
Blog
Cerapan dan kemas kini tentang Botpress dan ejen AI
bangunan
Discord
Sertai beribu-ribu rakan sebaya dan kongsi idea
Dokumen
Panduan dan rujukan yang komprehensif
API
Bahan rujukan untuk digunakan dengan sistem luaran
LLM Kedudukan
Bandingkan prestasi dan kos untuk pembekal model
Video
Tutorial, tunjuk cara dan panduan produk
Changelog
Ikuti perkembangan terkini Botpress kemas kini
Rakan kongsi
Menjadi Rakan Kongsi
Sertai rangkaian pakar bertauliah kami
Upah Pakar
Berhubung dengan rakan kongsi dan perunding
Dokumen
Perusahaan
Harga
Log masuk
KenalanDaftar
kembali ke Hub

HITL Peti Masuk HubSpot

v5.0.1
Pasang pada Ruang Kerja anda
Diselenggara oleh Botpress Pasukan Pertumbuhan
  
# 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.

Bina Lebih Baik dengan Botpress

Cipta pengalaman ejen AI yang menakjubkan.

Mulakan - ia percuma
Ikon anak panah
Maklumat lanjut di Botpress Academy

Bina ejen AI dengan lebih baik dan pantas dengan koleksi kursus, panduan dan tutorial kami yang dipilih susun.

Upah Pakar

Berhubung dengan pembangun bertauliah kami untuk mencari pembina pakar yang sesuai dengan keperluan anda.

Semua Sistem Operasi
SOC 2
Diperakui
GDPR
Patuh
© 2025
Platform
Harga
Studio Ejen
Enjin Autonomi
Pangkalan Pengetahuan
Jadual
Hub
Integrasi
Saluran
LLMs
Sumber
Bercakap dengan Jualan
Dokumentasi
Upah Pakar
Video
Cerita Pelanggan
Rujukan API
Blog
Status
Sumber v12
Komuniti
Sokongan Komuniti
Menjadi Rakan Kongsi
Menjadi Duta Besar
Menjadi Ahli Gabungan
Syarikat
Tentang
Kerjaya
Berita & Akhbar
Undang
Privasi
© Botpress 2025