Callbot API createTaskAndCall

callbot-api

v1.0.0

Base URLs:

• Production Environment: https://nxbot.nxcloud.com

aibot External API v3.0/Task Operations

Authentication Method

For authentication, please refer to the documentation at https://github.com/nxtele/http-api-document/wiki/Callbot-API-authorization

POST Create and Start Call

POST /callcentre/api/v3/createAndCall

Create a task and add orders

Response Code Enumeration

Response Code	Error Reason
0	Success
1	General Error
2	Missing Parameters
3	Parameter Format Error
4	Invalid Parameter Value
4001	Parameter Content Capacity Error (Too many array elements)
5	Server Maintenance
5001	Internal Server Error
6	Incorrect Signature
6001	Missing Signature Error
6001	Missing Signature Error
6002	Account Does Not Exist
6003	User Does Not Have Permission
7	System Busy

Request Body

{
  "productID": "callbot",
  "userTaskID": "string",
  "sceneID": "string",
  "taskCreateSetting": {
    "strategyName": "",
    "startupType": 1,
    "startupAt": 0,
    "zoneSecond": 0,
    "dialAtWeekDay": "string",
    "dialAtUpHour": "string",
    "dialAtDownHour": "string",
    "maxCall": 0,
    "taskName": "string",
    "taskCallbackUrl": "string",
    "maxRingTime": 0,
    "routeID": "",
    "manualCallSetting": {
      "agentGroup": "string",
      "dispatchType": 0,
      "ratioCallRate": 0,
      "predictCallRate": 0
    }
  },
  "funcFlag": {
    "taskKeep": false,
    "roundRedial": false,
    "wholeTTS": false,
    "smsEnable": false,
    "smsFuncFlag": [
      {
        "smsID": "string",
        "intentID": [
          "string"
        ],
        "intentName": [
          "string"
        ]
      }
    ],
    "phoneEncrypt": true
  },
  "callInfoList": {
    "orderCallbackUrl": "string",
    "callCallbackUrl": "string",
    "callList": [
      {
        "orderID": "string",
        "userPhone": "string",
        "other": "string",
        "userName": "string",
        "customerName": "string",
        "params": [
          {
            "name": null,
            "value": null
          }
        ]
      }
    ]
  }
}

Request Parameters

Name	Position	Type	Required	Description
requestID	header	string	Yes	Unique request ID
uuid	header	string	Yes	UUID, please log in to the platform, click on Developer Authorization
createTs	header	string	Yes	Request timestamp (in seconds)
sign	header	string	Yes	Signature
algorithm	header	string	No	Signature algorithm: MD5 or SHA256, default to MD5 if left blank
body	body	object	No	None
» productID	body	string	Yes	Fixed value: "callbot"
» userTaskID	body	string	Yes	Task ID generated by the requester (ensure uniqueness, recommended to use UUID)
» sceneID	body	string	Yes	Scenario template ID, log in to the background, select "Scenario Management," and choose the corresponding template name to view
» taskCreateSetting	body	object	Yes	Task parameter settings
»» strategyName	body	string	Yes	Strategy name; log in to the aibot platform -> Scenario Management -> Scenario (find the corresponding scenario, click on the scenario name or click edit) -> click Dialing Strategy (top right corner) to view the strategy name; this field can be used by default (default strategy); if you need to set other dialing strategies, please set a new strategy name on the aibot platform
»» startupType	body	integer	Yes	Startup strategy
»» startupAt	body	integer	Yes	When startupType=2, the timestamp when the task starts
»» zoneSecond	body	integer	Yes	Task working timezone, the offset value in seconds relative to the zero time, for example, for UTC+8, its value is 8 * 3600 = 28800, for UTC-8, its value is -8 * 3600 = -28800
»» dialAtWeekDay	body	string	Yes	For the task working time range, multiple values are separated by commas in English, the value range is [1,7], 1: Monday,...6: Saturday, 7: Sunday
»» dialAtUpHour	body	string	Yes	Multiple values are separated by commas. For the task working time range, the value range is [0,23], 0: [00:00 ~ 00:30] can be dialed, 1: [01:00 ~ 01:30] can be dialed,...23: [23:00 ~ 23:30] can be dialed
»» dialAtDownHour	body	string	Yes	Multiple values are separated by commas. For the task working time range, the value range is [0,23], 0: [00:30 ~ 01:00] can be dialed, 1: [01:30 ~ 02:00] can be dialed,...23: [23:30 ~ 24:00] can be dialed
»» maxCall	body	integer	Yes	Maximum number of concurrent calls
»» taskName	body	string	Yes	Task name
»» taskCallbackUrl	body	string	Yes	URL type, callback when the task status changes
»» maxRingTime	body	integer	Yes	Maximum ringing duration
»» routeID	body	string	Yes	route ID
»» manualCallSetting	body	object	No	Used only for AICC templates
»»» agentGroup	body	string	Yes	Agent group ID
»»» dispatchType	body	integer	Yes	Outbound call type, 0: none, 1: ratio-based outbound call, 3: pre-test outbound call 2.0
»»» ratioCallRate	body	number	Yes	Agent call rate (fill in this value for ratio-based outbound call)
»»» predictCallRate	body	number	Yes	Predicted call rate (fill in this value for pre-test outbound call)
» funcFlag	body	object	Yes	Task function flag
»» taskKeep	body	boolean	Yes	When enabled, the task will not automatically end even if there are no call orders in the task
»» roundRedial	body	boolean	Yes	When enabled, unanswered calls within a round will be automatically redialed once
»» wholeTTS	body	boolean	Yes	When enabled, sentences with variables will be treated as a whole for TTS synthesis. When there are variables, this must be enabled
»» smsEnable	body	boolean	Yes	true for enabled. After the call order of the task ends, a message will be sent based on the set intention (SMS service needs to be activated in advance, and an appKey needs to be set)
»» smsFuncFlag	body	[object]	Yes	Used when smsEnable is true, fill in the relevant fields as SMS sending conditions. Please do not repeat the intentID, otherwise it will be overridden in the order of the array
»»» smsID	body	string	Yes	The SMS template to be sent can be found through the SMS template (please contact customer service for SMS copy testing and delivery rate testing before sending SMS templates)
»»» intentID	body	[string]	Yes	After the call order ends, an SMS will be sent based on the set intention ID
»»» intentName	body	[string]	Yes	After the call order ends, an SMS will be sent based on the set intention name (the effect is the same as setting intentId)
»» phoneEncrypt	body	boolean	Yes	When enabled, the numbers displayed in the background will be displayed as encrypted numbers
» callInfoList	body	object	Yes	none
»» orderCallbackUrl	body	string	Yes	Callback address after the call order is completed
»» callCallbackUrl	body	string	Yes	Callback address after the call is completed
»» callList	body	[object]	Yes	Each number represents an order, and each order will go through one or more rounds of calls
»»» orderID	body	string	Yes	Generated by the caller and globally unique. Recommended to use UUID
»»» userPhone	body	string	Yes	With the user's mobile phone area code, without symbols, such as 86156xxxxxxxx
»»» other	body	string	Yes	Transparent field
»»» userName	body	string	Yes	Can be an empty string
»»» customerName	body	string	Yes	Can be an empty string
»»» params	body	[object]	Yes	If the script template contains variables, all variables must be filled in. You can query the template name through Script Management -> Variable Settings and enter the corresponding string value according to the variable type
»»»» name	body	string	Yes	Variable name
»»»» value	body	string	Yes	Variable value

Enumerated Values

Property	Value	Description
»» startupType	1	Manual
»» startupType	2	Scheduled
»» startupType	3	Immediate

Example Response

200 Response

{
  "retCode": 0,
  "retMsg": "string",
  "responseID": "string",
  "taskID": "string",
  "totalCount": 0,
  "successCount": 0,
  "errList": [
    {
      "phone": "string",
      "errMsg": "string"
    }
  ]
}

Response

Status Code	Status Code Meaning	Description	Data Model
200	OK	Success	Inline

Response header

Name	Type	Required	Description
requestID	string	Yes	Consistent with the request header
uuid	string	Yes	Consistent with the request header
createTs	string	Yes	Second level timestamp at response time
sign	string	Yes	The generation method is the same as the sign generation algorithm in the request header
algorithm	string	No	Consistent with the request header, signature algorithm: MD5 or SHA256, default to MD5 if not filled in

Response Data Structure

Status Code 200

Name	Type	Required	Constraints	Description
» retCode	integer	true	none	Response code,0 for success, others for failure
» retMsg	string	true	none	Response message
» responseID	string	true	none	A randomly generated unique ID used for request tracking and issue resolution
» taskID	string	true	none	The actual task ID returned by the callee
» totalCount	integer	true	none	Total count
» successCount	integer	true	none	Success count
» errList	[object]	false	none	Error list
»» phone	string	true	none	Failed phone
»» errMsg	string	true	none	Failure reason