HubSpot Help Desk HITL

  # 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.