Skip to main content

Message Script Configuration

This page documents the configuration parameters for the message script used in task creation.

Overview​

The message script is used to automatically send direct messages to users on TikTok or Instagram. When you provide multiple target users via API, one task is created per target user. You can control when each task executes using the start_time parameter.

Script Configuration (script_config)​

The script_config object contains the parameters for the message script. Below are the available parameters:

Parameters​

ParameterTypeRequiredDefaultDescription
target_usersstring[]Yes*[]Array of target usernames to message (one task per user)
target_userstringYes*""Single target username or multiple usernames separated by newlines/commas
message_contentstringYes""Message text content to send
access_methodstringNo"direct"How to navigate to user profile: direct (via URL) or search
note

Either target_users array or target_user string must be provided. If both are provided, target_users takes priority.

Task Creation

When multiple target users are provided, the API creates one task per target user. For example, if you specify 3 target users and 2 devices, 6 tasks will be created. Use the start_time parameter to control when tasks start executing.

Examples​

Send Message to Single User​

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1"],
    "script_name": "message",
    "script_config": {
      "target_users": ["@username_to_message"],
      "message_content": "Hello! Check out our latest content.",
      "access_method": "direct"
    }
  }'

Send Message to Multiple Users​

When messaging multiple users, one task is created per user:

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1"],
    "script_name": "message",
    "script_config": {
      "target_users": ["@user1", "@user2", "@user3"],
      "message_content": "Hi! We have an exclusive offer for you."
    }
  }'

This creates 3 separate tasks that execute immediately.

Schedule Messages with Start Time​

Use start_time to schedule when tasks should start:

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1"],
    "script_name": "message",
    "script_config": {
      "target_users": ["@user1", "@user2"],
      "message_content": "Scheduled greeting!"
    },
    "start_time": "14:30"
  }'

Send Message via Search Method​

Use the search method when direct URL access is not working:

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1"],
    "script_name": "message",
    "script_config": {
      "target_users": ["username1", "username2"],
      "message_content": "Hello from TikMatrix!",
      "access_method": "search"
    }
  }'

Send Message by Username List Mode​

Create message tasks directly for specific accounts:

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["@my_account1", "@my_account2"],
    "script_name": "message",
    "script_config": {
      "target_users": ["@target_user"],
      "message_content": "Hi there!"
    }
  }'

Batch Message on Multiple Devices​

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_1", "device_2", "device_3"],
    "script_name": "message",
    "script_config": {
      "target_users": ["@influencer_account"],
      "message_content": "Love your content! Let's collaborate."
    },
    "enable_multi_account": true
  }'

Instagram Message Example​

The same API works for Instagram direct messages:

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1"],
    "script_name": "message",
    "script_config": {
      "target_user": "instagram_username",
      "message_content": "Hey! Loved your post 📸"
    }
  }'

Response​

{
  "code": 0,
  "message": "success",
  "data": {
    "task_ids": [501, 502, 503],
    "created_count": 3
  }
}

Access Methods​

Direct Method (direct)​

  • Opens user profile via URL: tiktok.com/@username or instagram.com/username
  • Faster and more reliable
  • Recommended for most use cases
  • Navigates to search, types username, clicks on result
  • Slower but works when direct URL access is blocked
  • May be less accurate if multiple similar usernames exist

Best Practices​

  1. Use start_time for scheduling: Use the start_time parameter to schedule when tasks should execute (format: "HH:MM").

  2. Prefer direct access: The direct access method is faster and more reliable than search.

  3. Personalize your messages: Customize the message_content to make messages feel personal and engaging.

  4. Respect platform limits: Don't create too many message tasks at once. Most platforms have rate limits on direct messaging.

Error Codes​

CodeDescription
40001Missing target users or message content
40003Script not supported via API
40301API access requires Pro+ plan

See Also​