> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot Ticketing

> Create support tickets in HubSpot Service Hub through AGO

Connect AGO to HubSpot Service Hub so your agents can create support tickets directly in HubSpot when they need to escalate a conversation.

## Prerequisites

* A HubSpot account with Service Hub
* Admin access to both HubSpot and AGO

***

## Step 1: Create a Private App in HubSpot

1. In HubSpot, go to **Settings** > **Integrations** > **Private Apps**
2. Click **Create a private app**
3. Enter a name (e.g., `AGO Integration`)
4. Go to the **Scopes** tab and enable these scopes:

| Scope                        | Purpose                            |
| ---------------------------- | ---------------------------------- |
| `tickets`                    | Create and manage tickets          |
| `crm.objects.contacts.read`  | Look up existing contacts          |
| `crm.objects.contacts.write` | Create new contacts                |
| `files`                      | Attach files to tickets (optional) |

5. Click **Create app**
6. Copy the **Access Token** — you will need it in the next step

> **ℹ️ NOTE**: The access token is only shown once. Store it securely.

***

## Step 2: Get Your Portal ID

Find your Portal ID in your HubSpot URL — it is the number after `/contacts/`:

```
https://app.hubspot.com/contacts/12345678/...
                              ^^^^^^^^
                              This is your Portal ID
```

***

## Step 3: Configure in AGO

1. Navigate to **Ticketing** > **Settings**
2. Set **Active Ticketing System** to **HubSpot**
3. Enter your credentials:
   * **Access Token**: the token from Step 1
   * **Portal ID**: the number from Step 2
4. Click **Save**

***

## Step 4: Create a Ticket Form

1. Navigate to **Ticketing** > **Ticket Forms**
2. Create a new form and select HubSpot as the ticketing system
3. Click **Import from HubSpot** to sync your HubSpot ticket properties
4. Add the fields you want to your form
5. Save the form

> **💡 TIP**: You can also use [Embedded Form mode](../features/ticket-form-customization#embedded-external-forms) to display a native HubSpot form directly in the chat widget.

***

## How It Works

When a user creates a ticket through AGO:

1. AGO looks up the user's email in HubSpot. If no contact exists, one is created automatically
2. A ticket is created in HubSpot with the form data
3. The contact is linked to the ticket
4. If files were attached, they are uploaded and linked to the ticket as notes
5. A link to the ticket in HubSpot is stored for reference

### Field Mapping

| AGO Field     | HubSpot Property     | Notes                                           |
| ------------- | -------------------- | ----------------------------------------------- |
| Subject       | `subject`            | Ticket title                                    |
| Description   | `content`            | Ticket body                                     |
| Priority      | `hs_ticket_priority` | Mapped: Low → LOW, Normal → MEDIUM, High → HIGH |
| Category      | `hs_ticket_category` | Mapped from AGO typology                        |
| User email    | Contact association  | Automatic lookup or creation                    |
| Files         | Note attachments     | Uploaded to HubSpot File Manager                |
| Custom fields | Custom properties    | Mapped via HubSpot property name                |

### Custom Field Mapping

To map AGO ticket fields to HubSpot properties:

1. In the ticket form builder, add a field
2. Set the **HubSpot property name** to match the internal HubSpot property
3. When a ticket is created, the field value is sent to the matching HubSpot property

### Owner Assignment

To route tickets to specific HubSpot owners:

1. Add a dropdown field to your ticket form
2. Configure each option with a HubSpot owner ID
3. When a user selects an option, the ticket is assigned to that owner in HubSpot

***

## Troubleshooting

| Issue                            | Cause                     | Fix                                                                       |
| -------------------------------- | ------------------------- | ------------------------------------------------------------------------- |
| "Access token not configured"    | Credentials missing       | Verify token and portal ID in Ticketing settings                          |
| "Failed to create ticket"        | Permission or API issue   | Check that your Private App has the required scopes                       |
| Tickets not appearing in HubSpot | Wrong pipeline or stage   | Verify the default pipeline exists in your HubSpot account                |
| Contact not found                | Email mismatch            | The user's email must match; AGO creates contacts automatically if needed |
| File attachments missing         | `files` scope not enabled | Add the `files` scope to your Private App                                 |

***

## Related

* [Ticketing](../features/ticketing) — Ticketing feature overview
* [Ticket Form Customization](../features/ticket-form-customization) — Form field configuration and embedded forms
* [Ticketing Connectors](../data-connector/ticketing-connectors) — Compare available connectors
* [HelpScout Integration](../data-connector/helpscout-integration) — Alternative ticketing connector
* [Zendesk Integration](../data-connector/zendesk-ticketing-integration) — Alternative ticketing connector