Quick integration

更新时间:
复制 MD 格式

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

Important

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.

image

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:

  1. Instance ID: In the Business Management section, find the business that you created and click Edit. The Instance ID is displayed.

  2. 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

Note
  • 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