如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题
概览 智能体访问 ChatGPT 与 Codex 用户文档 使用场景

本地服务“获取报价”转化流程规范

将本地服务询价插件接入 ChatGPT 转化流程的接口约定。

ChatGPT 中用于本地服务“获取报价”转化流程的插件目前处于测试阶段,获准参与的合作伙伴正在协助测试。如需申请接入,请填写 ChatGPT 商家表单。

用途

在询价等用户意图明确的本地服务场景中,ChatGPT 可以直接调用合作伙伴插件。

要启用此流程,请在本地商家数据中标明您提供的服务,并提供一个可打开询价组件的 MCP 工具。

如果您希望开发符合此规范的插件,请通过 ChatGPT 商家表单申请接入。

用户体验

当用户搜索符合条件的本地商家时,商家卡片或侧栏可以显示获取报价按钮。用户选择该按钮后,ChatGPT 会在模态窗口中打开服务提供方的询价组件。

只有当商家有符合条件的服务提供方,且该提供方已配置合作伙伴插件时,ChatGPT 才会显示此按钮。

接口要求

注册一个名为 request_service 的 MCP 工具,并将 ui://widget/request-service.html 设为其组件资源。ChatGPT 会以 modal 显示模式打开组件。用户选择获取报价时,ChatGPT 会打开该组件,并传入服务提供方为该商家分配的 ID:

const launcherTool = {
  name: "request_service",
  _meta: {
    ui: {
      resourceUri: "ui://widget/request-service.html",
    },
  },
};

const launcherInput = {
  business_id: "biz_123",
};

对于组件直接调用的每个辅助工具,请设置 _meta["openai/widgetAccessible"] = true。此元数据适用于组件可直接访问的辅助工具。启动工具仅负责打开组件时,无需设置此项。

启动工具的输入参数 business_id 必须取自匹配的服务提供方记录中的 provider_business_id。该值可以与这条服务提供方记录所属的本地商家记录的 ID 不同。

商家数据源要求

商家数据源是您向 ChatGPT 提供的本地商家记录集合,按页返回。ChatGPT 会为这些记录建立搜索索引,并根据记录中的服务提供方数据判断商家是否支持获取报价。

商家必填字段

每条商家记录都必须包含以下字段:

  • id:稳定的商家 ID,在您的数据源内唯一。
  • name:商家名称。
  • address:结构化地址,或便于阅读的格式化地址。
  • location:包含 latitude 和 longitude 的对象。
  • phone_number:商家电话号码,建议使用 E.164 格式。
  • website_url:商家网站的网址。
  • platform_url:该商家在您平台上的详情页的规范 URL。

询价操作

对于每个接受询价的商家,请添加 service_providers 数组,并在数组中加入一条包含以下字段的记录:

  • provider:您的服务提供方名称,必须与已配置的合作伙伴插件匹配。
  • provider_business_id:您为该商家分配的标识符,不能为空。ChatGPT 会将此值作为 business_id 传给 request_service。
  • action_type:对于询价操作,请将此字段设为 request_a_quote。
  • provider_action_url:用于发起询价的有效 HTTP 或 HTTPS 绝对 URL。
  • display_name:由服务提供方指定的显示名称,可选。

分页列表端点

请提供一个列表端点,例如 GET /v1/businesses,并支持以下分页方式中的一种:

  • page 和 page_size。
  • offset 和 limit。
  • 不透明的 next_page_token。

端点应接受可选参数 changes_token,用于标识上一次同步的检查点。响应中应返回 checksum 以指示数据源是否发生变化,返回 businesses 以提供当前页的商家记录,并包含所用分页方式对应的元数据。

例如,以下请求从按页码分页的数据源中获取一条商家记录:

GET /v1/businesses?page=1&page_size=1&changes_token=sync_001

请返回完整的商家记录及其询价操作:

{
  "checksum": true,
  "page": 1,
  "page_size": 1,
  "total_pages": 1,
  "businesses": [
    {
      "id": "local_biz_456",
      "name": "Acme Plumbing",
      "address": {
        "line1": "123 Market St",
        "locality": "San Francisco",
        "region": "CA",
        "postal_code": "94105",
        "country": "US",
        "formatted": "123 Market St, San Francisco, CA 94105, US"
      },
      "location": {
        "latitude": 37.793,
        "longitude": -122.396
      },
      "phone_number": "+14155551234",
      "website_url": "https://acmeplumbing.example",
      "platform_url": "https://provider.example/businesses/local_biz_456",
      "service_providers": [
        {
          "provider": "example_provider",
          "provider_business_id": "biz_123",
          "action_type": "request_a_quote",
          "provider_action_url": "https://provider.example/request-quote/biz_123",
          "display_name": "Get Quote"
        }
      ]
    }
  ]
}

启用询价入口的条件

只有同时满足以下条件,ChatGPT 才会在聊天中创建询价入口:服务提供方记录所属的商家记录具有非空 ID,服务提供方记录包含非空的 provider_business_id 和有效的 provider_action_url,且服务提供方已配置合作伙伴插件。询价按钮使用 ChatGPT 界面标签获取报价。服务提供方指定的 display_name 不会覆盖 request_a_quote 操作的按钮标签。

未来扩展

本接口约定适用于询价。询价流程无需支持预约等其他服务操作。