المنصة
الميزات
استوديو الوكيل
أنشئ وكيلك وخصصه بسرعة
المحرك المستقل
استخدم LLMs لتوجيه المحادثات والمهام
قواعد المعرفة
تدريب الروبوت الخاص بك باستخدام مصادر المعرفة المخصصة
الجداول
تخزين بيانات المحادثة وإدارتها
القنوات
Whatsapp الشعار
WhatsApp
Instagram الشعار
Instagram
فيسبوك Messenger الشعار
Messenger
Slack Logo
Slack
جميع القنوات
التكاملات
شعار هبسبوت
هوب سبوت
شعار Notion
Notion
شعار جيرا
جيرا
Calendly الشعار
Calendly
جميع عمليات الدمج
LLM المزودون
شعار OpenAI
OpenAI
شعار Anthropic
Anthropic
شعار Groq
Groq
شعار HuggingFace
Hugging Face
الكل LLMs
محاليل
بالنسبة لـ
مؤسسة
أتمتة عمليات سير عمل الإنتاج ذات المهام الحرجة
الوكالات
تقديم خدمات الوكيل المتطورة
المطورين
استكشاف واجهة برمجة تطبيقات API قوية لتطوير الوكلاء
قصص العملاء
اكتشف من العملاء الناجحين كيف يقوم Botpress بتحويل الأعمال التجارية في جميع أنحاء العالم.
حسب الصناعة
التجارة الإلكترونية
التعليم
التمويل
الضيافه
جميع الصناعات
حسب القسم
المبيعات
الهندسة
المنتج
إدارة خدمات تكنولوجيا المعلومات والاتصالات
جميع الأقسام
حسب حالة الاستخدام
مساعد تسوق
توليد العملاء المحتملين
تجربة الموظف
إدارة التذاكر
جميع حالات الاستخدام
موارد
أساسي
Academy
تعلّم البناء من خلال الدورات التدريبية المنسقة
المكتبة
موارد لتحسين سير عمل الذكاء الاصطناعي لديك
مدونة
رؤى وتحديثات حول Botpress وعوامل الذكاء الاصطناعي
المبنى
ديسكورد
انضم إلى آلاف الأقران وشارك الأفكار
مستندات
أدلة ومراجع شاملة
واجهة برمجة التطبيقات
مواد مرجعية للاستخدام مع الأنظمة الخارجية
LLM الترتيب
مقارنة الأداء والتكلفة لمقدمي الخدمات النموذجية
مقاطع الفيديو
برامج تعليمية وعروض توضيحية وعروض تجول للمنتج
سجل التغييرات
ابق على اطلاع دائم بآخر تحديثات Botpress
شركاء
كن شريكًا
انضم إلى شبكتنا من الخبراء المعتمدين
استعن بخبير
تواصل مع الشركاء والاستشاريين
مستندات
مؤسسة
الأسعار
تسجيل الدخول
اتصل بناالتسجيل
العودة إلى Hub

HubSpot Inbox HITL

v5.0.1
التثبيت على مساحة العمل الخاصة بك
يحتفظ بها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 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.

بناء أفضل مع Botpress

صمم تجارب عملاء الذكاء الاصطناعي المذهلة.

ابدأ الآن- مجانًا
أيقونة سهم
تعرف على المزيد في Botpress Academy

أنشئ وكلاء الذكاء الاصطناعي بشكل أفضل وأسرع مع مجموعتنا المنسقة من الدورات التدريبية والأدلة والبرامج التعليمية.

استعن بخبير

تواصل مع مطورينا المعتمدين للعثور على مطور خبير يناسب احتياجاتك.

جميع الأنظمة قيد التشغيل
SOC 2
معتمد
اللائحة العامة لحماية البيانات العامة
متوافق
© 2025
المنصة
الأسعار
استوديو الوكيل
المحرك المستقل
قواعد المعرفة
الجداول
مجمع
التكاملات
القنوات
LLMs
موارد
تحدث إلى مسؤولي المبيعات
مستندات
استعن بخبير
مقاطع الفيديو
قصص العملاء
مراجع واجهة برمجة التطبيقات
مدونة
الحالة
مصادر الإصدار رقم 12
المجتمع
دعم المجتمع
كن شريكًا
كن سفيراً
كُن شريكًا
الشركة
عننا
الوظائف
الأخبار والصحافة
قانوني
الخصوصية
Botpress 2025