conversation-history-brief

Requires the conversations command group from hub-cli PR #251. hubspot conversations --help is authoritative. Also read communication-history/SKILL.md for CRM activity history (calls, emails, notes) — this skill covers the Conversations inbox surface only.

How threads associate to contacts

conversations threads list accepts --associated-contact-id. You must also supply --inbox-id — there is no portal-wide contact thread lookup without knowing the inbox. To cover all inboxes, enumerate them first (step 1), then query per inbox.

Paging: never collect a full result set with --format jsonl

Every conversations list command defaults to --limit 100 and returns a cursor for the next page. --format jsonl prints only the data rows — the cursor is surfaced only by --format json, at .meta.next. Piping --format jsonl into a file therefore silently truncates at the first 100 rows, and raising --limit is not a fix because the endpoint caps the page size.

Use this helper for anything that must see every row:

# conv_page <output-file> <conversations list args...>
# Pages a conversations list endpoint to exhaustion, writing one JSON object
# per line to <output-file>.
conv_page() {
  out=$1; shift
  after=""
  : > "$out"
  while :; do
    if [ -n "$after" ]; then
      page=$(hubspot "$@" --format json --after "$after") || return 1
    else
      page=$(hubspot "$@" --format json) || return 1
    fi
    printf '%s' "$page" | jq -c '.data[]' >> "$out"
    after=$(printf '%s' "$page" | jq -r '.meta.next // empty')
    [ -n "$after" ] || break
  done
}

A bare --format jsonl is still fine for eyeballing the first page interactively.

1. Enumerate inboxes

conv_page /tmp/inboxes.jsonl conversations inboxes list
# {"id":"123","name":"Support Inbox","createdAt":"...","updatedAt":"..."}
# {"id":"124","name":"Sales Chat","createdAt":"...","updatedAt":"..."}

2. Find all threads for a contact

Loop over inbox IDs and collect threads associated with the contact: