stable本次发布有变化全部展示
来自 TikTok Shop 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Customer engagement
Customer Engagement APIs let eligible apps create TikTok Shop IM engagement tasks, send task-based messages to eligible buyers, and read task performance.
§2 Before you start
Customer Engagement APIs are opened on an as-needed basis. Start with the self-service scope path, then use your TikTok Shop contact or support only when the scope is not available or the application needs manual review.
| Step | What to do |
|---|---|
| 1. Prepare the app | Create or select the TikTok Shop app that will call Customer Engagement APIs. The app must already support shop authorization and token refresh. |
| 2. Apply for scopes | In Partner Center > App & Service > select the app or service > Manage API, search for and apply for the Customer Engagement scope packages, such as Customer Engagement - Read and Customer Engagement - Write. |
| 3. Reauthorize the seller | After new scopes are approved or enabled, ask the seller to authorize or reauthorize the app so the access token includes the new scopes. |
| 4. Check shop eligibility | Call Get Feature Permissions for each shop. FUNDAMENTAL=true is required to use Customer Engagement APIs. CUSTOM_MSG=true is required before using custom-message tasks. |
| 5. Contact TikTok Shop if blocked | If the Customer Engagement scope package is not visible, or if the scope application requires manual approval, provide your app key, target markets, integration path, expected message scenarios, expected send volume, and seller-facing UX screenshots to your TikTok Shop representative or support channel. |
§3 Choose an integration path
There are two supported integration patterns. Keep the requirements separate, because Shopify Marketing App use cases are not required for a direct TikTok Shop integration.
| Area | TikTok Shop direct integration | Shopify Marketing App integration |
|---|---|---|
| Best fit | Apps that build their own TikTok Shop customer engagement UI and send messages directly through TikTok Shop APIs. | Partners that already run a Shopify Marketing App and want sellers to manage TikTok Shop campaigns or automations inside Shopify. |
| Shop connection | Required. Connect, manage, disconnect, and reauthorize TikTok Shop shops through the normal shop authorization lifecycle. | Required. The Shopify app still needs TikTok Shop shop authorization before it can call TikTok Shop APIs. |
| Customer source | Use TikTok Shop order APIs. buyer_email from Get Order Detail is the anonymized buyer email used by Customer Engagement APIs. | Use Shopify customer or segment APIs when the seller manages audiences in Shopify, or use TikTok Shop order APIs when the app builds TikTok Shop audiences directly. |
| Content | Use TikTok Shop message templates, products, and coupons; optionally use custom messages if CUSTOM_MSG is authorized. | Use Shopify campaign or automation UI, then create the corresponding TikTok Shop engagement task and send through TikTok Shop APIs. |
| Campaign and automation management | Implement in your own app if needed. Shopify-native campaign or automation use cases do not apply. | Required if the seller manages campaigns or automations from Shopify. The Shopify workflow should create the corresponding TikTok Shop engagement task. |
| Performance monitoring | Read TikTok Shop task performance and display it in your app. | Read TikTok Shop task performance and display or sync it back to the Shopify marketing experience. |
§4 Integration flow
- Apply for Customer Engagement API scopes and complete seller authorization.
- Call Get Feature Permissions to confirm the shop can use Customer Engagement features.
- Build the target customer list. For direct TikTok Shop integrations, retrieve
buyer_emailfrom Get Order Detail. When sending messages, pass the values asbuyer_emailsin Send Engagement Message. - Retrieve templates from Get Message Templates, then choose eligible product and coupon cards based on the template rules.
- Create a task with Create Engagement Task, or use Create Custom Engagement Task when
CUSTOM_MSGis authorized. - Send messages through Send Engagement Message.
- Monitor delivery and conversion metrics with Get Task Performances.
§5 Shopify Marketing App flow
The following screenshots illustrate the Shopify Marketing App experience. Use them only for the Shopify path; they are not required screens for a direct TikTok Shop integration. Campaign creation example: sellers create or select a campaign in the Shopify Marketing App, choose TikTok Shop IM as the message channel, define the audience, and schedule the campaign. The integration should create the corresponding TikTok Shop engagement task after campaign setup. Image Automation example: sellers configure a Shopify automation with TikTok Shop customer behavior as the trigger or condition. When automation is activated, the integration should map the automation to a TikTok Shop engagement task and send messages through TikTok Shop APIs. Image
§6 TikTok Shop direct platform flow
The following screenshot illustrates a direct Customer Engagement Platform flow. In this path, the app owns the seller-facing customer segmentation, content editing, task creation, message sending, and performance display. Image
§7 Message sending limits
Treat these rules as implementation requirements, not as side notes in a use-case table.
| Rule | Requirement |
|---|---|
| Shop eligibility | Call GetFeaturePermissions before enabling the feature for a shop. FUNDAMENTAL is the prerequisite for Customer Engagement APIs. CUSTOM_MSG is required for custom-message tasks. |
| Recipient eligibility | SendEngagementMessage uses buyer_emails, which are anonymized buyer email values retrieved from TikTok Shop order APIs. You can only send messages to buyers who have placed at least one order with the shop in the past 365 days. |
| Frequency limit | A buyer can receive one message per week from a specific shop and up to three messages per week across TikTok Shop. Additional messages can be rejected or discarded. |
| Task end time | Every engagement task has a mandatory end_time. Once the task expires, related messages are rejected. Create a new task and link future messages to the new task. |
| DND period | If a message is sent during a system Do Not Disturb period, it is suspended until the DND period ends. |
| Template rules | Follow product_card_rules and coupon_card_rules from GetMessageTemplates. Template rules determine how many product or coupon cards can be inserted. |
| Product cards | Use product IDs from Search Products. Custom-message tasks support up to four product cards. |
| Coupon cards | Use coupon IDs from Search Coupons or Get Coupon. For custom-message tasks, only one coupon card is supported, and the coupon must match the allowed coupon properties. |
| Performance data | Task performance data is delayed by two days, or T+2. Do not present it as real-time reporting. |
| Idempotency | CreateEngagementTask and CreateCustomEngagementTask require idempotency_key. Use a unique key, such as a v4 UUID, for each create request. |
§8 Use case matrix
| Use case | Direct TikTok Shop integration | Shopify Marketing App integration | Implementation notes |
|---|---|---|---|
| SHOP-CONN-SINGLE, SHOP-CONN-MULTI | Required | Required | Connect one platform store to one or more TikTok Shop shops, depending on the app model. |
| SHOP-DISCON-SINGLE, SHOP-MAN-MULTI, SHOP-MAN-WHOOK | Required | Required | Support disconnect, connection management, and authorization-expiration handling. |
CSENG-CUSMAN-GETPERMS | Required | Required | Use Get Feature Permissions. |
CSENG-CUSMAN-GETNATIVE | Required | Optional | Use buyer_email from Get Order Detail as the anonymized buyer email source. |
CSENG-CUSMAN-GETSHOPIFY | Not applicable | Required when audiences are managed in Shopify | Use the Shopify Customer API, or use TikTok Shop order APIs when the app builds TikTok Shop audiences directly. |
CSENG-CUSMAN-SEGTNATIVE | Required if the app offers segmentation | Optional | Segment customers by TikTok Shop order behavior, such as purchase, cancellation, return, product purchased, order count, or spend. |
CSENG-CUSTMAN-SEGSHOPIFY | Not applicable | Required when using Shopify segments | Use Shopify-native customer segmentation and retrieve segment members through customerSegmentMembers when the seller manages audiences in Shopify. |
CSENG-CONTMAN-TMPLT, CSENG-CONTMAN-EDIT, CSENG-CONTMAN-PREVIEW | Required | Required | Retrieve TikTok Shop message templates and provide an editing and preview experience. |
CSENG-CONTMAN-PRODUCT, CSENG-CONTMAN-COUPONS | Required when product or coupon cards are supported | Required when product or coupon cards are supported | Use Search Products, Search Coupons, and template card rules. |
CSENG-ENGMSG-CREATE, CSENG-ENGMSG-CUSTOM, CSENG-ENGMSG-SEND, CSENG-ENGMSG-PREVIEW | Required | Required | Create a task, optionally create a custom-message task, preview content, then send by buyer_emails. |
CSENG-ENGMSG-SHPAUTO, CSENG-ENGMSG-SHPCMPGN, CSENG-ENGMSG-ACTDACT | Not applicable unless the app builds equivalent features itself | Required for Shopify campaign or automation workflows | Shopify activation/deactivation is Shopify-native, but TikTok Shop message sending still goes through Customer Engagement APIs. |
CSENG-TASKPRF-DISPLAY, CSENG-TASKPRF-COMPARE | Required for reporting | Required for reporting | Use Get Task Performances. Remember the T+2 delay. |
§9 API quick reference
| API | Method and path | Use it for | Scope |
|---|---|---|---|
| Get Feature Permissions | GET /customer_engagement/202502/permissions | Check whether the shop can use Customer Engagement features. | Customer Engagement - Read |
| Get Customer Tab Visibility | GET /customer_engagement/202501/customer_tab/visibility | Check whether the Customer tab is visible for the shop. | Customer Engagement - Read |
| Get Message Templates | GET /customer_engagement/202412/message_templates | Retrieve predefined message templates and product or coupon card rules. | Customer Engagement - Read |
| Create Engagement Task | POST /customer_engagement/202412/engagement_tasks | Create a task based on a TikTok Shop predefined template. | Customer Engagement - Write |
| Create Custom Engagement Task | POST /customer_engagement/202502/engagement_tasks/custom | Create a task with a custom message. Requires CUSTOM_MSG=true. | Customer Engagement - Write |
| Send Engagement Message | POST /customer_engagement/202412/messages | Send messages to one or more buyer_emails through an active task. | Customer Engagement - Write |
| Get Task Performances | POST /customer_engagement/202412/performances | Retrieve task performance metrics, such as sent recipients, reads, orders, GMV, and claimed coupons. | Customer Engagement - Read |
| Get Order Detail | GET /order/202309/orders | Retrieve buyer_email, the anonymized buyer email used as the Customer Engagement recipient identifier. | Order scopes |
| Search Products | POST /product/202502/products/search | Retrieve product IDs for product cards. | Product scopes |
| Search Coupons | POST /promotion/202406/coupons/search | Retrieve coupon IDs and coupon properties for coupon cards. | Promotion scopes |
| Get Coupon | GET /promotion/202406/coupons/{coupon_id} | Retrieve details for one coupon. | Promotion scopes |
§10 Key field terminology
| Field | Where it appears | Meaning |
|---|---|---|
buyer_email | Order APIs, such as Get Order Detail | The anonymized buyer email returned by TikTok Shop. It is not a normal contact email for direct external emailing. For Customer Engagement, use it as the buyer identifier. |
buyer_emails | Send Engagement Message request body | The list of anonymized buyer email values that should receive the message. |
task_id | Returned by task creation APIs and used by Send Engagement Message | The engagement task that groups related messages and performance. The task must still be active. |
template_id | Returned by Get Message Templates and used by Create Engagement Task | The TikTok Shop predefined message template selected for the task. |
end_time | Task creation APIs | Unix timestamp in seconds. After this time, the task cannot send more messages. |