Create Custom Engagement Task

POST

/customer_engagement/202502/engagement_tasks/custom

Create an engagement task that uses a self-defined custom message instead of predefined message templates from TikTok Shop. The task acts as a container for grouping messages with similar content and rules, allowing sellers to track and compare task performance across different types of content. Note that each task has a mandatory end time, and once expired, it cannot be used to send additional messages.

Authorizations

• accessToken

Parameters

Query Parameters

shop_cipher

required

string

Identifies the shop. Obtain it from the Get Authorized Shops API.

idempotency_key

required

string

A unique key to recognize a request and prevent duplicate processing of the same request, especially in cases of connection issues. Ensure this key is unique for each request to avoid accidental duplicates. Note: We recommend that you generate v4 UUIDs for use as keys.

Request Body^required

Media typeapplication/json

object

task_name

required

The name of the task. Length: 1–256 bytes when UTF-8 encoded.

string

end_time

required

The time at which the task ends, and messages will no longer be sent. Unix timestamp (seconds).

integer format: int64

channel

required

The engagement channel. Only TIKTOK_IM is supported.

string

product_ids

The product IDs that you want to include as interactive cards in the message. Retrieve this value from the Search Products API. Max count: 4

Array<string>

<= 4 items

coupon_ids

The coupon IDs that you want to include as interactive cards in the message. Max count: 1 You can only add coupons that have one of these sets of property:

• coupons.display_type=REGULAR and coupons.target_buyer_segment=ALL
• coupons.display_type=REGULAR and coupons.target_buyer_segment=REPEAT_CUSTOMERS. Find out the coupon ID and properties from the Search Coupons API.

Array<string>

<= 1 items

custom_message

The custom message to send to customers.

object

title

The message title.

• Valid format: plain text, unicode emoji (UTF-8)
• Valid length: 1–70 Unicode code points.

string

body

The message body.

• Valid format: plain text, unicode emoji (UTF-8)
• Valid length: 1–500 Unicode code points.

string

Example^generated

{
  "task_name": "example",
  "end_time": 1,
  "channel": "example",
  "product_ids": [
    "example"
  ],
  "coupon_ids": [
    "example"
  ],
  "custom_message": {
    "title": "example",
    "body": "example"
  }
}

Responses

200

Success

Media typeapplication/json

object

code

Status code; 0 means success.

integer format: int64

message

Success or failure message.

string

request_id

Request log ID.

string

data

object

task_id

The unique identifier for the customer engagement task. Pass this value in the Send Engagement Message API to associate the task with the message sending operation.

string

Example

{
  "code": 0,
  "data": {
    "task_id": "475910475643"
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}