Operations | Understand the HubSpot ticket categorisation automation

Goal

This internal guide explains how the HubSpot ticket categorisation and sentiment automation works (what it processes, how it makes decisions, and what gets updated and logged).

When to use this guide

Use this when you need to understand why a ticket was categorised a certain way, why sentiment looks off, or why some tickets end up in the “Wrong Categories” log.

What the automation does

Every 60 minutes the workflow:

1. Fetches HubSpot tickets that miss AI fields (category and or sentiment)

2. Detects WhatsApp tickets and pulls the full conversation history (when available)

3. Runs AI analysis to assign

   1. A support category (from a predefined list of 65 plus options)

   2. A sentiment label (Positive, Neutral, or Negative)

4. Writes the results back to the HubSpot ticket

5. Logs outcomes to Airtable (for analytics and debugging)

Trigger setup

The workflow runs on a schedule.

End to end flow

1) Fetch tickets from HubSpot

The workflow pulls four ticket sets in parallel (to catch both open and closed tickets that still miss one of the AI fields).

• Closed tickets without category (limit 50)

• Closed tickets without sentiment (limit 25)

• Open tickets without category (older than 7 days) (limit 25)

• Open tickets without sentiment (older than 7 days) (limit 25)

Why the “older than 7 days” filter exists for open tickets: it reduces noise from brand new conversations that are still developing.

2) Merge and normalise

The workflow then:

• Merges all four sources

• Deduplicates by ticket ID

• Extracts the fields needed for analysis (subject, content, dates, hubspot_id)

• Processes tickets in batches of 100 (per loop)

3) WhatsApp detection and enrichment

If the ticket content contains the marker text auto-logged WhatsApp Conversation the workflow treats it as a WhatsApp case.

It then:

1. Fetches thread metadata via the HubSpot Engagements API

2. Validates that a WhatsApp thread exists

3. Pulls the full message history via the HubSpot Conversations API

4. Formats the conversation chronologically (with timestamps) so the AI receives a clean thread

If no valid WhatsApp thread can be found, the workflow applies a fallback:

• Category becomes Special case

• Sentiment becomes Neutral

This avoids random guesses based on incomplete WhatsApp data.

4) AI analysis (category and sentiment in parallel)

The workflow runs two AI tasks in parallel (both using OpenAI GPT 4o mini with temperature 0).

AI categorisation

• Output must be exactly one value from the predefined category list

• The model uses a selection tool (SelectCategoryFromList) to constrain output to allowed options

• Max tokens is set to 300 (enough for a short rationale internally, while still keeping the output tight)

AI sentiment

• Output must be one of: Positive, Neutral, Negative

• The sentiment logic focuses on the final message in the conversation (so a resolved ticket does not stay “Negative” because of earlier frustration)

After both tasks finish, the workflow merges the results into one payload per ticket.

5) Validation

Before writing anything back, the workflow checks:

• Is the AI category exactly in the allowed list?

If the category is invalid (typo, unexpected string, wrong format) the ticket does not get updated with that category and the output is logged to the Airtable “Wrong Categories” table for debugging.

If the category is valid, the workflow continues.

6) Update records and log to Airtable

For each valid ticket the workflow:

• PATCHes the HubSpot ticket with

  • ai_ticket_category

  • ai_ticket_sentiment

• Creates an Airtable record (analytics log) in hubspot_CG_SM_tickets

Special rules the workflow applies

These rules override or short circuit normal processing.

Category options (how the list is used)

The AI can only assign one category from the predefined list (65 plus options). The list covers:

• FAQ topics (for common questions)

• Feature requests (product and ecosystem ideas)

• Pre sales questions (compatibility, pricing, safety)

• Problems (apps, hardware, integrations, delivery, account issues, and more)

• Other operational tags (marketing, fulfilment, returns, warranty, reseller requests, not Bold Smart Lock related)

In practice: if a ticket does not cleanly match a specific bucket, it should land in Special case rather than forcing a misleading label.

Sentiment logic (what “Positive” actually means)

Sentiment is based mainly on the final user message.

Technical reference

Required HubSpot properties

These must exist for the workflow to update tickets correctly.

Airtable logging (where to look)