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 Helpdesk HITL

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

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