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

# HubSpot

> Connect HubSpot to Remark so agents can create and retrieve support tickets.

Remark's HubSpot integration lets agents create HubSpot tickets from shopper conversations and retrieve recent HubSpot tickets for a customer.

The current integration is ticket-focused. Remark uses HubSpot contacts to find tickets by customer email, but it does not manage HubSpot deals or contact records.

## What the integration does

Once connected, Remark can:

* Create a HubSpot ticket in the pipeline and stage you configure
* Retrieve up to 20 recent HubSpot tickets associated with a customer email
* Include the shopper email and Remark conversation URL in tickets created from live conversations

<Info>
  Ticket creation is skipped in playground chats. Use the playground to test intent matching and instructions, then test live ticket creation in a controlled conversation.
</Info>

## Before you start

You need:

* Access to **Settings > Integrations** in the Remark dashboard
* HubSpot access to create or manage private apps, usually as a super admin
* A HubSpot private app access token
* A HubSpot ticket pipeline ID
* A HubSpot ticket stage ID

The HubSpot private app needs permission to read contacts and read, create, and delete tickets. Remark uses those permissions to look up tickets by customer email and to run the integration health check.

## Find your HubSpot access token

In HubSpot, create or open the private app you want Remark to use.

1. Open **Development** in HubSpot.
2. Go to **Legacy apps**.
3. Create a private app, or select an existing private app.
4. Open the **Auth** tab.
5. Show and copy the access token.

HubSpot's private app docs cover the full setup flow: [Legacy private apps](https://developers.hubspot.com/docs/apps/legacy-apps/private-apps/overview).

## Find your pipeline and stage IDs

Use the ticket pipeline and stage where Remark should create new support tickets.

In HubSpot, open your ticket pipeline settings and copy the internal ID for:

* The ticket pipeline
* The pipeline stage where new Remark-created tickets should start

If those IDs are not visible in your HubSpot settings, ask a HubSpot administrator or developer on your team to retrieve them from HubSpot's CRM Pipelines API.

## Connect HubSpot

1. Open **Settings > Integrations** in the Remark dashboard.
2. Find **HubSpot**.
3. Select **Connect**.
4. Enter the HubSpot **Access token**.
5. Enter the **Pipeline ID**.
6. Enter the **Stage ID**.
7. Submit the connection form.

Remark tests the access token before saving the integration. After the integration is saved, the health check also verifies the configured ticket pipeline and stage.

## Add HubSpot to an intent

Connecting HubSpot makes the HubSpot actions available to your workspace. To let agents create or retrieve tickets during conversations, add the relevant action to an [intent](/dashboard/intents).

Use HubSpot actions in intents such as:

* Escalation to support
* Order issue follow-up
* Warranty or repair requests
* Customer service handoff

In that intent:

1. Add the HubSpot action the agent should be allowed to use.
2. Tell the agent when to create a ticket or retrieve existing tickets.
3. Tell the agent what customer details to collect before creating a ticket.
4. Test the intent in the playground before enabling it for live conversations.

## Supported actions

### Create HubSpot ticket

Agents can create a HubSpot ticket after they have enough context for a human support teammate to follow up.

The action needs:

| Field          | Description                                                  |
| -------------- | ------------------------------------------------------------ |
| Customer email | The shopper's email address                                  |
| Subject        | A short summary of the issue                                 |
| Description    | The details a support teammate needs to understand the issue |

Remark creates the ticket in the HubSpot pipeline and stage configured on the integration. For live conversations, Remark also adds the shopper email and Remark conversation URL to the ticket content.

### Retrieve HubSpot tickets

Agents can retrieve recent HubSpot tickets for a shopper by email address.

Remark looks up the HubSpot contact with that email address, then searches for tickets associated with that contact. The result includes ticket IDs, subjects, priorities, creation dates, and descriptions.

If no HubSpot contact exists for that email, or the tickets are not associated with that contact, Remark returns no tickets.

## Health check

The HubSpot health check validates:

* The access token can call the HubSpot tickets API
* Remark can create a test ticket in the configured pipeline and stage
* Remark can read the test ticket back from HubSpot
* Remark can delete the test ticket after the check completes

If the health check fails during ticket creation, the access token may be missing ticket permissions or the pipeline or stage ID may be invalid.

## Troubleshooting

### Access token is rejected

Confirm that the token is from a HubSpot private app and has not been rotated, deleted, or copied with missing characters. If the HubSpot user who created the private app was removed or lost permissions, rotate the private app token in HubSpot and update the integration in Remark.

### Missing scopes or permissions

Confirm that the private app can read contacts and read, create, and delete tickets. Remark needs contact read access to find tickets by shopper email and ticket access to create tickets, retrieve tickets, and run the health check.

### Pipeline or stage validation fails

Confirm that the pipeline ID is for a HubSpot ticket pipeline and the stage ID belongs to that same pipeline. Remark creates tickets using the exact IDs saved in the integration.

### Existing tickets are not found

Confirm that the shopper email matches a HubSpot contact email and that the tickets are associated with that contact. Remark does not search all HubSpot tickets by free text.

### Ticket creation fails

Confirm that the access token can create tickets and that the configured pipeline and stage are active. If the pipeline was renamed, the ID usually stays the same; if it was deleted or replaced, update the integration with the new ID.

<Note>
  Need help connecting HubSpot or testing ticket actions? Contact `support@remark.ai`.
</Note>