AI Agent Task Create

Create Outbound Task

Create an AI Agent outbound task. You can either create an empty task first and import contacts later, or submit the initial contact list together with the task.

---

API Information

• URL: https://api-hk.nxlink.ai/openapi/aiagent/task/create
• Method: POST
• Content-Type: application/json
• Authentication Required: Yes

---

🌐 Service Endpoints

NXLink is deployed across multiple global regions. Please select the appropriate service endpoint based on your business location.

Code	Region	NXLink Website	API Gateway
APAC	Hong Kong	https://app.nxlink.ai	https://api-hk.nxlink.ai
AMER	Americas	https://chl-nxlink.nxcloud.com	https://chl-api.nxlink.ai
APAC(IDN)	Indonesia	https://idn.nxlink.ai	https://api-idn.nxlink.ai

---

Request Parameters

Header Parameters

Parameter	Type	Required	Example Value	Description
accessKey	String	Yes	AK-6230339248928541113-2133	User identity identifier
ts	String	Yes	1655710885431	Current request timestamp in milliseconds. The server allows a maximum time difference of 60 seconds
bizType	String	Yes	100	Business type. Fixed value: 100
action	String	Yes	nxai	Business action. Fixed value: nxai
sign	String	Yes	6e9506557d1f289501d333ee2c365826	API request signature. See common conventions, Signature Algorithm

---

Body Parameters

Parameter	Type	Required	Example Value	Description
userTaskId	String	No	"EXT-TASK-202603250001"	User-defined task ID. A globally unique value is recommended for reconciliation and querying
other	String	No	"task-batch-20260325"	Task passthrough field. The same value is returned in the task status callback and task list API
taskName	String	Yes	"Customer Follow-up Task 0325"	Task name
taskDesc	String	No	"Customer satisfaction follow-up after purchase"	Task description
autoFlowId	Long	Yes	197	AI Agent ID. You can obtain it from List AI Agents
routeId	String	Yes	"y29ND1X4kkCG_nC576sALEkvg3HjEqde"	Route ID. You can obtain it from List Routes
taskKeep	Integer	Yes	0	Keep-alive flag: 0 = disabled, 1 = enabled
startupType	Integer	Yes	1	Startup type: 1 = manual, 2 = scheduled, 3 = immediate
startupAt	Long	No	1746583929	Required when startupType = 2; scheduled start timestamp in seconds
shutdownAt	Long	No	1746670329	Scheduled stop timestamp in seconds; omit if no stop time is needed
zoneSecond	Integer	Yes	28800	Task timezone offset in seconds. Example: UTC+8 = 28800
weekDay	String	Yes	"1,2,3,4,5,6,7"	Allowed dialing weekdays separated by commas. 1 = Monday, ..., 7 = Sunday
firstFifteen	String	Yes	"9,10,11,14,15,16,17"	Allowed hours for the first 15-minute slot of each hour, corresponding to HH:00~HH:15
secondFifteen	String	Yes	"9,10,11,14,15,16,17"	Allowed hours for the second 15-minute slot of each hour, corresponding to HH:15~HH:30
thirdFifteen	String	Yes	"9,10,11,14,15,16,17"	Allowed hours for the third 15-minute slot of each hour, corresponding to HH:30~HH:45
fourthFifteen	String	Yes	"9,10,11,14,15,16,17"	Allowed hours for the fourth 15-minute slot of each hour, corresponding to HH:45~HH+1:00
orderMaxCall	Integer	Yes	1	Maximum redial attempts per contact
replayInterval	Integer	Yes	600	Redial interval in seconds. For example, 10 minutes = 600
maxCall	Integer	No	20	Maximum concurrent calls. 0 means the system default behavior is used
maxRingTime	Integer	No	40	Maximum ringing time in seconds. 0 means the system default behavior is used
taskCallbackUrl	String	No	"https://example.com/webhook/task"	Callback URL for task status changes
callCallbackUrl	String	No	"https://example.com/webhook/call"	Callback URL when a call ends. The API value takes priority. If omitted, the page configuration is used. If neither is configured, no callback is sent
countryCode	String	No	"86"	Default country code. Use this when phone numbers in callList do not include the country code
callList	Array	No		Initial contact list imported during task creation. Omit or pass an empty array to create an empty task first and import contacts later

---

Contact Object (callList Element)

Parameter	Type	Required	Example Value	Description
contactId	String	Yes	"52145b00-abc9-4a87-94c2-ed1e1e42x4rfvmh"	Contact ID (globally unique)
other	String	No	"contact-ext-001"	Contact passthrough field. The same value is returned in the call record callback
name	String	Yes	"Jones"	Contact name
phoneNumber	String	Yes	"13800000001"	Phone number
params	Array	No		Variable list

---

Variable Object (params Element)

Parameter	Type	Required	Example Value	Description
name	String	Yes	"customerName"	Variable name. It must match an existing variable defined in the workflow
value	Object	No	"Lucy"	Variable value

---

Startup Type (startupType) Reference

Value	Description
1	Manual
2	Scheduled
3	Immediate

---

Dialing Window Fields

Field	Value Range	Description
weekDay	1~7	Allowed weekdays, where 1 = Monday and 7 = Sunday
firstFifteen	0~23	00~15 minutes of each hour
secondFifteen	0~23	15~30 minutes of each hour
thirdFifteen	0~23	30~45 minutes of each hour
fourthFifteen	0~23	45~60 minutes of each hour

---

Notes

1. If you only want to create an empty task, omit callList or pass an empty array, then import contacts later through the append-contacts API.

---

Request Example

{
  "userTaskId": "EXT-TASK-202603250001",
  "other": "task-batch-20260325",
  "taskName": "Customer Follow-up Task 0325",
  "taskDesc": "Customer satisfaction follow-up after purchase",
  "autoFlowId": 197,
  "routeId": "y29ND1X4kkCG_nC576sALEkvg3HjEqde",
  "taskKeep": 0,
  "startupType": 2,
  "startupAt": 1746583929,
  "shutdownAt": 1746670329,
  "zoneSecond": 28800,
  "weekDay": "1,2,3,4,5,6,7",
  "firstFifteen": "9,10,11,14,15,16,17",
  "secondFifteen": "9,10,11,14,15,16,17",
  "thirdFifteen": "9,10,11,14,15,16,17",
  "fourthFifteen": "9,10,11,14,15,16,17",
  "orderMaxCall": 1,
  "replayInterval": 600,
  "maxCall": 20,
  "maxRingTime": 40,
  "taskCallbackUrl": "https://example.com/webhook/task",
  "callCallbackUrl": "https://example.com/webhook/call",
  "countryCode": "86",
  "callList": [
    {
      "contactId": "c3d79370-9f3a-4da2-84dd-2d2200f40e11",
      "other": "contact-ext-001",
      "name": "Lucy",
      "phoneNumber": "13800000001",
      "params": [
        {
          "name": "customerName",
          "value": "Lucy"
        },
        {
          "name": "orderNo",
          "value": "SO202603250001"
        }
      ]
    },
    {
      "contactId": "5f6f6f6f-7a7b-4c4d-9e9f-101010101010",
      "other": "contact-ext-002",
      "name": "Tom",
      "phoneNumber": "13800000002",
      "params": [
        {
          "name": "customerName",
          "value": "Tom"
        }
      ]
    }
  ]
}

Response Parameters

Parameter	Type	Description
code	Integer	Result code
message	String	Result message
traceId	String	Trace ID for request tracking
data	Object	Response payload

---

data Object

Parameter	Type	Description
taskId	String	Created task ID
userTaskId	String	User-defined task ID
taskStatus	Integer	Task status. 1 = Ready, 2 = In Progress, 3 = Completed, 4 = Failed, 5 = Paused, 6 = Paused (Insufficient Balance)
successCount	Integer	Number of successfully imported contacts
totalCount	Integer	Total number of processed contacts
errList	Array	Error list containing records that failed to be imported

---

errList Element

Parameter	Type	Description
contactId	String	Contact ID of the failed record. This is the primary identifier for the error item
name	String	Contact name
phoneNumber	String	Phone number that failed to be imported
errMsg	String	Failure reason

---

Response Examples

Success Example

{
  "code": 0,
  "message": "success",
  "traceId": "3287f5aa-b8db-4dd7-97b0-03fabac2f4c7",
  "data": {
    "taskId": "52145b00-abc9-4a87-94c2-ed1e1e42ec1c",
    "userTaskId": "EXT-TASK-202603250001",
    "taskStatus": 1,
    "successCount": 2,
    "totalCount": 2,
    "errList": []
  }
}

Partial Import Failure Example

{
  "code": 0,
  "message": "success",
  "traceId": "dbdd93a9-cb7c-4c0d-8f98-01755b1883b6",
  "data": {
    "taskId": "52145b00-abc9-4a87-94c2-ed1e1e42ec1c",
    "userTaskId": "EXT-TASK-202603250001",
    "taskStatus": 1,
    "successCount": 1,
    "totalCount": 2,
    "errList": [
      {
        "contactId": "5f6f6f6f-7a7b-4c4d-9e9f-101010101010",
        "name": "lucy",
        "phoneNumber": "1312895-xxx",
        "errMsg": "Illegal phone number format:1312895-xxx"
      }
    ]
  }
}

Failure Example

{
  "code": 20000,
  "message": "autoFlowId not found",
  "traceId": "8a731fe8-81b0-4a7f-9785-b214977e30ef"
}

Error Codes

Code	Description
1001	Authentication failed (missing public parameters)
1002	Authentication failed (parameter error)
1003	Authentication failed (invalid signature)
1004	Authentication failed (timestamp expired)
1005	Authentication failed (insufficient authority)
20000	Business Error