Plataforma
Features
Estúdio de agentes
Crie e personalize o seu agente rapidamente
Motor autónomo
Utilizar LLMs para orientar as conversas e as tarefas
Bases de conhecimento
Treine seu bot com fontes de conhecimento personalizadas
Tabelas
Armazene e gerencie dados de conversa
Canais
Emblema do Whatsapp
WhatsApp
Instagram Emblema
Instagram
Logótipo do Facebook Messenger
Messenger
Logotipo do Slack
Slack
Todos os canais
Integrações
Logótipo da Hubspot
HubSpot
Logótipo Notion
Notion
Logótipo Jira
Jira
Calendly logótipo
Calendly
Todas as integrações
Provedores de LLM
Logótipo OpenAI
OpenAI
Logótipo Anthropic
Anthropic
Logótipo Groq
Groq
Logótipo HuggingFace
Hugging Face
Todos os LLMs
Soluções
Para
Enterprise
Automatize fluxos de trabalho de produção essenciais.
Agências
Ofereça serviços de agentes sofisticados.
Programadores
Explore uma API robusta para desenvolvimento de agentes.
Histórias de clientes
Descubra, através de clientes bem sucedidos, como o Botpress está a transformar os negócios em todo o mundo.
Por sector
Ecommerce
Educação
Finanças
Hospitalidade
Todos os setores
Por Departamento
Vendas
Engenharia
Produto
ITSM
Todos os departamentos
Por caso de utilização
Assistente de compras
Geração de leads
Experiência do Funcionário
Gestão de Tickets
Todos os casos de utilização
Recursos
Essencial
Academy
Aprenda a construir por meio de cursos selecionados.
Biblioteca
Recursos para melhorar os seus fluxos de trabalho de IA.
Blogue
Insights e atualizações sobre o Botpress e agentes de IA.
edifício
Discord
Junte-se a milhares de colegas e partilhe ideias
Documentos
Guias e referências abrangentes.
API
Material de referência para utilização com sistemas externos
LLM Classificação
Compare o desempenho e o custo para provedores de modelos.
Vídeos
Tutoriais, demonstrações e orientações sobre produtos
Registro de Alterações
Mantenha-se atualizado sobre as últimas atualizações do Botpress.
Parceiros
Torne-se um Parceiro
Junte-se à nossa rede de especialistas certificados.
Contrate um Especialista
Ligação com parceiros e consultores
Documentos
Enterprise
Preços
Iniciar sessão
ContatoInscrever-se
voltar para Hub

Centro de Ajuda do HubSpot HITL

v3.0.0
Instalar no seu espaço de trabalho
Mantido por Botpress Equipa de crescimento
  
# 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.

Construir melhor com Botpress

Crie experiências incríveis para agentes de IA.

Comece agora - é grátis
Ícone de uma seta
Saiba mais na Botpress Academy

Crie agentes de IA melhor e mais rapidamente com a nossa coleção de cursos, guias e tutoriais.

Contrate um Especialista

Conheça nossos desenvolvedores certificados para encontrar um construtor especializado que atenda às suas necessidades.

Todos os sistemas operacionais
SOC 2
Certificado
RGPD
Em conformidade
© 2025
Plataforma
Preços
Estúdio de agentes
Motor autónomo
Bases de conhecimento
Tabelas
Hub
Integrações
Canais
LLMs
Recursos
Fale com Vendas
Documentação
Contrate um Especialista
Vídeos
Histórias de clientes
Referência da API
Blogue
Status
v12 Recursos
Comunidade
Suporte da Comunidade
Torne-se um Parceiro
Torne-se um Embaixador
Torne-se um Afiliado
Empresa
Sobre
Carreiras
Notícias e imprensa
Legal
Privacidade
© Botpress 2025