Plattform
Eigenschaften
Agent Studio
Bauen Sie Ihren Agenten schnell auf und passen Sie ihn an
Autonomer Motor
Verwenden Sie LLMs , um Gespräche und Aufgaben zu leiten.
Wissensgrundlagen
Trainieren Sie Ihren Bot mit benutzerdefinierten Wissensquellen
Tische
Gesprächsdaten speichern und verwalten
Kanäle
Whatsapp Wappen
WhatsApp
Instagram Wappen
Instagram
Facebook Messenger Logo
Messenger
Slack-Logo
Slack
Alle Kanäle
Integrationen
Hubspot-Logo
HubSpot
Notion
Notion
Jira-Logo
Jira
Calendly Logo
Calendly
Alle Integrationen
LLM Anbieter
OpenAI
OpenAI
Anthropic Logo
Anthropic
Groq
Groq
HuggingFace-Logo
Hugging Face
Alle LLMs
Lösungen
Für
Unternehmen
Automatisieren Sie geschäftskritische Produktionsabläufe
Agenturen
Hochentwickelte Agentendienste bereitstellen
Entwickler
Erkunden Sie eine robuste API für die Agentenentwicklung
Kundengeschichten
Erfahren Sie von erfolgreichen Kunden, wie Botpress die Geschäftswelt weltweit verändert.
Nach Industrie
Elektronischer Handel
Bildung
Finanzen
Gastfreundschaft
Alle Branchen
Nach Abteilung
Vertrieb
Technik
Produkt
ITSM
Alle Abteilungen
Nach Anwendungsfall
Einkaufsassistent
Lead-Generierung
Erfahrung der Mitarbeiter
Ticket-Verwaltung
Alle Anwendungsfälle
Ressourcen
Wesentlich
Academy
Lernen Sie durch kuratierte Kurse zu bauen
Bibliothek
Ressourcen zur Verbesserung Ihrer AI-Workflows
Blog
Einblicke und Updates zu Botpress und KI-Agenten
Gebäude
Discord
Tausende von Gleichgesinnten treffen und Ideen austauschen
Dokumente
Umfassende Leitfäden und Referenzen
API
Referenzmaterial zur Verwendung mit externen Systemen
LLM Rangliste
Leistungs- und Kostenvergleich für Modellanbieter
Videos
Tutorials, Demos und Produktpräsentationen
Änderungsliste
Bleiben Sie auf dem Laufenden über die neuesten Botpress
Partner
Partner werden
Werden Sie Mitglied in unserem Netzwerk von zertifizierten Experten
Einen Experten beauftragen
Verbindung mit Partnern und Beratern
Dokumente
Unternehmen
Preisgestaltung
Einloggen
KontaktRegistrieren Sie sich
zurück zu Hub

HubSpot Posteingang HITL

v5.0.1
Installation auf Ihrem Arbeitsbereich
Gepflegt von 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.

Besser bauen mit Botpress

Schaffen Sie erstaunliche AI-Agenten-Erlebnisse.

Starte jetzt - es ist kostenlos
Symbol eines Pfeils
Mehr Informationen unter Botpress Academy

Entwickeln Sie KI-Agenten besser und schneller mit unserer kuratierten Sammlung von Kursen, Anleitungen und Tutorials.

Einen Experten beauftragen

Setzen Sie sich mit unseren zertifizierten Entwicklern in Verbindung, um einen Experten zu finden, der Ihren Anforderungen entspricht.

Alle Systeme einsatzbereit
SOC 2
Zertifiziert
GDPR
Konform
© 2025
Plattform
Preisgestaltung
Agent Studio
Autonomer Motor
Wissensgrundlagen
Tische
Hub
Integrationen
Kanäle
LLMs
Ressourcen
Mit Sales sprechen
Dokumentation
Einen Experten beauftragen
Videos
Kundengeschichten
API-Referenz
Blog
Status
v12 Ressourcen
Gemeinschaft
Unterstützung der Gemeinschaft
Partner werden
Werden Sie Botschafter
Werden Sie ein Partner
Unternehmen
Über
Karriere
Nachrichten & Presse
Rechtliches
Datenschutz
© Botpress 2025