Customer Service API overview
Customer Service API overview
Context
Customer Service refers to the communication channel used by the customer service of the sellers and buyers to communicate information about the whole process of pre-sale, in-sale and after-sale.
Once the integration is done using Customer Service API, the messages from your TikTok Shop buyers will be forwarded to third party customer support system. This eliminates the need to log in to Seller Center to manage buyer messages, and allows customer service agents to reply to messages directly on their Customer support platform. This article is applicable to Third-party Independent Service Vendors (hereinafter referred to as ISV) or self-developed merchants who access the TiKTok Shop Customer Service functions.
Customer Service is available in TTSPC as custom API.
Customer Service is a custom API available in TTSPC, visible to partners/ ISVs who have selected Customer Service as the business category in 'Category & Market' and service category in 'app or service', however it requires specific approval based on the following conditions:
If the partner has 1000 or more authorized sellers, or it has any API scope call to count towards the 1 million per day threshold, then it can gain access to the CS API scope. The exception is that if this seller has the "TikTok Shop Seller" APP category, which means that this seller self-owns development team, we can give it special approval.
Sellers can authorize third-party software or systems to use the Customer Service open interface to obtain Customer Service data and functions through the authorization page of the workbench.
The Customer Service open interface will provide capabilities including: Customer Service session list, session status, sending pictures, etc., and support merchants to receive and reply to consumer TTS Customer Service messages on third-party systems.
With the Customer Service API you can build applications that send messages to buyers, obtaining session lists, session messages, new event hooks, obtaining and setting customer service agent status. You can get a list of message types that are available for an order that you specify, then call the operation that creates a new conversation to send a message to the buyer for that order. By integrating Customer Service Open API with your third party systems, you will centralize your customer support efforts, maintain better control over communication and provide consistent experience for your customers.
Seller Side Overview
NOTE: Please refer to the Developer Guide before integration for complete platform onboarding and app creation, and understand api call & authorization notice.
Customer Service API Operations and Webhooks
| Operations |
|---|
| Get Conversation Messages |
| Get Conversations |
| Send Message |
| Get Agent Settings |
| Update Agent Settings |
| Upload Buyer Messages Image |
| Read Message |
| Create Conversation |
| Webhooks |
| New Conversation |
| New Message |
Important Concepts
Conversation - A conversation is an exchange between the buyer and the shop. Conversations can occur in real-time and across channels when necessary, but can be picked back up without losing context or history. A conversation can be started with a message and it can have threaded messages.
Message - A message is a single instance of communication between the buyer and the seller.
Chat message response window for conversation auto-close.
- In a chat conversation, if the buyer does not reply, the conversation will be closed after 6 hours.
- The seller customer service has 7 days to respond to a chat message. If customer service does not reply, the conversation is auto-closed for non-response.
To initiate a conversation with a buyer, one of the following three criteria must be satisfied:
- There should have been a prior conversation between the buyer and the shop within the last 30 days.
- The buyer should have placed an order at the shop within the past 60 days.
- The buyer should have a history of returns or refunds at the shop.
| Definition of roles in "Particpant" | |
|---|---|
| BUYER | The buyer communicates with the seller by sending a message on the TikTok messaging app. |
| SHOP | The shop is the seller business owner on TikTok marketplace. Shop is the main account which also has the customer service role. The owner account is the only one supported in the Customer Service API for integration with CS partners. |
| CUSTOMER_SERVICE | The customer support agent of the seller who is assigned to the conversation. If a seller has multiple customer service agents, then their conversations are passed as the main account to the buyer by the Customer Service API. |
| Example scenarios: |
- When the buyer starts a conversation, 2 participants are in this group chat: the BUYER and the SHOP.
- If there is customer service serving this customer, there will be 3 members: BUYER, SHOP and CUSTOMER SERIVCE.
- Once this conversation is done, the CUSTOMER_SERVICE will leave the group chat.
| Definition of roles in "Sender" | |
|---|---|
| BUYER | indicates that the message is sent by buyer. |
| CUSTOMER_SERVICE | indicates that the message is sent by agent |
| SHOP | Auto-Reply and FAQs are sent via the Shop. |
| SYSTEM | indicates this message is a system message. Normally this kind of message will be sent via the user "SHOP", and the sender is marked as "SYSTEM", to indicate that this message is a "system message". |
| ROBOT | When the seller enables "Chat Bot" in seller center, some auto-reply may be triggered once the buyer has entered some kind of questions. This kind of message will be sent via user "SHOP" or "CUSTOMER_SERVICE", and the sender is marked as "ROBOT", to indicate that this message is triggered by our smart tools |
| Customer Service user identifiers | |
|---|---|
| im_user_id | This is the internal Customer Service participant ID. This ID can not be used to query orders. For querying orders, use buyer_user_id instead. |
| buyer_user_id | This is the buyer's user ID. User_id in Customer Service API is the same as the buyer_user_id in Order API. You can fetch orders of a buyer who reached out to you via chat using "buyer_user_id." Please use buyer_user_id to query for buyers in any external domain. |
TikTok Shop Marketplace Policies
It is very important to reply to buyer's messages in a timely manner. We recommend that sellers reply to buyers within 24 hours because replying to messages promptly:
- allows sellers to resolve any doubts that customers may have and improves customers' willingness to buy, improve conversion rates.
- helps customers get a better understanding of products, reducing the likelihood of returns or refunds.
- leads to customer satisfaction with shop service and reduces the number of complaints.
Key Performance Indicators and Targets
We encourage sellers to have direct, professional, and efficient communication when responding to customers. All the messages sent through TikTok Shop's Buyer Messages must comply with the response times set out in this policy. Sellers should note that TikTok Shop will evaluate them based on their customer service response time.
Any customer queries that are handled by TikTok Shop will not impact seller performance metrics. Only tickets that are routed to sellers will be used to calculate a seller's performance.
The table below outlines the response time sellers must abide by when responding to customers.
| Metric | Definition | Seller Target | |
|---|---|---|---|
| Seller Response Efficiency | 24-Hour response rate | Number of chats responded within 24 hours/Total number of chats received (over the last 30 calendar days) | ≥80% |
| Resolution Rate | Number of Chats marked as resolved / Total number of chats received (over the last 30 calendar days) | ≥65% | |
| Customer Satisfaction | Customer Satisfaction Rating | Number of chats with ratings of 4 and 5 / Total chats that received ratings (over the last 30 calendar days) | ≥75% |
| Review the TikTok Shop customer service policy at TikTok academy here. |
Customer Service API Approval Rule
Who should apply
This API is intended for Merchants or ISVs building their own customer support tools that integrate TikTok Shop conversations.
If you only need basic order synchronization or catalog management, other APIs may be more appropriate. The Customer Service API is specifically for chat-based customer support scenarios.
Important: This document only covers onboarding & approval rules. API reference, endpoints, and technical details are documented separately.
Eligibility Requirements
All applicants must meet the minimum eligibility criteria below before submitting an application for the Customer Service API.
Active in-app chat window
You must already have an active in-app chat window (merchant–buyer chat interface) in your product.
What this means
- Your product must provide a user-visible chat interface where:
Agents or merchants can respond to buyer messages Buyers can see replies and follow up within the same conversation Your product must provide a user-visible chat interface
where: - Agents or merchants can respond to buyer messages
- Buyers can see replies and follow up within the same conversation
for example
What will be reviewed
- UI/UX of the chat screen
- Ability to send and receive messages in real time
- Basic conversation history display (recent messages, timestamps, participants)
To pass review, you must submit full screenshots and a screen recording of your existing in-app chat window. Partial or cropped screenshots are often considered insufficient.
Pre-integrated core capabilities (Order / Fulfillment / After-Sales)
Before applying for the Customer Service API, your product is expected to have already integrated (or be clearly ready to integrate) the core operational capabilities that typical customer service flows depend on:
- Order – basic order information, order details, and order status
- Fulfillment – shipment, delivery status, and related logistics information
- After-Sales (Returns & Refunds) – return requests, refund status, and related tickets
Why this is requiredCustomer service agents typically need order, fulfillment, and after-sales context in the same interface as the chat window to resolve issues efficiently. The API onboarding will verify that your product can:
- Display order information linked to the conversation
- Surface fulfillment / shipment status when relevant
- Show after-sales / returns / refund status as part of the support workflow
What will be reviewed
- Whether your product has UI surfaces or workflows that:
Display orders associated with a buyer or ticket Show shipment / delivery status Reflect returns and refunds status for the relevant order Whether your product has UI surfaces
or workflows
that: - Display orders associated with a buyer or ticket
-
Show shipment / delivery status
-
Reflect returns and refunds status for the relevant order
-
Whether your integration design makes it practical for agents to use these capabilities during a live conversation.
Partner Scale & API Usage
Partners can be granted access to the Customer Service API if they meet either of the following criteria:
- Have 1,000 or more authorized sellers; OR
- Reach the threshold of 1 million API calls per day.
Exception: If the seller belongs to the "TikTok Shop Seller" app category (indicating they have their own development team), special approval may be granted.
Common Rejection Reasons & How to Resolve
This section summarizes the most common reasons why Customer Service API applications are rejected, and what you should do to fix them before re-applying.
| Rejection reason | How to fix | What to resubmit |
|---|---|---|
| Insufficient chat window evidence | * Provide uncropped, full-page screenshots of the in-app chat window * Include at least one realistic conversation (test data acceptable) * Add a short screen recording showing the full send/receive flow | * Full chat interface screenshots (conversation list & detail) * New screen recording (30–90s) showing actual messages being sent and received |
| "Core capability integration not demonstrated" | * Make sure your product visibly surfaces Order / Fulfillment / After-Sales information in customer service flows * Add or expose UI panels that show order details, shipment status, and returns/refunds status * Document how agents use these features while chatting with buyers | * Screenshots of order details UI linked to conversations * Screenshots of shipment / delivery status screens * Screenshots of returns/refunds views * Short written explanation for each capability area |
| User base threshold not met | Ensure you meet the 1,000 users requirement and provide clear quantification. | Dashboard screenshots showing the relevant user metric. |
Frequently Asked Questions
When can I re-apply after a rejection?
- Typically, you can re-apply after you have fully addressed the rejection reasons.
Can we apply if our chat window is still under development?
- The Customer Service API is intended for products with a live, functioning in-app chat window.
- If your chat experience is still a mock or prototype, we recommend finishing the implementation first.
Can we apply if we have not yet integrated all core capabilities (Order / Fulfillment / After-Sales)?
- The expectation is that these capabilities are already integrated or clearly in place before approval.
When can Seller Customer Support initiate a new conversation with a buyer?
Sellers can reach out to buyers who have ordered from them.
To initiate a conversation with a buyer, one of the following three criteria must be satisfied:
- There should have been a prior conversation between the buyer and the shop within the last 30 days.
- The buyer should have placed an order at the shop within the past 60 days.
- The buyer should have a history of returns or refunds at the shop.
What message types are supported in TTS Customer Service API?
| Message type | Customer Service API Support | Description |
|---|---|---|
| Text | Yes | No more than 2000 characters |
| Image | Yes | Up to 10 MB |
| emoji (static) | Yes | |
| emoji (animation) | Yes | |
| Video | Yes | Up to 100MB |
| Product card | Yes | Product ID |
| Order card | Yes | Order ID |
| Logistic card | Yes | Tracking Number and Logistics Service Provider Name, Estimated Delivery Date, Latest Logistics Status, Product Image and Title, Quantity & Price Info |
| Order Reverse card | Yes | Return/Refund Request |
| Coupon card | Yes | |
| Return/Refund Status card | Not supported | |
| FAQ Card | Not supported | |
| Hyperlinks | Not supported | |
| Attachments | Not Supported |
Current support shows msg type
| msg type | is support |
|---|---|
| text | Yes |
| file_image | Yes |
| allocated_service | Yes |
| notification | Yes |
| user_enter_from_transfer | Yes |
| user_enter_from_goods | Yes |
| user_enter_from_order | Yes |
| goods_card | Yes |
| emoticons | Yes |
| order_card | Yes |
| video | Yes |
| invite_comment_v2 | No |
| card | No |
| interactive_system_message | No |
| card_greeting | No |
| message_greeting_question_answer | No |
| message_greeting_question | No |
| message_greeting_question_answer_image | No |
| order_reverse_card | Yes |
| system_button | No |
| select_order | No |
| coupon_card | Yes |
| order_logistics_card | Yes |
| return_refund_status_card | No |
What are some of the gaps between Customer Service API and TTS Seller Center.
| Feature | TTS Shop Chat | Customer Service API | Note on Customer Service API |
|---|---|---|---|
| Send messages | ✅ | ✅ | |
| List conversation | ✅ | ✅ | |
| Get conversation messages | ✅ | ✅ | Get messages by messageID and conversation details by ConversationID supported in Customer Service API V3.0 |
| Customer status | ✅ | ✅ | |
| Update customer status | ✅ | ✅ | |
| Agent Work Status | ✅ | ✅ | |
| Customer Service Hook * New Conversation Started * New Message Received * sender id/sender role/message | ✅ | ✅ | |
| Mark Read | ✅ | ✅ | |
| Start new conversation with Buyer | ✅ | ✅ | |
| Smart Tools | ✅ | ❌ | |
| Chat details | ✅ | ❌ | |
| Chat Assistant | ✅ | ❌ | CS Platforms may have their own or may prefer to use their own Chatbot/FAQ. |
| Add Notes | ✅ | ❌ | |
| Customer satisfaction review | ✅ | ❌ | Buyer satisfaction data is calculated by TTS and available in Seller Center. |
| FAQ and Auto Reply | ✅ | ❌ | "FAQ and Auto Reply" has to be configured and enabled by Sellers in TTS first to be used in Chat API. CS Platforms may have their own or may prefer to use their own Chatbot/FAQ. |
| Order Management | ✅ | ❌ | This can be achieved by Order API to enable the support agents to see the list of orders per buyer in 3P CS platforms. |
| Tagging | ✅ | ❌ | CS Platforms may have their own tagging features. |
| Translation functions (such as English to Chinese) for crossborder sellers in TTS | ✅ | ❌ | |
| Merchant's product list by name / SKU | ✅ | ❌ | This can be achieved by /api/products/search in Product API to enable the Support agents to search for products in Seller catalog to reference in chat channel. |
| Conversation Monitoring | ✅ | ❌ | |
| Service Data | ✅ | ❌ |
Receive and respond to buyer messages via email.
TikTok Shop sellers now have the ability to service their users, and receive and reply to buyer messages via email. Additionally, they can set up message integration through third-party customer service platforms like Salesforce, Zendesk, or Gorgias, which utilize email-to-case or similar functions. This means that buyer messages will be compiled and sent to sellers via email, and sellers can respond directly to the email, with the buyer receiving the response within TikTok.
Is service data supported in the Customer Service API?
Service data is currently not supported in the Customer Service API.
Service data refers to the personal data of this customer service agent.
- 24h response rate: The number of chats inquired by customers responded within 24 hours divided by the total number of chats inquired by customers within the last 7 days.
- Satisfaction rate: the satisfaction of buyers served by customer service today, the formula = the number of sessions that customers evaluated as 'satisfied' and 'very satisfied' divided by the number of sessions that buyers have evaluated.
- Sessions today: The number of sessions initiated by consumers allocated to this customer service today.
Is this content helpful?Helpful
Not Helpful
PreviousNext