ghl-crm-for-realtors

使用此技能为房地产经纪人进行 GoHighLevel CRM 工作：联系人查找和更新、机会/渠道操作、对话消息、日历时段以及使用 GoHighLevel API v2 的工作流程注册。

# GHL CRM for Realtors

Use this skill when a user wants realtor CRM actions in GoHighLevel (GHL), including lead follow-up, pipeline movement, appointment booking context, and messaging workflows.

## Required Environment

Set these variables before running the scripts:

- `HIGHLEVEL_TOKEN` (Private Integration token)
- `HIGHLEVEL_LOCATION_ID` (sub-account location ID)

Optional runtime variables:

- `PYTHONUNBUFFERED=1`

## Setup

If the user asks to connect or set up GHL, run:

```bash
python3 scripts/setup-wizard.py
```

The wizard validates credentials and tests API connectivity.

## Primary Script

Use the helper script for direct actions:

```bash
python3 scripts/ghl-api.py <command> [args...]
```

Common commands for realtor workflows:

- `test_connection`
- `search_contacts [query]`
- `get_contact [contact_id]`
- `create_contact [json]`
- `update_contact [contact_id] [json]`
- `list_opportunities`
- `list_pipelines`
- `list_conversations`
- `send_message [contact_id] [message]`
- `list_calendars`
- `get_free_slots [calendar_id] [start_date] [end_date]`
- `list_workflows`
- `add_to_workflow [contact_id] [workflow_id]`

## Realtor-Focused Playbooks

### New Lead Intake

1. `search_contacts` to prevent duplicates.
2. If not found, `create_contact` with source tags (for example: `buyer`, `zillow`, `open-house`).
3. Add next-step task/note using supported contact endpoints.

### Pipeline Progress

1. `list_opportunities` to inspect active deals.
2. Move stage using the opportunity update command path in `ghl-api.py`.
3. Confirm stage and status in response payload.

### Follow-Up Messaging

1. Resolve contact first (`search_contacts` or `get_contact`).
2. Send message with `send_message`.
3. Re-check conversation history with `list_conversations`.

### Appointment Assist

1. `list_calendars`
2. `get_free_slots` for date range.
3. Use the calendar endpoints in script for appointment creation if requested.

## Safety Rules

- Never print or echo raw tokens in chat output.
- Prefer dry informational reads before write actions when intent is ambiguous.
- Validate contact/opportunity IDs from GHL responses instead of guessing.
- If an API error returns 401/403, stop and ask for corrected scopes or token.

## References

Load these only as needed:

- `references/contacts.md`
- `references/opportunities.md`
- `references/conversations.md`
- `references/calendars.md`
- `references/troubleshooting.md`

---

## 中文说明

# 面向房地产经纪人的 GHL CRM

当用户想在 GoHighLevel（GHL）中执行房地产经纪人 CRM 操作时使用本技能，包括线索跟进、渠道推进、预约相关背景，以及消息工作流。

## 必需环境

在运行脚本前设置以下变量：

- `HIGHLEVEL_TOKEN`（私有集成令牌）
- `HIGHLEVEL_LOCATION_ID`（子账户位置 ID）

可选的运行时变量：

- `PYTHONUNBUFFERED=1`

## 设置

如果用户要求连接或设置 GHL，运行：

```bash
python3 scripts/setup-wizard.py
```

该向导会验证凭据并测试 API 连接性。

## 主脚本

使用辅助脚本执行直接操作：

```bash
python3 scripts/ghl-api.py <command> [args...]
```

房地产经纪人工作流的常用命令：

- `test_connection`
- `search_contacts [query]`
- `get_contact [contact_id]`
- `create_contact [json]`
- `update_contact [contact_id] [json]`
- `list_opportunities`
- `list_pipelines`
- `list_conversations`
- `send_message [contact_id] [message]`
- `list_calendars`
- `get_free_slots [calendar_id] [start_date] [end_date]`
- `list_workflows`
- `add_to_workflow [contact_id] [workflow_id]`

## 房地产经纪人专属操作手册

### 新线索接入

1. `search_contacts` 以防止重复。
2. 如果未找到，使用带来源标签的 `create_contact`（例如：`buyer`、`zillow`、`open-house`）。
3. 使用受支持的联系人端点添加下一步任务/备注。

### 渠道进展

1. `list_opportunities` 以查看活跃交易。
2. 使用 `ghl-api.py` 中的机会更新命令路径移动阶段。
3. 在响应负载中确认阶段和状态。

### 跟进消息

1. 先解析联系人（`search_contacts` 或 `get_contact`）。
2. 使用 `send_message` 发送消息。
3. 用 `list_conversations` 重新检查对话历史。

### 预约协助

1. `list_calendars`
2. 对日期范围使用 `get_free_slots`。
3. 如有需要，使用脚本中的日历端点创建预约。

## 安全规则

- 切勿在聊天输出中打印或回显原始令牌。
- 当意图不明确时，在写操作之前优先进行干读式的信息读取。
- 从 GHL 响应中验证联系人/机会 ID，而非凭空猜测。
- 如果 API 错误返回 401/403，停止并请求更正后的作用域或令牌。

## 参考

仅在需要时加载这些：

- `references/contacts.md`
- `references/opportunities.md`
- `references/conversations.md`
- `references/calendars.md`
- `references/troubleshooting.md`