你好 Bonsai 集成 重力形式

如何启用插件？

购买 Hello Bonsai 集成 Gravity Forms 后，您需要在 WordPress 网站上安装该插件。让我们一起来看看安装过程。.

步骤 1： 安装

登录您的 WordPress 网站，然后导航至“插件”→“添加插件”→“上传插件”→“安装 zip 文件并激活它”。.

第二步： 注册插件

导航至“表单”→“设置”→“Hello Bonsai”，然后点击 激活许可证 在“许可证”部分，输入您的许可证密钥并激活。.

步骤 3： 连接您的 Hello Bonsai 帐户

在您的 Hello Bonsai 帐户中，转到 设置 → 我的帐户 → 集成 → 盆景 API（新增） 并创建一个 API 密钥（它以……开头）。 bonsai_at_返回 WordPress，将其粘贴到 Hello Bonsai 连接部分，然后单击“保存设置”——密钥将与 Hello Bonsai 进行验证，并一步完成帐户添加。.

第四步： 创建订阅源

打开你想用来收集潜在客户信息的表单，进入“设置”→“Hello Bonsai”选项卡，然后添加一个数据源。映射你的姓名和邮箱字段，然后根据需要启用“公司”和“交易”部分。这样就完成了——下次提交的信息就会进入 Hello Bonsai。.

功能详情

Hello Bonsai 会创建什么？

每个数据源在每次提交时都会执行最多四个步骤：

1. 公司 （可选）– 按域名和/或名称匹配，或者在没有匹配项时创建。.
2. 接触 （总是）——通过确切的电子邮件地址找到并更新，或者创建并链接到公司。.
3. 交易 （可选）– 在您选择的流程阶段打开，分配，评估，并附加到联系人和公司。.
4. 评论 （可选）——将提交的文件作为书面记录张贴在新协议上。.

如果后续步骤无法完成，之前的步骤仍然有效——该条目会被标记。 部分同步 并以简明易懂的英语解释具体需要注意的步骤，然后重新发送会从中断的地方继续执行。.

联系字段映射

• 姓名 （必填）– Gravity Forms 的姓名字段会自动合并（名字 + 姓氏）。.
• 电子邮件 （必填）– Hello Bonsai 匹配联系人的唯一密钥。.
• 职称
• 电话号码

这些是 Hello Bonsai API 目前在联系人信息中接受的字段。随着 Hello Bonsai API 的扩展（自定义字段已在其计划之中），此插件也将随之扩展。.

如果联系人已存在, 您可以为每个信息流选择相应的行为：使用提交的值更新现有联系人（默认），或保持不变。无论哪种方式，提交的内容都会与现有联系人关联——不会创建重复项，并且 Hello Bonsai 中的空白可选字段永远不会覆盖真实数据。.

公司配比

Hello Bonsai 将您帐户中的每个网站域名视为唯一域名——一个域名只能属于一家公司——这使得域名匹配极其可靠。每个数据源的“公司”部分都提供三种匹配模式：

• 域名，然后是公司名称 （默认）– 首先尝试域名，如果域名匹配失败，则回退到完全匹配（不区分大小写）的名称。.
• 仅限域名
• 公司名称

映射网站/域名字段，插件会将访客输入的任何内容进行规范化处理—— https://www.acme.com/contact 变成 acme.com 匹配之前。如果没有映射域字段，则使用联系人的域。 电子邮件 系统会自动使用，并且会忽略免费邮箱服务商（例如gmail.com、outlook.com、yahoo.com、icloud.com 等数十家），因此您永远不会使用“Gmail”这样的公司。开发者可以通过过滤器来调整免费邮箱服务商列表。.

当没有任何匹配项时, 您可以为每个信息源选择：创建公司（默认）或跳过。创建的公司名称取自映射的“公司名称”字段，如果未提交名称，则取自其域名——这与 Hello Bonsai 本身使用的命名规则相同。.

与现有公司匹配不会对其进行任何修改。. 当现有联系人提交与其尚未关联的公司相关的信息时，该插件会在不更改公司主要联系人的情况下创建链接——这是 Hello Bonsai 的 API 处理起来非常棘手的问题，而插件会自动为您处理。.

优惠

启用“交易”版块后，每个捕获到的潜在客户都可以在您的 Hello Bonsai 交易看板上创建交易。Hello Bonsai 要求每笔交易都必须属于一家公司，因此需要启用并配置“公司”版块——如果未启用，信息流编辑器和条目结果都会明确提示。.

• 交易标题 – 支持 Gravity Forms 合并标签，例如. Website lead – {Name:1}. 默认为表单标题。.
• 交易价值 – 映射任何包含金额的表单字段。产品字段会识别货币（读取的是价格，而不是标签），数字字段也同样适用。.
• 管道阶段 – 实时选择您 Hello Bonsai 账户中显示的实际交易板阶段。默认显示第一阶段。.
• 分配给 – 未分配、关联帐户的成员或任何活跃团队成员（也实时提取）。.
• 达成协议 ——每次提交都这样，或者仅在联系人是新用户时才这样。第二种方法可以防止老客户重复提交交易。.

交易评论

启用评论选项后，插件会将评论内容发布到新创建的交易页面上——默认模板是 {form_title} 其次是 {all_fields}, 您可以使用任何合并标签进行自定义。在 Hello Bonsai 中接单的人无需离开交易板即可查看完整的询价信息。（Hello Bonsai 的评论为纯文本格式；格式由 Hello Bonsai 移除。）

参赛结果及重新发送

每份参赛作品都会获得一个 你好，盆景 详情页面上的方框会显示具体发生的事情：

• 已同步 所有要求的步骤均已完成。.
• 部分同步 在 Hello Bonsai 中，联系人信息是安全的，但后续步骤（公司、交易或评论）需要注意。消息会明确说明具体是哪一步以及原因。.
• 同步失败 ——无法写入任何内容；消息中包含 Hello Bonsai 自身的错误。.

创建的联系人 ID、公司 ID 和交易 ID 为： 可点击链接直接进入您的 Hello Bonsai 帐户, 并且，在任何支持对话中都会显示 Hello Bonsai 的请求 ID。.

这 重新发送至 Hello Bonsai 此按钮可安全地重试失败或部分同步：公司和联系人会重新匹配而不是重复创建，已创建的交易绝不会重新创建，已发布的评论绝不会重复发布。它也适用于插件发布之前的条目——打开任何较早的条目并点击即可。 发送至 Hello Bonsai 填补它。.

合并标签

{bonsai_contact_id} – 与此条目关联的 Hello Bonsai 联系 ID。.

{bonsai_company_id} – 与此条目关联的 Hello Bonsai 公司 ID。.

{bonsai_deal_id} – 此条目已开启 Hello Bonsai 交易 ID。.

可在通知、确认和 Webhook 有效负载中使用它们。提交过程中，信息流会同步处理，因此 Gravity Forms 发送同一提交的通知时，ID 已经解析完毕——不会出现竞态条件。对于未创建的记录（例如，重复提交者未达成交易），其标签将为空。.

多个账户

代理机构和多品牌团队可以连接多个 Hello Bonsai 帐户。每个帐户在添加时都会进行验证，并列在“已连接帐户”表中，用户可以进行测试和移除操作。每个信息源都可以选择要发送到的帐户——如果信息源未指定，则使用默认帐户。凭据存储在 WordPress 数据库的服务器端，保存后不会再渲染到页面中。.

错误通知和重新同步

错误通知 在“表单”→“设置”→“Hello Bonsai”→“错误报告”中添加电子邮件地址，即可在同步失败或部分成功时收到电子邮件。邮件包含源信息、确切的结果消息、Hello Bonsai 的请求 ID 以及指向该条目的直接链接，方便您进行调查并只需点击两下即可重新发送。.

条目编辑重新同步 - 当 WordPress 后台编辑表单条目时，可以选择重新运行表单数据，以便关联的 Hello Bonsai 联系人和公司信息能够获取更正后的值。无论重新同步多少次，都不会为同一条目创建两次交易。.

常见问题解答

我该如何获取 Hello Bonsai API 密钥？

在您的 Hello Bonsai 帐户下 设置 → API, 创建一个 API 密钥——它以……开头 bonsai_at_. 将其粘贴到插件的设置页面，即可一步完成验证和保存。任何能够创建 API 密钥的 Hello Bonsai 帐户均可与此插件配合使用。.

为什么我的投稿没有达成协议？

Hello Bonsai 要求每笔交易都必须属于一家公司，因此必须启用信息流的“公司”部分，并且必须匹配或创建一个公司。条目的 Hello Bonsai 信息框会详细说明每个步骤的具体情况——如果跳过了公司或无法解决，交易信息会以简明易懂的语言进行说明。.

同一个人提交两次会发生什么？

该插件会通过电子邮件查找现有联系人，绝不会创建重复项。对于每个信息流，您可以选择提交信息后是否更新联系人的详细信息，以及是否开启新的交易，还是仅在首次联系时才开启交易。公司之间的重新匹配方式相同。.

我可以推送安装插件之前提交的条目吗？

是的。打开任意条目并点击 发送至 Hello Bonsai 在“Hello Bonsai”框中。它会将表单数据与该条目进行比对，并提供完整的重复数据保护，因此即使其中一些人已经存在于您的“Hello Bonsai”中，回填也是安全的。.

我可以映射自定义字段或发送文件上传吗？

尚未实现——Hello Bonsai 的公共 API 目前不支持自定义字段、文件附件或 Webhook。该插件映射了 API 目前支持的所有内容，随着 Hello Bonsai API 的扩展，该插件也会随之扩展。在此期间，使用“交易评论”选项是获取完整提交内容（包括所有字段）的绝佳方式，方便负责该销售线索的人员查看。.

我只能向 Hello Bonsai 投稿某些类型的作品吗？

是的——每个信息流都支持 Gravity Forms 条件逻辑（“如果……则发送到 Hello Bonsai”），因此您可以根据任何字段来控制同步：仅限合格的预算、仅限某些服务选择、仅限非垃圾邮件，任何适合您表单的内容都可以。.

哪些数据会离开我的网站？

只有您在信息流中映射的值（以及评论模板，如果已启用）会通过 HTTPS 直接发送到 Hello Bonsai 的官方 API。不会发送给任何其他第三方，并且只有在满足信息流的条件时才会发送任何数据。.

它是否支持缓存/CDN和脚本优化？

是的，无需任何配置。所有同步都在表单提交时于服务器端进行——没有前端脚本，因此无需排除任何缓存、压缩或延迟加载插件。.

它是否兼容支持 AJAX 的 Gravity Forms 表单？

是的，它适用于 AJAX表单 以及标准的（非 AJAX）Gravity Forms 提交。.

如果在提交过程中 Hello Bonsai 运行缓慢或无法访问，会发生什么情况？

您的访客受到保护：插件会在短暂地重试暂时性故障时，限制单次提交的总耗时（默认 40 秒，可通过过滤器调整），因此即使 API 速度慢，也不会导致表单卡死。所有未完成的操作都会如实记录在表单条目中，显示为“失败”或“部分完成”——如果您设置了错误通知邮件，您会收到通知——一旦 Hello Bonsai 恢复正常，只需点击“重新发送”即可完成提交。.

它是否支持 WordPress 多站点网络？

是的。每个子站点都连接自己的 Hello Bonsai 帐户（或多个帐户），并配置自己的订阅源，卸载操作会清理整个网络。使用无限许可证，网络模式允许您一次性将单个许可证密钥推送至所有子站点。.

可以翻译了吗？

是的——每个字符串都是可翻译的。您可以使用免费的 Loco Translate 插件 创建适用于您网站语言/地区的翻译。如果您之前从未使用过 Loco Translate，请点击此处。 适合初学者的教程.

钩子

过滤器

pb_gfhellobonsai_contact_payload

在将联系人正文发送到 Hello Bonsai 之前对其进行筛选——在发送过程中调整姓名、电子邮件、职位或电话号码。.

参数：

• $contact_body （大批） – 已设置联系人字段（姓名、电子邮件、职位、电话号码）。.
• $feed （大批） – Gravity Forms 饲料。.
• $entry （大批） – 当前条目。.
• $form （大批） – 当前形式。.

// Title-case every contact name on its way into Hello Bonsai.
add_filter( 'pb_gfhellobonsai_contact_payload', function( $contact_body, $feed, $entry, $form ) {
    if ( isset( $contact_body['name'] ) ) {
        $contact_body['name'] = ucwords( strtolower( $contact_body['name'] ) );
    }
    return $contact_body;
}, 10, 4 );

pb_gfhellobonsai_company_payload

在创建公司之前筛选公司主体——调整名称或域名。.

参数：

• $body （大批） – 公司字段（名称、域名）。.
• $feed （大批） – Gravity Forms 饲料。.
• $entry （大批） – 当前条目。.
• $form （大批） – 当前形式。.

// Prefix companies created from forms so they're easy to spot in Hello Bonsai.
add_filter( 'pb_gfhellobonsai_company_payload', function( $body, $feed, $entry, $form ) {
    $body['name'] = 'Lead: ' . $body['name'];
    return $body;
}, 10, 4 );

pb_gfhellobonsai_deal_payload

在发送交易正文之前对其进行筛选——通过编程方式调整标题、价值、阶段或受让人。.

参数：

• $deal （大批） – 交易字段（标题、公司 ID、联系人 ID、董事会组 ID、受让人成员 ID、交易值）。.
• $feed （大批） – Gravity Forms 饲料。.
• $entry （大批） – 当前条目。.
• $form （大批） – 当前形式。.

// Route big-budget leads into a different pipeline stage.
add_filter( 'pb_gfhellobonsai_deal_payload', function( $deal, $feed, $entry, $form ) {
    if ( isset( $deal['deal_value'] ) && (float) $deal['deal_value'] >= 10000 ) {
        $deal['board_group_id'] = 'your-priority-stage-uuid';
    }
    return $deal;
}, 10, 4 );

pb_gfhellobonsai_free_email_domains

筛选从基于电子邮件的公司匹配中排除的免费邮箱域名列表（默认情况下包括 gmail.com、outlook.com、yahoo.com、icloud.com 等数十个域名）。.

参数：

• $free_domains （大批） - 要排除的小写域名。.

// Also treat a local ISP's addresses as personal email.
add_filter( 'pb_gfhellobonsai_free_email_domains', function( $free_domains ) {
    $free_domains[] = 'myisp.example';
    return $free_domains;
} );

pb_gfhellobonsai_record_url

在输入框中筛选用于同步记录链接的 Hello Bonsai 应用 URL。返回空字符串以呈现不带链接的纯 ID。.

参数：

• $url （细绳） – 此记录的默认应用程序 URL。.
• $type （细绳） – 联系人、公司、交易之一。.
• $id （整数） – Hello Bonsai 的记录 ID。.

pb_gfhellobonsai_run_time_budget

调整 Hello Bonsai 在单次 Feed 运行中所有请求共享的等待时间（以秒为单位）。Feed 在提交期间同步处理，因此这是 API 降级后访客停留时间的上限。默认值为 40。.

参数：

• $seconds （漂浮） ——预算以秒为单位计算。默认值为 40。.

// Tighten the budget on high-traffic sites.
add_filter( 'pb_gfhellobonsai_run_time_budget', function( $seconds ) {
    return 20.0;
} );

pb_gfhellobonsai_runtime_allowed

绕过数据处理许可限制。主要用于测试和开发环境。.

参数：

• $allowed （布尔值） – 许可证目前是否允许进行饲料加工。.

pb_gfhellobonsai_api_base_url

覆盖 Hello Bonsai API 的基本 URL。仅用于针对模拟 API 进行开发和测试——在生产环境中永远不需要用到它。.

参数：

• $url （细绳） – API 基本 URL。默认值 https://app.hellobonsai.com/public-api/v1.