This topic provides a quick reference for API integration with Outbound Bot. It describes how to use APIs to make task calls and receive automatic push callbacks for task results.
Integration guide
The phone line feature is not included with Outbound Bot and must be purchased separately. Outbound Bot supports integration with third-party providers and Alibaba Cloud Communications. A SIP fee is charged for integrating third-party phone lines.

API integration for task calls
Step 1: Get the instance ID and scenario ID
After you create an outbound instance and an outbound script as described in Business management, obtain the instance ID (InstanceId) and scenario ID (ScriptId) by following these steps:
Instance ID: In the Business Management section, find the business that you created and click Edit. The Instance ID is displayed.
Scenario ID: On the business page, go to the Scenario management tab and click Scenario ID next to the script scenario that you created.
Step 2: Create an outbound task
Call the CreateJobGroup - Create an outbound task group API to obtain the returned JobGroupId.
Step 3: Upload a list of outbound numbers
Call the AssignJobs - Create outbound tasks in batches API. In the call, pass the JobGroupId that you obtained and the list of callee numbers for the task.
Step 4: Get task results
Call the QueryJobsWithResult - Query tasks by result API to retrieve task results. The corresponding feature in the console is shown below:
Call the DescribeJob - Return the dialogue data of a job API to retrieve the call details for a single number. The corresponding feature in the console is shown below:
Call the DownloadRecording - Download a call recording API to download the recording. The corresponding feature in the console is shown below:
For more information about the Outbound Bot integration APIs, see API reference.
Automatic push callbacks for task results
Introduction to MQ
The Outbound Bot service uses Message Queue (MQ) for RocketMQ to send a notification to the caller about the completion status of each outbound task. The message contains the task ID and the status of the outbound task, such as connected, no answer, or call failed.
You must purchase the RocketMQ service from Alibaba Cloud. Outbound Bot currently supports RocketMQ 4.0, RocketMQ 5.0, and ROCKET_MQ_5_SERVERLESS. To use RocketMQ 4.0, you can use the self-service tool to add it to the allowlist.
Note: To connect to the MQ service, configure it in the System administration section of the Outbound Bot console. Enter the values for the MQ message queue configuration parameters. For more information, see Outbound system administration.
If you use RocketMQ 4.0, enter the following information:
Message Queue instance ID: Enter the instance ID of your MQ instance.
Topic: Enter the topic of the MQ service.
Endpoint: Enter the public TCP endpoint of the MQ service.
Access point type: Select NAMESRV_ADDR or ONS_ADDR as needed.
Authentication type: The default is AK/SK.
AccessKey: Enter the AccessKey of the MQ service.
SecretKey: Enter the SecretKey of the MQ service.
If you use RocketMQ 5.0, enter the following information:
Message Queue instance ID: Enter the instance ID of your MQ instance.
Topic: Enter the topic of the MQ service.
Endpoint: Enter the endpoint of the MQ service.
Access point type: Select NAMESRV_ADDR or ONS_ADDR as needed.
Authentication type: Username and password.
Username: Enter the username of the MQ service.
Password: Enter the password of the MQ service.
If you select ROCKET_MQ_5_SERVERLESS:
Message Queue instance ID: Enter the instance ID of your MQ instance.
Topic: Enter the topic of the MQ service.
Endpoint: Enter the public TCP endpoint of the MQ service.
Access point type: Select NAMESRV_ADDR or ONS_ADDR as needed.
Authentication type: Username and password.
Username: The username for the MQ service.
Password: Enter the password of the MQ service.
Recommended MQ SDK version
<dependency>
<groupId>com.aliyun.openservices</groupId>
<artifactId>ons-client</artifactId>
<version>1.8.8.Final</version
</dependency>
Activate and integrate MQ
To purchase RocketMQ, see the product page.
To subscribe to RocketMQ messages, see the ApsaraMQ for RocketMQ documentation.
For information about how to retrieve task completion information after you activate the MQ service, see Subscribe to messages and Use the TCP protocol SDK to send and receive normal messages.
MQ message types
Message level |
Message type |
EventType |
Task |
Task complete |
JobComplete |
Call |
Start call |
Dialing |
Call |
Call connected |
CallAnswered |
Call |
Call finished: hung up or unanswered timeout |
CallFinished |
Call |
Large Language Model label |
LabelReady |
Recording |
Recording generated successfully |
RecordingReady |
CallFinished message body
{
"contacts": [
{
"honorific": "259049",
"id": "d045421c-5c56-4e60-bd30-52621bd40358",
"name": "259049",
"phoneNumber": "1854625****",
"referenceId": "102553299"
}
],
"eventTime": 1732032007598,
"eventType": "CallAnswered",
"extras": [
{
"key": "TenantId",
"value": "1594349927946608"
},
{
"key": "ServiceId",
"value": "208983907113910398"
}
],
"groupId": "b842817b-3a8e-455e-974f-60a22c7181a8",
"id": "c18312d3-1e3a-4f07-a00a-bf92d3bcce87",
"instanceId": "e2d412ad-6571-43a7-9624-0d779fb80a9e",
"scriptId": "0e700dc9-39e9-4872-8cc8-0654d38c9615",
"tagHits": [
],
"task": {
"actualTime": 1732032007576,
"callId": "ee819df9f4e54e26a741591431534878",
"calledNumber": "1854625****",
"callingNumber": "0218045****",
"id": "88a26ac5-645e-4423-bb39-3d5943a27dc9",
"planedTime": 1732031999000,
"status": "Executing"
}
}
JobComplete message body
{
"contacts": [
{
"honorific": "259049",
"id": "d045421c-5c56-4e60-bd30-52621bd40358",
"name": "259049",
"phoneNumber": "185xxxxxxx",
"referenceId": "102553299"
}
],
"eventTime": 1732032015258,
"eventType": "JobComplete",
"extras": [
{
"key": "TenantId",
"value": "1594349927946608"
},
{
"key": "ServiceId",
"value": "208983907113910398"
}
],
"groupId": "b842817b-3a8e-455e-974f-60a22c7181a8",
"id": "c18312d3-1e3a-4f07-a00a-bf92d3bcce87",
"instanceId": "e2d412ad-6571-43a7-9624-0d779fb80a9e",
"scriptId": "0e700dc9-39e9-4872-8cc8-0654d38c9615",
"status": "Succeeded",
"tagHits": [
],
"tasks": [
{
"actualTime": 1732032008000,
"callId": "ee819df9f4e54e26a741591431534878",
"calledNumber": "185xxxxxxxx",
"callingNumber": "021xxxxxxxx",
"endTime": 1732032015000,
"hasLastPlaybackCompleted": true,
"id": "88a26ac5-645e-4423-bb39-3d5943a27dc9",
"planedTime": 1732031999000,
"realRingingDuration": 7,
"ringingDuration": 25,
"status": "Succeeded"
}
]
}
CallAnswered message body
{
"contacts": [
{
"honorific": "259049",
"id": "d045421c-5c56-4e60-bd30-52621bd40358",
"name": "259049",
"phoneNumber": "185xxxxxxxx",
"referenceId": "102553299"
}
],
"eventTime": 1732032007598,
"eventType": "CallAnswered",
"extras": [
{
"key": "TenantId",
"value": "1594349927946608"
},
{
"key": "ServiceId",
"value": "208983907113910398"
}
],
"groupId": "b842817b-3a8e-455e-974f-60a22c7181a8",
"id": "c18312d3-1e3a-4f07-a00a-bf92d3bcce87",
"instanceId": "e2d412ad-6571-43a7-9624-0d779fb80a9e",
"scriptId": "0e700dc9-39e9-4872-8cc8-0654d38c9615",
"tagHits": [
],
"task": {
"actualTime": 1732032007576,
"callId": "ee819df9f4e54e26a741591431534878",
"calledNumber": "185xxxxxxxx",
"callingNumber": "021xxxxxxxx",
"id": "88a26ac5-645e-4423-bb39-3d5943a27dc9",
"planedTime": 1732031999000,
"status": "Executing"
}
}
LabelReady message body
{
"eventTime": 1732087443211,
"eventType": "LabelReady",
"instanceId": "ae4572af-376f-439f-8970-38764acbaa91",
"jobId": "12964626-49a9-4da2-beec-783b94637aff",
"labelMap": {
"callSummary": "The user stated that the range hood has not arrived, so installation cannot be scheduled. Advise the user to contact the service center to confirm installation after the goods arrive.",
"realNumber": "Not triggered",
"oldApplianceRemovalRequired": "Not triggered",
"appointmentTime": "Not triggered",
"appointmentConfirmed": "Not triggered",
"addressModified": "Not triggered",
"goodsDelivered": "Not delivered",
"agentService": "Not triggered"
},
"scriptId": "a81f9147-ec4c-43d3-9dfa-e939a68b1d62",
"taskId": "4fb3a6b5-3468-4f35-b3eb-dfe9f31333d0"
}
RecordingReady message body
{
"eventType":"RecordingReady",
"eventTime":1588850490334,
"instanceId":"08a4c460-***-737e069a154f",
"groupId":"8869f35d-***-9b46437bc0fa",
"id":"08a4c460-***-737e069a154f",
"extras":[
{
"key":"custom",
"value":"aaa"
}
],
"contacts":[
{
"id":"762c2e16-***-00a0f13372b1",
"honorific":"test",
"name":"test",
"phoneNumber":"11111111",
"referenceId":"762c2e16-***-00a0f13372b1"
}
],
"recording":{
"taskId":"60b48efe-***-5d6b70479641",
"callId":"60b48efe-***-5d6b70479641",
"duration":5,
"fileName":"a.wav",
"mkvUrl":"https://a.wav",
"url":"https://a.wav"
}
}
Status enumerations
JobGroup status examples
-JobGroupStatus {
Draft(0), // Draft
Scheduling(1), // Scheduling
Executing(2), // Executing
Completed(3), // Completed
Paused(4), // Paused
Failed(5), // Failed
Cancelled(6), // Canceled
Initializing(7) // Initializing
}
Job status examples
-JobStatus {
Scheduling(0, "Scheduling"),
Executing(1, "Executing"),
Succeeded(2, "Finished - Reached"),
Paused(3, "Paused"),
Failed(4, "Finished - Not Reached"),
Cancelled(5, "Canceled - Manual intervention"),
Drafted(6, "Draft"),
}
Task status examples
-TaskStatus {
Executing(0, "Dialing"),
Succeeded(1, "Connected"),
NoAnswer(2, "Not connected - No answer"),
NotExist(3, "Not connected - Nonexistent number"),
Busy(4, "Not connected - Busy"),
Cancelled(5, "Not dialed - Task stopped"),
Failed(6, "Failed"),
NotConnected(7, "Not connected - Unreachable"),
PoweredOff(8, "Not connected - Powered off"),
OutOfService(9, "Not connected - Callee out of service"),
InArrears(10, "Not connected - Callee has overdue payment"),
EmptyNumber(11, "Not dialed - Nonexistent number not called"),
PerDayCallCountLimit(12, "Not dialed - Daily limit exceeded"),
ContactBlockList(13, "Not dialed - Blacklisted"),
CallerNotRegistered(14, "Not dialed - Caller number not registered"),
Terminated(15, "Not dialed - Terminated"),
VerificationCancelled(16, "Not dialed - Canceled due to failed pre-call verification"),
OutOfServiceNoCall(17, "Not dialed - Callee out of service, not called"),
InArrearsNoCall(18, "Not dialed - Callee has overdue payment, not called"),
CallingNumberNotExist(19, "Not dialed - Caller number does not exist"),
SucceededFinish(20, "Connected - Normal completion"),
SucceededChatbotHangUpAfterNoAnswer(21, "Connected - Bot hung up after rejection"),
SucceededChatbotHangUpAfterSilence(22, "Connected - Bot hung up after silence timeout"),
SucceededClientHangUpAfterNoAnswer(23, "Connected - User hung up after rejection"),
SucceededClientHangUp(24, "Connected - User hung up for no reason"),
SucceededTransferByIntent(25, "Connected - Transferred to agent on intent hit"),
SucceededTransferAfterNoAnswer(26, "Connected - Transferred to agent after rejection"),
SucceededInoInterAction(27, "Connected - No interaction from user"),
SucceededError(28, "Connected - Interrupted by system exception"),
SucceededSpecialInterceptVoiceAssistant(29, "Connected - Intercepted by special case - Voice assistant"),
SucceededSpecialInterceptExtensionNumberTransfer(30, "Connected - Intercepted by special case - Extension number transfer")
}
Job failure reason examples
-JobFailureReason
{
/**
* Unknown error
*/
Unknown(0),
/**
* No answer
*/
NoAnswer(1),
/**
* Invalid policy. The policy configuration is incorrect.
*/
InvalidStrategy(2),
/**
* Timeout detected during scheduling.
*/
TimeUp(3),
/**
* The policy is empty or not found.
*/
NoStrategy(4),
/**
* Call failed.
*/
CallFailed(5),
/**
* Daily call limit for the number reached.
*/
PerDayCallCountLimit(6),
/**
* Contact on blacklist.
*/
ContactBlockList(7),
/**
* Nonexistent number, not called again.
*/
EmptyNumber(8),
/**
* Daily call limit for the number reached.
*/
JobPerDayCallCountLimit(9),
/**
* Canceled due to failed pre-call verification.
*/
VerificationCancelled(10),
/**
* Calling suspended for the contact.
*/
ContactSuspended(11),
/**
* Overdue payment.
*/
InArrears(12),
/**
* Out of service.
*/
OutOfService(13),
/**
* Maximum number of task attempts reached. This takes effect when RepeatBy (@see) is None.
*/
NoneRepeatableJobMaxAttemptCountLimit(14);
}
Task status enumeration return conditions
The Dialing, LabelReady, and RecordingReady messages do not return a Task status value.
The Succeeded status is subdivided by reason. The status Succeeded: 1 (Connected) is not returned. Instead, a more specific reason type is returned.
Status code enumeration |
JobComplete |
CallAnswered |
CallFinished |
Executing(0, "Dialing") |
Returned |
Returned |
This operation does not return a value. |
Succeeded(1, "Connected") |
Not returned |
Not returned |
Not returned |
NoAnswer(2, "Not connected - No answer") |
Returned |
Not returned |
Returned |
NotExist(3, "Not connected - Nonexistent number") |
Returned |
Not returned |
Returned |
Busy(4, "Not connected - Busy") |
Returned |
Not returned |
Returned |
Cancelled(5, "Not dialed - Task stopped") |
Returned |
Not returned |
Not returned |
Failed(6, "Failed") |
Returned |
None |
Returned |
NotConnected(7, "Not connected - Unreachable") |
Returned |
Not returned |
Returned |
PoweredOff(8, "Not connected - Powered off") |
Returned |
Not returned |
Returned |
OutOfService(9, "Not connected - Callee out of service") |
Returned |
Not returned |
Returned |
InArrears(10, "Not connected - Callee has overdue payment") |
Returned |
Not returned |
Returned |
EmptyNumber(11, "Not dialed - Nonexistent number not called") |
Returned |
Not returned |
Not returned |
PerDayCallCountLimit(12, "Not dialed - Daily limit exceeded") |
Returned |
Not returned |
Not returned |
ContactBlockList(13, "Not dialed - Blacklisted") |
Returned |
Not returned |
Not returned |
CallerNotRegistered(14, "Not dialed - Caller number not registered") |
Returned |
Not returned |
Not returned |
Terminated(15, "Not dialed - Terminated") |
Returned |
Not returned |
Not returned |
VerificationCancelled(16, "Not dialed - Canceled due to failed pre-call verification") |
Not returned |
Not returned |
None |
OutOfServiceNoCall(17, "Not dialed - Callee out of service, not called") |
Not returned |
Not returned |
Not returned |
InArrearsNoCall(18, "Not dialed - Callee has overdue payment, not called") |
Returned |
Not returned |
No value is returned. |
CallingNumberNotExist(19, "Not dialed - Caller number does not exist") |
Returned |
Not returned |
Not returned |
SucceededFinish(20, "Connected - Normal completion") |
Returned |
Not returned |
Returned |
SucceededChatbotHangUpAfterNoAnswer(21, "Connected - Bot hung up after rejection") |
Returned |
Not returned |
Returned |
SucceededChatbotHangUpAfterSilence(22, "Connected - Bot hung up after silence timeout") |
Returned |
Not returned |
Returned |
SucceededClientHangUpAfterNoAnswer(23, "Connected - User hung up after rejection") |
Returned |
Not returned |
Returned |
SucceededClientHangUp(24, "Connected - User hung up for no reason") |
Returned |
Not returned |
Returned |
SucceededTransferByIntent (25, "Connected - Transferred to agent on intent hit") |
Returned |
Not returned |
Returned |
SucceededTransferAfterNoAnswer (26, "Connected - Transferred to agent after rejection") |
Returned |
Not returned |
Returned |
SucceededInoInterAction(27, "Connected - No interaction from user") |
Returned |
Not returned |
Returned |
SucceededError(28, "Connected - Interrupted by system exception") |
Returned |
Not returned |
Returned |
SucceededSpecialInterceptVoiceAssistant(29, "Connected - Intercepted by special case - Voice assistant") |
Returned |
Not returned |
Returned |
SucceededSpecialInterceptExtensionNumberTransfer(30, "Connected - Intercepted by special case - Extension number transfer") |
Returned |
Not returned |
Returned |