导出线索并回传 CRM 事件

本文介绍了以 CRM（客户关系管理）合作伙伴身份导出线索并回传 CRM 事件的具体步骤。

简介

作为 CRM 合作伙伴，您可以集成 TikTok 线索生成功能，让您的客户无需编码即可直接将线索导出到 CRM 中。

前提条件

您已经拥有 TikTok API for Business 的使用权限。详见快速入门 - 具体步骤。
若要创建广告，您需要获取相关的权限。参阅 API 参考了解使用相关接口（包括“步骤”部分列出的接口）所需的权限；参阅更新应用权限范围了解如何设置权限。
确保您的开发者应用已开启以下权限：
- 广告账号管理 > 广告账号信息
- 创意管理 > Instant Page 管理
- 潜在客户管理 > 潜在客户导出
- 潜在客户管理 > 测试线索
- CRM Event Management > Read CRM Event Sets
- 度量 > Report Conversion Event
您可以使用 /user/info/ 获取用户详情，为用户提供个性化体验。
您已通过以下传参从 /page/get/ 获取了广告账户内的即时表单列表：
business_type 设置为 LEAD_GEN
status 设置为 PUBLISHED
您已通过 /page/field/get/ 获取了即时表单的字段，以进行字段映射。

步骤

若要集成 TikTok 线索广告，需遵循以下步骤：

1. 访问线索数据

选择以下方式之一：

方式 1：通过 Webhook 接收线索

通过 /subscription/subscribe/ 订阅即时表单线索或私信线索。要了解更多步骤，请参阅订阅新线索。订阅完成后，您可以接收线索生成的实时更新。

注意
若您稍后想取消订阅，可使用 /subscription/unsubscribe/。

示例

请求

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/subscription/subscribe/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "app_id": "{{app_id}}", 
    "secret": "{{secret}}",
    "subscription_detail": {
        "advertiser_id": "{{advertiser_id}}", 
        "access_token": "{{access_token}}", 
        "page_id": "{{page_id}}"
    }, 
    "subscribe_entity": "LEAD", 
    "callback_url": "{{callback_url}}" // when there is a new lead, our 
    // service will send a post reqeust containing lead data to this callback url
}'
(/code)

(code curl http)
HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "data": {
        "subscription_id": "{{subscription_id}}"
    },
    "request_id": "{{request_id}}"
}
(/code)

方式 2：通过任务下载线索

i. 通过 /page/lead/task/ 创建线索下载任务。请注意，由于数据合规要求，广告主的线索按所在市场分别存储：欧洲（包括欧洲经济区（EEA）、瑞士和英国）、美国和其他地区。

创建不同市场的线索任务所需的 Header 配置不尽相同，具体请参阅以下代码示例：

创建欧洲市场的线索下载任务

(code http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/page/lead/task/?advertiser_id={{advertiser_id}}&page_id={{page_id}}' \
--header 'Access-Token: {{Access-Token}}' \
<span style="background-color: green;"> --header 'x-lead-region: eu'</span>
(/code)

创建美国市场的线索下载任务

(code http)
curl --location  --request POST 'https://business-api.tiktok.com/open_api/v1.3/page/lead/task/?advertiser_id={{advertiser_id}}&page_id={{page_id}}' \
--header 'Access-Token: {{Access-Token}}' \
<span style="background-color: green;"> --header 'x-lead-region: us'</span>
(/code)

创建其他市场的线索下载任务

(code http)
curl --location  --request POST 'https://business-api.tiktok.com/open_api/v1.3/page/lead/task/?advertiser_id={{advertiser_id}}&page_id={{page_id}}' \
--header 'Access-Token: {{Access-Token}}' 
(/code)

成功的返回示例

(code curl http)
HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "data": {
        "status": "CREATED",
        "task_id": "{{task_id}}"
    }
}
(/code)

ii. 当任务status为 SUCCEED 时，使用 /page/lead/task/download/ 下载线索。

下载不同市场的线索所需的 Header 配置不尽相同，具体请参阅以下代码示例：

下载欧洲市场的线索

(code http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/page/lead/task/download/?advertiser_id={{advertiser_id}}&task_id={{task_id}}' \
--header 'Access-Token: {{Access-Token}}' \
<span style="background-color: green;">--header 'x-lead-region: eu'</span>
(/code)

下载美国市场的线索

(code http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/page/lead/task/download/?advertiser_id={{advertiser_id}}&task_id={{task_id}}' \
--header 'Access-Token: {{Access-Token}}' \
<span style="background-color: green;">--header 'x-lead-region: us'</span>
(/code)

下载其他市场的线索

(code http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/page/lead/task/download/?advertiser_id={{advertiser_id}}&task_id={{task_id}}' \
--header 'Access-Token: {{Access-Token}}' \
(/code)

2. 测试线索

使用以下接口测试您的线索： - /page/lead/mock/create/ - /page/lead/mock/get/ - /page/lead/mock/delete/

3. 回传 CRM 事件

使用 CRM 事件 API 将事件数据回传给 TikTok 可产生更高质量的线索，这些线索更有可能促成转化。

请按以下步骤回传 CRM 事件：

i. 使用 /crm/list/ 获取您的广告账户内的 CRM 事件组。

ii. 使用 /event/track/ 回传您的 CRM 事件数据。将 event_source 设置为 crm，并将 event_source_id 设置为从步骤 i 获得的 CRM 事件组 ID 之一。

示例

(code curl http)
curl --location  --request POST 'https://business-api.tiktok.com/open_api/v1.3/event/track/' \
--header 'Access-Token: {{Access-Token}}' \ 
--header 'Content-Type: application/json' \
--data '{
    "event_source": "crm",
    "event_source_id": "CCM52VJC77U1F3L1CJRG", // target crm event set id
    "partner_name": "Name of the Partner", //name of the CRM
    "data": [
        {
            "event": "qualified", // the status of one lead
            "event_time": 1687673101, // timestamp for the status change
            "lead": {
                "lead_id": "lead_id", // lead_id will pass to crm when syncing
                "lead_event_source": "Lead_gen_partner_name" // name of the CRM 
            }
        }
    ]
}'
(/code)

4. 在 TikTok 广告管理平台上列为 CRM 合作伙伴

完成上述步骤后，您可以通过提高在 TikTok 上的可见度来扩大客户群。

通过填写 TikTok 广告管理平台 CRM 合作伙伴申请表单，可让更多 TikTok 广告管理平台上的广告主发现您的 CRM 平台。