来自 TikTok Shop 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Overview
This guide is for Customer Service apps built by third-party Independent Service Vendors (ISVs) or seller self-developed teams. It explains the required app capabilities, API access prerequisites, and the recommended end-to-end implementation flow for receiving buyer messages, loading conversation context, and replying from a third-party customer support system.
Recommended document title: Customer Service app features.
Recommended slug: customer-service-app-features. Avoid using the generic slug app-features, because this page is specific to the Customer Service category and can be confused with app feature requirements for other categories.
Updated: July 7, 2026. API availability, scope names, and review requirements should be checked against the latest Partner Center UI before publishing.
§2 About Customer Service
Customer Service is the communication channel used by sellers and buyers during pre-sale, in-sale, and after-sale support. After integration, TikTok Shop buyer messages can be forwarded to a third-party customer support system. Agents can then receive, read, and reply to buyer messages without logging in to Seller Center for every conversation. Image Customer Service APIs support capabilities such as:
- Listing and retrieving conversations.
- Reading historical conversation messages.
- Marking messages as read.
- Sending text, image, video, product card, order card, return/refund card, coupon card, and logistics card messages.
- Uploading buyer message images before sending image messages.
- Retrieving and tracking customer service performance metrics.
- Using customer service webhooks, such as New conversation and New message, to receive new-message events.
§3 Apply For Customer Service API Access
Customer Service is a category-specific API capability in TikTok Shop Partner Center. It is visible to partners or ISVs who have selected Customer Service as the business category in Category & Market and as the service category for the app or service. Customer Service API access is inactive by default. The app owner must apply for access and complete review before calling Customer Service APIs. Image Recommended application path:
| Step | Partner Center entry | What to do |
|---|---|---|
| 1 | App & Service or My Account | Confirm that the partner account or service category includes Customer Service for the target market. |
| 2 | Category & Market | Select or update the Customer Service business category and market, if the category is not already approved. |
| 3 | App/service detail page > API Scopes or Access scope | Find the Customer Service scope package and submit the access request. See Access scope. |
| 4 | Account Manager, Partner Manager, or Partner Center support ticket | If the Customer Service scope remains inactive or is not visible, submit the app key/service ID, target market, Customer Service use cases, and launch timeline for review. |
Approval time is not fixed in the source material. Treat this as a manual Account Manager or Partner Manager review, plan for several business days, and confirm the expected timeline with the review owner before committing a launch date. Do not publish a fixed SLA unless the owning operations team confirms it.
Scope ID check before publishing: the source table lists Customer Service (48004). Local OAS files confirm the Customer Service endpoints but do not confirm the scope ID. Because 48004 has a different length from many other scope IDs, verify the exact scope name and ID in Partner Center before publishing this page. Do not infer or rewrite the ID without owner confirmation.
§4 Main Message Flow
暂时无法在飞书文档外展示此内容
| Phase | API or event | Implementation note |
|---|---|---|
| Connect shop | Seller authorization and shop connection use cases | Store the authorized shop and shop cipher before calling Customer Service APIs. |
| Receive event | New conversation or New message webhook | Use the event to identify the shop, buyer, conversation, and message context. |
| Load conversation | Get Conversations and Get Conversation Messages | Retrieve the conversation list and historical messages needed by the support agent. |
| Mark read | Read Message | Call before or during agent handling so the buyer can see that the seller has read the message. |
| Load context | Product, order, logistics, return/refund, and coupon APIs | Load product cards, order cards, shipping status, after-sale records, and eligible coupons as needed. |
| Reply | Send Message | Send each message type separately. Do not combine text, image, product card, and coupon card in one message call. |
| Measure | Get Customer Service Performance | Track response rate, response time, satisfaction, and month-over-month trends where available. |
§5 Key Implementation Constraints
| Constraint | Requirement |
|---|---|
| Combined messages | The existing Send Message API cannot send combined messages. Each message type must be transmitted individually. For example, text plus image plus coupon card requires three separate Send Message calls. |
| Message content format | Send Message uses a type field and a JSON-serialized content string. The content schema depends on the message type. |
| Images | Upload the image first with Upload Buyer Messages Image, then use the returned image URL in the image message content. |
| Return/refund card | Before sending a return/refund card, verify eligibility with Get Aftersale Eligibility. |
| Coupon card | Before sending a coupon card, search for valid coupons with Search Coupons. Eligible coupons should meet the display type, status, creation source, and buyer segment conditions described in the API reference. |
| Shop identifier | Customer Service APIs include shop_cipher in query parameters. It is optional for most Customer Service endpoints but required by Get Customer Service Performance. For cross-border shops, pass the correct shop identifier to avoid incorrect responses. |
| Access token | Customer Service endpoints require x-tts-access-token in the request header. Also send Content-Type: application/json for JSON requests. |
§6 Required Use Cases
#§7 Shop Connection
Shop Connection
| Use case | Required | Summary | Scope |
|---|---|---|---|
| SHOP-CONN-SINGLE | Yes | Connect one store from the platform to one TikTok Shop. | Shop Authorized Information (431812); Global Shop Information (431300) |
| SHOP-CONN-MULTI | No | Connect one store from the platform to multiple TikTok Shops. | Shop Authorized Information (431812); Global Shop Information (431300) |
| SHOP-DISCON-SINGLE | Yes | Disconnect one store from one TikTok Shop. | Shop Authorized Information (431812); Global Shop Information (431300) |
| SHOP-MAN-MULTI | Yes | Manage shop connections by adding new ones or removing existing ones. | Shop Authorized Information (431812); Global Shop Information (431300) |
| SHOP-MAN-WHOOK | Yes | Use the Upcoming Authorization Expiration webhook to notify sellers to reauthorize their shop connection. | Shop Authorized Information (431812); Global Shop Information (431300) |
| SHOP-MAN-CARRIER | Yes | Map shipping carriers on the platform to the corresponding carriers on TikTok Shop. | Shop Authorized Information (431812); Global Shop Information (431300) |
§8 Inbound Messages
Inbound Messages
| Use case | Required | Summary | Recommended API reference |
|---|---|---|---|
| CS-INMSG-TXT | Yes | Receive buyer plain-text messages and display multiple paragraphs in their original format. | Get Conversation Messages |
| CS-INMSG-VID | Yes | Receive video messages and allow agents to preview and play the video. | Get Conversation Messages |
| CS-INMSG-IMG | Yes | Receive image messages and allow agents to view the image. | Get Conversation Messages |
| CS-INMSG-EMOJI | Yes | Receive buyer messages that contain emojis. | Get Conversation Messages |
| CS-INMSG-PROD | Yes | Receive product-card messages and load product details for display. | Get Product |
| CS-INMSG-ORD | Yes | Receive order-card messages and load order details for display. | Get Order Detail |
| CS-INMSG-HIST | Yes | Retrieve buyer historical conversation messages when needed. | Get Conversation Messages |
| CS-INMSG-READ | Yes | Notify the buyer when the seller reads the message. | Read Message |
§9 Outbound Messages
Outbound Messages
| Use case | Required | Summary | Recommended API reference |
|---|---|---|---|
| CS-OUTMSG-TXT | Yes | Send a plain-text message to the buyer. | Send Message |
| CS-OUTMSG-IMG | Yes | Send an image to the buyer. | Upload Buyer Messages Image; Send Message |
| CS-OUTMSG-PROD | Yes | Send one or multiple product cards to the buyer. | Send Message |
| CS-OUTMSG-ORD | Yes | Send a specific order card to a buyer. The seller can retrieve recent buyer order information before sending the card. | Get Order List; Get Order Detail; Send Message |
| CS-OUTMSG-RRCARD | No | Send a return/refund card at order or SKU level when after-sale conditions are met. | Get Aftersale Eligibility; Send Message |
| CS-OUTMSG-COUPON | No | Search eligible coupons and send a coupon card to the buyer using coupon_id. | Search Coupons; Send Message |
§10 Context Data
Context Data
| Use case | Required | Summary | Recommended API reference |
|---|---|---|---|
| CS-DATA-PRODLIST | Yes | Load the active product list for the shop. Obtain shop_id from New conversation or New message, then call the product endpoint required by the product reference. | Get Product |
| CS-DATA-PRODSRCH | Yes | Search product details by product ID when a product-card message is received. | Get Product |
| CS-DATA-ORDNFO | Yes | Load buyer order information when receiving an order-card message or preparing to send an order card. | Get Conversations; Get Order Detail |
| CS-DATA-ORDSHIP | No | Show logistics information for each package when an order is split into multiple packages. | Get Order Detail; Get Package Detail; Get Tracking |
| CS-DATA-ORDRET | No | Retrieve cancellation, return, and refund records for the buyer or order to improve support context. | Get Order List; Search Cancellations; Search Returns |
| CS-DATA-ORDSRCH | No | Search order details by order ID from a buyer inbound message. | Get Order Detail |
§11 Engagement And Performance
Engagement And Performance
| Use case | Required | Summary | Recommended API reference |
|---|---|---|---|
| CS-ENG-ORD | No | Use order history to understand buyer behavior, purchase history, products purchased, and amount paid. | Get Order List; Get Order Detail |
| CS-ENG-BMSG | No | Send after-sale, promotional, or marketing messages to one or more buyers where allowed by policy and API capability. | Send Message |
| CS-ENG-CSPERF | No | Access customer service performance data for specific time periods and monitor month-over-month trends. | Get Customer Service Performance |
§12 Field Mapping Reference
Use the field-mapping style below when writing use case requirements. It gives developers both the recommended display fields and the API source for each field.
| Scenario | API source | Recommended fields to display |
|---|---|---|
| Product card received from buyer | Get Product | Product ID; title; price; status; main image, using the first image returned by the API. For multi-SKU products, show each SKU line with price and inventory. |
| Order card received from buyer | Get Order Detail | Order ID; order status; order create_time; total amount; product name; SKU name and quantity. Aggregate the quantity of the same SKU. |
| Buyer order context | Get Conversations; Get Order Detail | Use user_id from the conversation context to load the buyer's related order details where supported. |
| Package and shipping context | Get Order Detail; Get Package Detail; Get Tracking | Package ID; package status; shipping provider name; tracking number; latest tracking event. |
| Cancellation context | Search Cancellations | Cancellation status; cancellation initiator role; cancellation reason; creation time; refund amount. |
| Return/refund context | Search Returns | Return order ID; return type; return status; return reason text; initiator role; creation time; shipment type; return provider name; return tracking number; item image; product name; item name; amount; refund amount. |
| Coupon card | Search Coupons; Send Message | Coupon type; range; validity period; discount; qualification threshold; coupon ID used to send the card. |
§13 Customer Service API Reference
The local OAS reference lists the following Customer Service endpoints. Confirm exact endpoint documentation links and scope availability in Partner Center before publishing.
| Capability | Method and path | Notes |
|---|---|---|
| Get agent settings | GET /customer_service/202309/agents/settings | Query agent settings for the authorized shop. |
| Update agent settings | PUT /customer_service/202309/agents/settings | Update agent settings for the authorized shop. |
| Get conversations | GET /customer_service/202309/conversations | Retrieve conversation list. |
| Create conversation | POST /customer_service/202309/conversations | Start a conversation when allowed for the order and buyer context. |
| Get conversation messages | GET /customer_service/202309/conversations/{conversation_id}/messages | Retrieve historical messages for a conversation. |
| Send message | POST /customer_service/202309/conversations/{conversation_id}/messages | Supported message types include TEXT, IMAGE, VIDEO, PRODUCT_CARD, ORDER_CARD, RETURN_REFUND_CARD, COUPON_CARD, and LOGISTICS_CARD. |
| Read message | POST /customer_service/202309/conversations/{conversation_id}/messages/read | Mark messages as read. |
| Upload buyer messages image | POST /customer_service/202309/images/upload | Upload an image before sending an image message. |
| Get customer service performance | GET /customer_service/202407/performance | Requires shop_cipher. Use for performance tracking where enabled. |
| Get conversation | GET /customer_service/202601/conversations/{conversation_id} | Retrieve one conversation. |
变化记录
相对上一发布版本，本文内容有变化。
本版没有改过这篇（或它是新增页），没有可比的上一版。