hubspot-get-associations

用途

本技能（hubspot-get-associations）用于在 HubSpot CRM 中获取对象之间的关联记录（associations）。当用户提出“get associations”“linked records”“contacts on deal”“company contacts”“related records”等需求时加载使用，本质上是一个通过命令行脚本查询 HubSpot 关联数据的专项技能。

运行前检查

在执行操作前，需先运行配置检查脚本：

python 00-system/skills/hubspot/hubspot-master/scripts/check_hubspot_config.py --json

如果返回的 ai_action 不是 proceed_with_operation，则应按照 hubspot-connect 设置指南进行配置。

主要能力与使用方式

技能通过 get_associations.py 脚本调用，需要以下必填参数：

--object-type：源对象类型（contacts、companies、deals）
--object-id：源对象 ID
--to-type：要查找关联的目标对象类型

使用示例（保留原始命令）：

获取某个交易上的联系人：

python 00-system/skills/hubspot/hubspot-master/scripts/get_associations.py \
  --object-type deals \
  --object-id 5840795376 \
  --to-type contacts \
  --json

获取某家公司的联系人：

python 00-system/skills/hubspot/hubspot-master/scripts/get_associations.py \
  --object-type companies \
  --object-id 6493611979 \
  --to-type contacts \
  --json

获取某个联系人的交易：

python 00-system/skills/hubspot/hubspot-master/scripts/get_associations.py \
  --object-type contacts \
  --object-id 12345 \
  --to-type deals \
  --json

获取某个联系人所属的公司：

python 00-system/skills/hubspot/hubspot-master/scripts/get_associations.py \
  --object-type contacts \
  --object-id 12345 \
  --to-type companies \
  --json

有效对象类型

contacts：联系人记录
companies：公司记录
deals：交易 / 商机记录

输出格式

脚本返回 JSON 结构，包含 results 数组，每个结果项中包含 toObjectId（目标对象 ID）与 associationTypes（关联类型列表，含 category、typeId、label）：

{
  "results": [
    {
      "toObjectId": 12345,
      "associationTypes": [
        {
          "category": "HUBSPOT_DEFINED",
          "typeId": 3,
          "label": "Deal to Contact"
        }
      ]
    }
  ]
}

展示格式示例：

Found 3 contacts associated with deal 5840795376:

1. Contact ID: 12345 (Deal to Contact)
2. Contact ID: 12346 (Deal to Contact)
3. Contact ID: 12347 (Deal to Contact)

Use 'search contacts --id 12345' for full details.

适用场景

根据资料中给出的对照表，常见使用场景包括：

“Who is on this deal?” → deals → contacts
“What company is John at?” → contacts → companies
“Show contacts at Acme” → companies → contacts
“What deals does John have?” → contacts → deals

错误处理

资料中列出的错误及对应解决方案：

401：令牌无效（invalid token）——重新运行设置
403：对象类型缺少读取权限（missing read scope）
404：对象未找到——检查 ID
429：触发速率限制——等待后重试

限制

资料中仅说明支持 contacts、companies、deals 三类对象，其余对象类型、返回字段的完整范围、速率限制的具体数值、价格与平台要求等信息暂未提供。

技能介绍

用途