logo
  • Home
  • API
  • Third-Party Integration
  • Chatbot
  • CallCenter PaaS API
  • Voicebot

Create Automatic Callout Task

This interface is used to create an automatic callout task.

Request Method

POST /cc_ad_tasks

Request Parameters

Attribute NameTypeRequiredDescription
nameStringYesName of the callout task
descriptionStringNoDescription of the callout task
task_typeIntegerYesType of the callout task, see Task Type
user_group_idIntegerYesCustomer service group ID for the callout task
force_policy_idIntegerNoRouting policy ID, determines which intelligent routing to use for this phone. Default routing
priorityIntegerNoPriority (1-100), default 10
working_time_idIntegerNoTask execution time period work time ID
recall_policyStringNoTypes of call results that trigger redial, see Data Structure - Call Result Type List
recall_countIntegerNoNumber of redials, default 0
recall_intervalStringNoRedial interval, format "1,2,3" first 60 seconds, second 120 seconds, third 180 seconds, default 600 seconds
follow_on_policyStringNoTypes of call results that trigger follow-up calls, see Data Structure - Call Result Type List
callout_numberStringNoRelay number (outbound display number)
call_limitStringNoNumber of tasks in parallel, cannot exceed the number of tasks concurrently limited by callout_number

Response Data

Attribute NameTypeDescription
codeIntegerExecution result code, 1000 represents success
idIntegerCallout task ID

Example

curl https://demo.udesk.cn/open_api_v1/cc_ad_tasks?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X POST \
-H 'content-type: application/json' \
-d '
{
    "name": "Callout Task",
    "description": "This is a callout task",
    "task_type": 1,
    "user_group_id": 100,
    "force_policy_id": 1,
    "priority": 10,
    "working_time_id": 1,
    "recall_policy": "customer_missed",
    "recall_count": 6,
    "recall_interval": "1,2,3,4,5,6",
    "follow_on_policy": "customer_missed",
    "callout_number": "021002002020",
    "call_limit": "10"
}'

Response

{
  "code": 1000,
  "id": 1
}

Update Automatic Callout Task

This interface is used to update the name and description of an automatic callout task.

Request Method

PUT /cc_ad_tasks/:id

Request Parameters

Attribute NameRequiredDescription
nameYesCallout task name
descriptionNoCallout task description
callout_numberNoRelay number (outbound display number)
call_limitNoNumber of tasks in parallel

Response Data

Attribute NameTypeDescription
codeIntegerExecution result code, 1000 represents success

Example

curl https://demo.udesk.cn/open_api_v1/cc_ad_tasks/1?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X PUT \
-H 'content-type: application/json' \
-d '
{
    "name": "Modified Callout Task",
    "description": "This is the modified callout task",
    "callout_number": "021002002020",
    "call_limit": "10"
}'

Response

{
  "code": 1000
}

Get Automatic Callout Task List

This interface is used to obtain an automatic callout task list.

Request Method

GET /cc_ad_tasks

Request Parameters

Parameter NameRequiredDescription
pageNoPagination page number, starting from 1, default to 1
per_pageNoNumber of items per page, default to 10, max to 100

Response Data

Attribute NameTypeDescription
codeIntegerExecution result code, 1000 represents success
cc_ad_tasksArrayAutomatic callout task information, see Data Structure - Automatic Callout Task
metaObjectPagination information, see General Data

Example

curl https://demo.udesk.cn/open_api_v1/cc_ad_tasks?page=1&per_page=10&email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

Response

{
  "code": "1000",
  "cc_ad_tasks": [
  {
    "id": 1,
    "name": "Automatic Callout",
    "description": "Description of automatic callout task",
    "task_type": 2,
    "user_group_id": 100,
    "customer_count": 100000,
    "callout_number": "057126200039",
    "created_at": "2017-10-21 11:22:33",
    "status": 1,
    "execute_customer_count": 100000,
    "customer_answer_count": 100000,
    "agent_answer_count": 100000,
    "call_success_rate": "1.0",
    "agent_answer_rate": "1.0",
    "agent_use_rate": "1.0",
"disturb_rate": "0.0",
"minute_call_rate": "1.0",
"minute_agent_use_rate": "1.0",
"minute_disturb_rate": "0.0"
}
],
"meta": {
"current_page": 1,
"total_pages":1,
"total_entries": 1
}
}

Get Automatic Callout Task Details

This interface is used to query the details of a single callout task.

Request Method

GET /cc_ad_tasks/:id

Response Data

Attribute NameTypeDescription
codeIntegerExecution result code, 1000 represents success
itemObjectCallout task information, see Data Structure - Automatic Callout Task Details

Example

curl https://demo.udesk.cn/open_api_v1/cc_ad_tasks/1?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

Response

{
    "code": 1000,
    "item": {
        "id": 16,
        "name": "Waiting for callout",
        "status": 2,
        "call_limit": 10,
        "callout_number": "05712620039",
        "task_type": 1,
        "force_policy_id": 45,
        "user_group_id": 323,
        "description": null,
        "created_at": "2017-11-02T20:13:40.000+08:00",
        "schedule_id": null,
        "redial_times": 0,
        "redial_guide": ["1", "1"],
        "redial_scene": ["phone_busy", "phone_outline"],
        "redial_multi_scene": ["phone_busy"],
        "priority": 10,
        "force_policy_name": "Automatic callout",
        "schedule_name": null,
        "customer_count": 2,
        "execute_customer_count": 6,
        "customer_answer_count": 0,
        "agent_answer_count": 0,
        "call_success_rate": "0.0",
        "agent_answer_rate": "0",
        "agent_use_rate": "0.0",
        "disturb_rate": "0",
        "minute_call_rate": "1.0",
        "minute_agent_use_rate": "0.0",
        "minute_disturb_rate": "0.0"
    }
}

Import Numbers for Automatic Callout Task

This interface is used to add numbers to a specified automatic callout task. Up to 300 numbers can be imported each time, and the calling frequency should not exceed 1 time per second.

Request Method

POST /cc_ad_tasks/add_numbers

Content Type

application/json

Request Parameters

Attribute NameRequiredTypeDescription
idYesIntegerAutomatic callout task ID
numbersYesArrayArray of numbers to add, see Data Structure - Import Automatic Callout Number Structure

Response Data

Attribute NameTypeDescription
codeIntegerExecution result code, 1000 represents success
successful_countIntegerNumber of successfully imported numbers
unsuccessful_countIntegerNumber of unsuccessfully imported numbers
unsuccessful_numbersArrayList of unsuccessfully imported numbers, see Data Structure - Import Failed Number Structure

Example

curl https://demo.udesk.cn/open_api_v1/cc_ad_tasks/add_numbers?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X POST \
-H 'content-type: application/json' \
-d '
{
  "id": 1,
  "numbers": [
    {"cellphone": "13223004567", "name": "Test number 1", "description": "Number description 1"},
    {"cellphone": "13223004568", "name": "Test number 2", "description": "Number description 2"},
    {"cellphone": "13223004569", "name": "Test number 3", "description": "Number description 3",
     "custom": {"company": "Udesk", "address": "Beijing City"}
    }
  ]
}'

Response

{
  "code": 1000,
  "successful_count": 3,
  "unsuccessful_count": 0,
  "unsuccessful_numbers": []
}

Notes

  • Automatic callout tasks can only add numbers when they are closed.
  • Please note the number pool quota: Each API import is limited to adding up to 300 numbers, each automatic callout task is limited to 1 million numbers, and each company is limited to 10 million numbers.
  • The frequency of adding numbers API calls should not exceed 1 time per second.

Get Automatic Callout Task Number Pool

This interface is used to return the number pool list for a specified automatic callout task, with a maximum of 500 records returned each time.

Request Method

GET /cc_ad_tasks/numbers

Request Parameters

Parameter NameRequiredTypeDescription
idYesIntegerAutomatic callout task ID
start_number_idNoIntegerStarting number pool number ID, default to 0, note: only return numbers with an ID greater than this value

Response Data

Attribute NameTypeDescription
codeIntegerExecution result code, 1000 represents success
numbersArrayReturned number list details, see Data Structure - Number Pool Structure
metaObjectAdditional information, see Data Structure - Number Pool Additional Information

Example

curl https://demo.udesk.cn/open_api_v1/cc_ad_tasks/numbers?id=12292&start_number_id=2&email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

Response

{
  "code": 1000,
  "numbers": [
    {
      "id": 3,
      "name": "Test Number 3",
      "cellphone": "13989001200",
      "description": "Description of Number 3",
      "call_count": 0,
      "customer_answer_count": 0,
      "agent_answer_count": 0
    },
    {
      "id": 14,
      "name": "Test Number 14",
      "cellphone": "13989001201",
      "description": "Description of Number 14",
      "call_count": 0,
      "customer_answer_count": 0,
      "agent_answer_count": 0
    }
  ],
  "meta": {
    "record_size": 2,
    "max_number_id": 14
  }
}

Automatic Callout Task Number Redial

This interface is used to redial a specific number for an automatic callout task.

Request Method

POST /cc_ad_tasks/recall

Request Parameters

Parameter NameRequiredTypeDescription
idYesIntegerCallout task ID
numberYesStringRedial phone number
after_atYesStringRedial start time, format YYYY-MM-DDTHH:MM:SSZ

Response Data

Attribute NameTypeDescription
codeIntegerExecution result code, 1000 represents success
messageStringExecution result explanation

Example

curl https://demo.udesk.cn/open_api_v1/cc_ad_tasks/recall?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X POST \
-H 'content-type: application/json' \
-d '
{
  "id":1,
  "number":"13412341234",
  "after_at":"2019-02-08T15:30:02+08:00"
}'

Response

{
  "code": 1000,
  "message": "Redial successful"
}

Automatic Callout Task Number Follow-up

This interface is used to initiate a follow-up call for a specific number in an automatic callout task.

Request Method

POST /cc_ad_tasks/follow_on

Request Parameters

Parameter NameRequiredTypeDescription
idYesIntegerCallout task ID
calledYesStringAlready dialed phone number

Response Data

Attribute NameTypeDescription
codeIntegerExecution result code, 1000 represents success
messageStringExecution result explanation

Example

curl https://demo.udesk.cn/open_api_v1/cc_ad_tasks/follow_on?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X POST \
-H 'content-type: application/json' \
-d '
{
    "id": 1,
    "called": "13223004570"
}'

Response

{
  "code": 1000,
  "message": "Follow-up successful"
}

Outbound Call Task Start/Stop

Request Method

POST /cc_ad_tasks/:id/open

Request Parameters

Parameter NameRequiredTypeDescription
openYesBooleantrue/false
callout_numberNoStringRelay number

Response

Attribute NameTypeDescription
codeIntegerResult code, 1000 represents success
messageStringResult explanation

Example

curl https://demo.udesk.cn/open_api_v1/cc_ad_tasks/1/open?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X POST \
-H 'content-type: application/json' \
-d '
{
    "open": true/false,
    "callout_number": "01086465047"
}'

Response

{
  "code": 1000
}

Data Structure - Automatic Outbound Call Task

AttributeDescriptionExampleType
idTask ID1Integer
nameTask Name'Automatic Outbound Call'String
descriptionTask Description'This is an automatic outbound call task'String
task_typeTask Type1Integer
callout_numberOutbound Call Number"01086465047"String
user_group_idCustomer Service Group ID100Integer
customer_countNumber of Customers100000Integer
created_atCreation Time'2017-11-22 10:32:33'DateTime
statusStatus1Integer
execute_customer_countExecuted Count100000Integer
customer_answer_countCustomer Answer Count100000Integer
agent_answer_countAgent Answer Count100000Integer
call_success_rateOutbound Call Success Rate'0.67'String
agent_answer_rateAgent Answer Rate'0.32'String
disturb_rateDisturbance Rate'0.0'String
agent_use_rateAgent Utilization Rate'1.0'String
minute_call_rate10-Minute Connection Rate'1.0'String
minute_agent_use_rate10-Minute Disturbance Rate'1.0'String
minute_disturb_rate10-Minute Agent Utilization Rate'1.0'String

Task Type Description (task_type)

ValueChinese Name
1Precision Outbound Call
2Proportion Outbound Call
3Predictive Outbound Call
4Simple IVR (Voice Broadcast, No Queue)

Status Description (status)

ValueChinese Name
1Enabled
2Disabled
3Stopping

Data Structure - Import Automatic Outbound Call Numbers

AttributeTypeDescriptionRequired
cellphoneStringPhone number, multiple numbers can be separated by commasYes
nameStringNameNo
descriptionStringDescriptionNo
customObjectCustom data, see the structure in Data Structure - Custom Data for Importing Automatic Outbound Call NumbersNo

Data Structure - Failed Import Number Structure

AttributeTypeDescription
cellphoneStringPhone number
nameStringName
descriptionStringDescription
customObjectCustom data
reasonStringReason for failure

Data Structure - Number Pool Structure

AttributeTypeDescription
idIntegerNumber ID
nameStringName
cellphoneStringPhone number
descriptionStringDescription
call_countIntegerNumber of calls
customer_answer_countIntegerNumber of times the customer answered
agent_answer_countIntegerNumber of times the agent answered

Data Structure - Additional Number Pool Information

AttributeTypeDescription
record_sizeIntegerThe number of numbers returned in the current request
max_number_idIntegerThe maximum number ID returned in the current request (null when record_size is 0), can be used as the start_number_id for the next request

Data Structure - Custom Data for Importing Automatic Outbound Call Numbers

The number of custom fields cannot exceed 10.

AttributeTypeDescriptionRequired
Field 1StringThe field name can be customizedYes
Field 2StringThe field name can be customizedNo
Field 3StringThe field name can be customizedNo
....StringThe field name can be customizedNo
Field 10StringThe field name can be customizedNo

Data Structure - Call Result Type List

ValueChinese Name
customer_missedCustomer Missed
agent_missedAgent Missed
customer_breakoutCustomer Breakout
phone_outlinePhone Offline
phone_busyPhone Busy

Data Structure - Automatic Outbound Call Task Details

AttributeDescriptionExampleType
idTask ID1Integer
nameTask Name'Automatic Outbound Call'String
statusStatus1Integer
call_limitConcurrent Call Limit1Integer
callout_numberOutbound Call Number"01086465047"String
task_typeTask Type1Integer
force_policy_idRouting Policy ID1Integer
user_group_idCustomer Service Group ID100Integer
descriptionTask Description'This is an automatic outbound call task'String
created_atCreation Time'2017-11-22 10:32:33'DateTime
schedule_idWork Time ID1Integer
redial_timesRedial Attempts0Integer
redial_guideRedial Interval["1", "1"]Array
redial_sceneRedial Policy["phone_busy", "phone_outline"]Array
redial_multi_sceneContinuation Call Policy["phone_busy"]Array
priorityPriority10Integer
force_policy_nameRouting Policy Name"Automatic Outbound Call"String
schedule_nameWork Time Name"Work Time"String
customer_countNumber of Customers100000Integer
execute_customer_countExecuted Count100000Integer
customer_answer_countCustomer Answer Count100000Integer
agent_answer_countAgent Answer Count100000Integer
call_success_rateOutbound Call Success Rate'0.67'String
agent_answer_rateAgent Answer Rate'0.32'String
disturb_rateDisturbance Rate'0.0'String
agent_use_rateAgent Utilization Rate'1.0'String
minute_call_rate10-Minute Connection Rate'1.0'String
minute_agent_use_rate10-Minute Disturbance Rate'1.0'String
minute_disturb_rate10-Minute Agent Utilization Rate'1.0'String

Error Code Description

Error CodeMessageException:messageDescription
2000Unknown errorunknown attribute: working_time_idParameter {working_time_id} is empty
undefined method `size' for nil:NilClassRequired parameter {numbers} not imported or is empty
2005Resource not foundCouldn't find CcAdTask with id=12 [WHERE cc_ad_tasks.company_id = ?]Parameter {id} is incorrect, no matching value found
Couldn't find CcAdTask without an IDParameter {id} is incorrect, no matching value found
206203Invalid task_type(Message omitted)Required parameter {task_type} not filled out or value is out of range
206204Invalid user_group_id(Message omitted)Required parameter {user_group_id} not filled out or value is out of range
206205Invalid name(Message omitted)Required parameter {name} not filled out or value is out of range
206206Invalid force_policy_id(Message omitted)Parameter {force_policy_id} value is out of range
206207Invalid working_time_id(Message omitted)Parameter {force_policy_id} value is out of range
501004Cannot import numbers for a task that is starting(Message omitted)The automatic outbound call task is in the starting state
501015Parameter open cannot be empty and must be true/false(Message omitted)Parameter {open} value is not true or false within the specified range
501016The task is already closing, no need to close again(Message omitted)The automatic outbound call task is already in the closed state
501032Invalid number(Message omitted)Required parameter {number} not filled out or value is out of range
501033Incorrect redial start time format(Message omitted)Required parameter {after_at} not filled out or format is incorrect
501035Automatic outbound call task is starting, no need to start again(Message omitted)The automatic outbound call task is already in the started state
503001(Continued)(Message omitted)The value of parameter {callout_number} is incorrect, not within the specified range
503002Does not meet the current concurrent call limit for the dialing number(Message omitted)The value of parameter {call_limit} exceeds the concurrent call limit of the corresponding relay number
marketing@udeskglobal.com
service@udeskglobal.com

Products

Solutions

Resources