Adding an Outbound Campaign (V2)

Scenario

This interface is invoked to add a predicted, intelligent, automatic, previewed, or preempted outbound campaign.

The V2 version is recommended. It supports the adding of the outbound call retry policy, call policy, and business result policy. Only one interface is required to add the data related to an outbound campaign task. The interface for setting the outbound campaign retry policy does not need to be invoked.

Usage Description

Prerequisites
- You have applied for a developer account.
- For intelligent outbound calls, the customer needs to develop the IVR. For details, see Configuring Intelligent IVR.
Restrictions
- Only 20 outbound campaign tasks whose device type is skill queue can be created.
- Only 20 outbound campaign tasks whose device type is IVR can be created.
  
  The number of active outbound campaign tasks of the same type of a tenant cannot be greater than a specified value. The value is specified by max.liveliest.taskCount. The default value is 20.
- After an outbound campaign is created, the device type cannot be changed.

Method

This interface supports only the POST method.

URI

https://ip:port/rest/isales/v2/openapi/campaigns/{vdnId}

In the URL, ip indicates the IP address of the CC-iSales server, and port indicates the HTTPS port number of the CC-iSales server.

**Table 1** Parameters in the URL
No.	Parameter	Type	Mandatory or Not	Description
1	vdnId	Integer	Yes	VDN ID. The value is an integer ranging from 1 to 9999.

Request Description

**Table 2** Request header parameters
No.	Parameter	Type	Mandatory or Not	Description
1	Content-Type	String	Yes	The value is fixed to application/json; charset=UTF-8.
2	Authorization	String	Yes	For details about the generation mode, see C2 Monitoring, System Outbound Call, CDR, and Knowledge Base Interface Authentication.

**Table 3** Request body parameters
No.	Parameter	Type	Mandatory or Not	Description
1	name	String	Yes	Name of an outbound campaign. The name must be unique. The value can contain a maximum of 32 characters.
2	description	String	No	Description of an outbound campaign. The value can contain a maximum of 200 characters, excluding the following special characters: "[]=;<>
3	strBeginTime	String	Yes	Time when an outbound campaign starts. The format is yyyy-MM-dd HH:mm:ss. The time cannot be earlier than 00:00 of the current day.
4	strEndTime	String	Yes	Time when an outbound campaign ends. The format is yyyy-MM-dd HH:mm:ss.
5	deviceType	Integer	Yes	Type of an outbound device. The options are as follows: 1: IVR for intelligent outbound calls (available in the SaaS environment when the intelligent feature is enabled) 2: skill queue for predicted outbound calls 3: IVR for automatic outbound calls 5: skill queue for previewed outbound calls 6: skill queue for preempted outbound calls
6	callerNo	List	Yes	Multiple calling numbers are supported. For details about the parameters of this object, see Table 13.
7	maxAlertingTime	Integer	Yes	Maximum ringing duration for no answer. If the ringing duration exceeds the value of this parameter, the call is released. For previewed outbound calls, the value ranges from 9 to 120, in seconds. For other types of outbound calls, the value ranges from 5 to 120, in seconds.
8	priority	Integer	No	Task priority. The value ranges from 1 to 5. A smaller value indicates a higher priority.
9	scheduleParam	Object	Yes	Outbound call time segment. For details about the parameters of this object, see Table 4.
10	ivrParam	Object	No	This parameter is mandatory when deviceType is set to 1 or 3 (IVR). For details about the parameters of this object, see Table 5.
11	skillParam	Object	No	This parameter is mandatory when deviceType is set to 2, 5, or 6 (skill queue). For details about the parameters of this object, see Table 6.
12	initStatus	Integer	No	Campaign status after addition. The default value is 0. The options are as follows: 0: The campaign is in started status after being added. 1: The campaign is in suspended status after being added.
13	callBackUrl	String	Yes	Callback notification address of the outbound call result. The URL must start with https:// or http. NOTE: HTTP is an insecure protocol, which may bring risks to the system. Therefore, it is not recommended. The secure HTTPS protocol is recommended.
14	retryPolicy	Object	Yes	Outbound call result policy. For details about the parameters of this object, see Table 14.
15	callPolicy	Object	No	Call policy. For details about the parameters of this object, see Table 19.
16	ccId	Integer	Yes in the OP environment	Center ID. This parameter can be used to identify a center when there are multiple centers.

If the value of callPolciy is not empty and the value of callType is 1 (round call), the value of policyType in the outbound call result policy retryPolicy can only be 1, that is, the number type policy.

**Table 4** Parameter description of scheduleParam
No.	Parameter	Type	Mandatory or Not	Description
9.1	workdayBeginTime1	String	No	Start time of outbound call time segment 1 on workdays, in HH:mm format.
9.2	workdayEndTime1	String	No	End time of outbound call time segment 1 on workdays, in HH:mm format.
9.3	workdayBeginTime2	String	No	Start time of outbound call time segment 2 on workdays, in HH:mm format.
9.4	workdayEndTime2	String	No	End time of outbound call time segment 2 on workdays, in HH:mm format.
9.5	workdayBeginTime3	String	No	Start time of outbound call time segment 3 on workdays, in HH:mm format.
9.6	workdayEndTime3	String	No	End time of outbound call time segment 3 on workdays, in HH:mm format.
9.7	holidayBeginTime1	String	No	Start time of outbound call time segment 1 on holidays, in HH:mm format.
9.8	holidayEndTime1	String	No	End time of outbound call time segment 1 on holidays, in HH:mm format.
9.9	holidayBeginTime2	String	No	Start time of outbound call time segment 2 on holidays, in HH:mm format.
9.10	holidayEndTime2	String	No	End time of outbound call time segment 2 on holidays, in HH:mm format.
9.11	holidayBeginTime3	String	No	Start time of outbound call time segment 3 on holidays, in HH:mm format.
9.12	holidayEndTime3	String	No	End time of outbound call time segment 3 on holidays, in HH:mm format.

Among the outbound call time segments 1, 2, and 3 on workdays, at least one segment must be specified.
The start time and end time must be specified or left empty at the same time.
The start time must be earlier than the end time.
Outbound calls are made by workday unless a date or a day in a week is specified as a holiday.
For the compatibility with the CC-iSales page, after the holiday time segment is configured, the interface in "Adding a Holiday for an Outbound Campaign" must be invoked to specify the relationship between the outbound campaign and the holiday. Otherwise, the interface is incompatible with the page.

**Table 5** Parameter description of ivrParam
No.	Parameter	Type	Mandatory or Not	Description
10.1	deviceSign	String	Yes	When deviceType is set to 1, the value is an intelligent IVR flow code (oifde-flowcode). To obtain the flow code, sign in to the AICC as a tenant administrator and choose Configuration Center > Flow Configuration > Intelligent IVR > Flow Management > Flow Orchestration. When deviceType is set to 3, the value is a common IVR flow access code. To obtain the flow access code, sign in to the AICC as a tenant administrator and choose Configuration Center > Flow Configuration > Flow Management.
10.2	callCount	Integer	Yes	Number of outbound calls that are made in an outbound task each time. The value ranges from 1 to 100.
10.3	callInterval	Integer	Yes	Interval for executing an outbound campaign task. The value ranges from 1 to 9999, in seconds.

For example, if an outbound campaign task requires 60 outbound calls in one minute, you are advised to set callInterval to 3 and callCount to 3.

When the device type is IVR and outbound calls are made, the number of outbound calls is calculated as follows: (Value of callCount/Value of callInterval) x 3, rounded up. Outbound calls are made only when the result is greater than 1. If the value of callInterval is greater than 3, 3 is used for calculation. If the value of callInterval is less than 3, the actual value is used.

**Table 6** Parameter description of skillParam
No.	Parameter	Type	Mandatory or Not	Description
11.1	skillId	Integer	Yes	ID of a skill queue. The value ranges from 1 to 1000.
11.2	skillName	String	Yes	Skill queue name. The value can contain a maximum of 100 characters.
11.3	outBoundType	Integer	Yes	Outbound call mode. The options are as follows: 2: predicted outbound call 5: previewed outbound call 6: preempted outbound call
11.4	predictParam	Object	No	Parameter settings for predicted outbound calls. This parameter is mandatory when outBoundType is set to 2. For details about the parameters of this object, see Table 8.
11.5	previewParam	Object	No	Parameter settings for previewed outbound calls. This parameter is mandatory when outBoundType is set to 5. For details about the parameters of this object, see Table 7.

**Table 7** Parameter description of previewParam
No.	Parameter	Type	Mandatory or Not	Description
11.5.1	failInterval	Integer	Yes	Outbound call interval, in seconds. The value ranges from 3 to 60.
11.5.2	obCallCount	Integer	Yes	Number of outbound calls each time. The value ranges from 1 to 100.
11.5.3	autoCallTime	Integer	Yes	Duration of a previewed outbound call, in seconds. The value ranges from 5 to the value of maxAlertingTime minus 3.

**Table 8** Parameter description of predictParam
No.	Parameter	Type	Mandatory or Not	Description
11.4.1	predictMethod	Integer	Yes	Algorithm for predicted outbound calls. The options are as follows: 1: Algorithm for empirical prediction 2: Algorithm for agent usage prediction 3: Algorithm for predicting the outbound call completion rate 5: Algorithm for off-hook rate prediction
11.4.2	expPredictParam	Object	No	Parameter settings of the algorithm for empirical prediction. This parameter is mandatory when predictMethod is set to 1. For details about the parameters of this object, see Table 9.
11.4.3	agentPredictParam	Object	No	Parameter settings of the algorithm for agent usage prediction. This parameter is mandatory when predictMethod is set to 2. For details about the parameters of this object, see Table 10.
11.4.4	connectPredictParam	Object	No	Parameter settings of the algorithm for predicting the outbound call completion rate. This parameter is mandatory when predictMethod is set to 3. For details about the parameters of this object, see Table 11.
11.4.5	offhookPredictParam	Object	No	Parameter settings of the algorithm for off-hook rate prediction. This parameter is mandatory when predictMethod is set to 5. For details about the parameters of this object, see Table 12.

**Table 9** Parameter description of expPredictParam
No.	Parameter	Type	Mandatory or Not	Description
11.4.2.1	maxAvgCallTime	Integer	Yes	Maximum average call duration, in seconds. The value is a positive integer. The value ranges from 50 to 200.
11.4.2.2	minAvgCallTime	Integer	Yes	Minimum average call duration, in seconds. The value is a positive integer. The value ranges from 50 to 200. The value must be less than or equal to the value of maxAvgCallTime.
11.4.2.3	outBoundRate	Integer	Yes	Outbound call rate. The value ranges from 0 to 100. The default value is 70.

**Table 10** Parameter description of agentPredictParam
No.	Parameter	Type	Mandatory or Not	Description
11.4.3.1	maxAvgCallTime	Integer	Yes	Maximum average call duration, in seconds. The value is a positive integer. The value ranges from 50 to 200.
11.4.3.2	minAvgCallTime	Integer	Yes	Minimum average call duration, in seconds. The value is a positive integer. The value ranges from 50 to 200. The value must be less than or equal to the value of maxAvgCallTime.
11.4.3.3	lossRate	Integer	Yes	Minimum call loss rate. The value ranges from 0 to 100. The default value is 3.
11.4.3.4	utilRate	Integer	Yes	Agent usage. The value ranges from 0 to 100. The default value is 70.
11.4.3.5	utilRateMethod	Integer	Yes	Algorithm for agent usage. The options are as follows: 1: Agent usage = Total call duration/Total login duration 2: Agent usage = (Total call duration + Work state duration)/Total login duration

**Table 11** Parameter description of connectPredictParam
No.	Parameter	Type	Mandatory or Not	Description
11.4.4.1	maxAvgCallTime	Integer	Yes	Maximum average call duration, in seconds. The value is a positive integer. The value ranges from 50 to 200.
11.4.4.2	minAvgCallTime	Integer	Yes	Minimum average call duration, in seconds. The value is a positive integer. The value ranges from 50 to 200. The value must be less than or equal to the value of maxAvgCallTime.
11.4.4.3	lossRate	Integer	Yes	Minimum call loss rate. The value ranges from 0 to 100. The default value is 3.
11.4.4.4	waitTime	Integer	Yes	Called party's waiting time. The value ranges from 0 to 16, in seconds. The default value is 5.
11.4.4.5	connRate	Integer	Yes	Outbound call connection rate. The value ranges from 0 to 100.

**Table 12** Parameter description of offhookPredictParam
No.	Parameter	Type	Mandatory or Not	Description
11.4.5.1	offHookRate	Integer	Yes	Off-hook rate. The value ranges from 50 to 200. The default value is 100.

**Table 13** Parameter description of callerNo
No.	Parameter	Type	Mandatory or Not	Description
6.1	accessCode	String	Yes	Calling number. Number displayed on the phone of a customer after a call is connected. The value can contain a maximum of 32 characters, including only digits.
6.2	priority	Integer	Yes	Calling number priority. The value ranges from 1 to 5. A smaller value indicates a higher priority.

**Table 14** Parameter description of retryPolicy
No.	Parameter	Type	Mandatory or Not	Description
14.1	policyType	Integer	Yes	Retry policy type. 0: global policy; 1: number type matching policy.
14.2	retryDay	Integer	--	Maximum number of days for call attempts. This parameter is mandatory for common policies under the global policy. The value ranges from 1 to 5.
14.3	retryTimes	Integer	--	Maximum number of call attempts per day. This parameter is mandatory for common policies under the global policy. The value ranges from 1 to 6.
14.4	callInterval	Integer	--	Outbound call interval, in seconds. This parameter is mandatory for common policies under the global policy. The value ranges from 1 to 86400.
14.5	resultRetry	String	--	JSON string of the result policy. This parameter is mandatory for result policies under the global policy. For details about the parameters of this object, see Table 15.
14.6	policyJson	String	--	JSON string of the number type matching policy. This parameter is mandatory for number type matching policies. For details about the parameters of this object, see Table 16.
14.7	busiPolicy	String	No	JSON string of the business result policy. For details about the parameters of this object, see Table 18.
14.8	noRetryPolicy	List <String>	No (This parameter cannot be set when policyType is set to 1.)	Result codes for which no retry policy is configured. The result codes come from the resultCode field in the data attribute in Querying Outbound Call Results.

If the value of policyType is 0 and the policy is a common policy, set retryDay, retryTimes, and callInterval, for example, "retryDay": 2,"retryTimes": 2,"callInterval": 2. For a result-based policy, set only resultRetry, for example, "[{"result":"2","retryNumber":"1","callInterval":600}]".

When the value of policyType is 1, set only policyJson.

For a common policy, an example of policyJson is as follows: policyJson: "[{"dataType":"ST","type":"0","policy":{"retryDay":"2","retryTimes":"2"}}]".

For a result-based policy, an example of policyJson is as follows: "policyJson": "[{'dataType':'SI','type':1,'policy':[{'result':4,'retryNumber':3,'callInterval':600}]}]".

**Table 15** Parameter description of resultRetry
No.	Parameter	Type	Mandatory or Not	Description
14.5.1	result	Integer	--	Result type. This parameter is mandatory for result policies under the global policy. The value ranges from 1 to 9.
14.5.2	callInterval	Integer	--	Outbound call interval, in seconds. This parameter is mandatory for result policies under the global policy. The value ranges from 1 to 86400.
14.5.3	retryNumber	Integer	--	Number of retry times. This parameter is mandatory for result policies under the global policy. The value ranges from 0 to 9.

**Table 16** Parameter description of policyJson
No.	Parameter	Type	Mandatory or Not	Description
14.6.1	dataType	String	Yes	Number type. The value can contain a maximum of 20 characters, excluding special characters.
14.6.2	type	Integer	Yes	Retry logic policy type. 0: common policy 1: result policy
14.6.3	policy	String	Yes	Policy configuration information. For details about the parameters of this object, see Table 17.

**Table 17** Parameter description of policy
No.	Parameter	Type	Mandatory or Not	Description
14.6.3.1	retryDay	Integer	--	Maximum number of days for call attempts. This parameter is mandatory for common policies that are matched based on the number type. The value ranges from 1 to 5.
14.6.3.2	retryTimes	Integer	--	Maximum number of call attempts per day. This parameter is mandatory for common policies that are matched based on the number type. The value ranges from 1 to 6.
14.6.3.3	result	Integer	--	Result type. This parameter is mandatory for result policies that are matched based on the number type. The value ranges from 0 to 9. The options are as follows: 1: The customer is busy. 2: The customer does not answer the call. 3: The customer rejects the call. 4: The number does not exist. 5: The customer's phone is powered off. 6: The customer is out of the service area. 7: Fax or switchboard. 8: The call times out. 9: The call fails. 0: Others. The retry policy is also determined based on the specific failure code (failCode). For details about failure codes, see Table 4.
14.6.3.4	callInterval	Integer	--	Outbound call interval, in seconds. This parameter is mandatory for result policies that are matched based on the number type. The value ranges from 1 to 86400.
14.6.3.5	retryNumber	Integer	--	Number of retry times. This parameter is mandatory for result policies that are matched based on the number type. The value ranges from 0 to 9.

**Table 18** Parameter description of busiPolicy
No.	Parameter	Type	Mandatory or Not	Description
14.7.1	busiResultCode	String	Yes	Business result code.
14.7.2	busiResultSubCode	String	--	Business result subcode. (This parameter is associated with the business result code.)
14.7.3	busiResultPolicy	Integer	Yes	Call policy for a business result. 0: Stop calling. 1: Call the next number. 2: Call the current number.
14.7.4	callInterval	Integer	--	Outbound call interval, in seconds. If the call policy is set to 0, you do not need to set this parameter. Otherwise, this parameter is mandatory. The value ranges from 1 to 3600.

**Table 19** Parameter description of callPolicy
No.	Parameter	Type	Mandatory or Not	Description
15.1	callType	Integer	No	Call mode. 0: by sequence; 1: by round. The default value is 0.
15.2	chooseType	Integer	--	Round mode. 0: by number category; 1: by number sequence. This parameter is mandatory when the call mode is by round.
15.3	turns	List	--	Round information. This parameter is mandatory when the call mode is by round. For details about the parameters of this object, see Table 20.

**Table 20** Parameter description of turns
No.	Parameter	Type	Mandatory or Not	Description
15.3.1	turnType	String	--	Number type. The value can contain a maximum of 20 characters, excluding special characters. This parameter is mandatory when the round mode is by number category.
15.3.2	turnOrder	Integer	--	Number sequence. The value ranges from 1 to 10. This parameter is mandatory when the round mode is by number sequence.

Response Description

**Table 21** Response body parameters
No.	Parameter	Type	Description
1	resultCode	String	Error code. The value 0200000 indicates success, and other values indicate failure. For details, see Table 23.
2	resultDesc	String	Description.
3	returnCode	String	Error code. The value 0200000 indicates success, and other values indicate failure. For details, see Table 23.
4	returnDesc	String	Description.
5	returnObject	Object	For details, see Table 22.

**Table 22** Parameter description of returnObject
No.	Parameter	Type	Description
5.1	id	Integer	ID of an outbound campaign.

Triggered Event

None

Error Codes

**Table 23** Error code description
No.	Error Code	Description
1	0200001	Parameter error. For details about the error, see resultDesc.
2	0200002	The start time of an outbound campaign is earlier than the early morning of the current day.
3	0200003	The number of outbound campaigns whose device type is skill queue has reached the upper limit. To add more outbound campaigns, delete other outbound campaigns whose device type is skill queue.
4	0200004	The number of outbound campaigns whose device type is IVR has reached the upper limit. To add more outbound campaigns, delete other outbound campaigns whose device type is IVR.
5	0200005	The outbound campaign name must be unique.
6	0200017	The skill queue ID does not exist.
7	02000001	Empty parameter.
8	02000002	The parameter contains invalid characters.
9	02000003	The parameter length cannot exceed the maximum length.
10	02000004	The parameter length cannot be less than the minimum length.
11	02000005	The parameter length must be within the specified range.
12	02000006	Incorrect parameter type.
13	02000007	Incorrect parameter value.
14	02000008	Parameter conversion error. Check the request parameters.
15	02000009	Incorrect parameter combination. Check the request parameters.
16	02000010	The hour and minute parameters must be set at the same time.
17	02000011	The number of parameters cannot exceed the specified number.

Example

The following provides an example of the request body of this interface:

{
    "name": "test0827shwocase1",
    "description": "long0825",
    "strBeginTime": "2021-08-27 00:00:00",
    "strEndTime": "2021-08-28 23:59:59",
    "deviceType": 2,
    "callerNo": [
        {
            "accessCode": "88889527",
            "priority": 3
        },
        {
            "accessCode": "88880066",
            "priority": 4
        }
    ],
    "maxAlertingTime": 20,
    "priority": 4,
    "scheduleParam": {
        "workdayBeginTime1": "00:00",
        "workdayEndTime1": "23:59",
        "workdayBeginTime2": "",
        "workdayEndTime2": "",
        "workdayBeginTime3": "",
        "workdayEndTime3": "",
        "holidayBeginTime1": "10:00",
        "holidayEndTime1": "11:00",
        "holidayBeginTime2": "13:00",
        "holidayEndTime2": "17:30",
        "holidayBeginTime3": "",
        "holidayEndTime3": ""
    },
    "skillParam": {
        "skillId": 2,
        "skillName": "defaultAudioSkill",
        "outBoundType": 2,
        "predictParam": {
            "predictMethod": 1,
            "expPredictParam": {
                "maxAvgCallTime": 100,
                "minAvgCallTime": 50,
                "outBoundRate": 50
            }
        }
    },
    "retryPolicy": {
        "policyType": 1,
        "policyJson": "[{'dataType':'SI','type':1,'policy':[{'result':4,'retryNumber':3,'callInterval':600}]}]"
    },
    "callPolicy": {
        "callType": 1,
        "chooseType": 0,
        "turns": [
            {
                "turnType": "SI"
            }
        ]
    },
    "initStatus": 0,
    "callBackUrl": "https://10.10.10.10/xxx/xxx/xxx"
}

The following provides an example of the response body of this interface:

{
    "resultCode": "0200000",
    "resultDesc": "",
    "returnCode": "0200000",
    "returnDesc": "",
    "returnObject": {
        "id": 46
    }
}

Parent topic: Outbound Campaign Management Interfaces

Previous topic: Adding an Outbound Campaign (V1)

Next topic: Modifying an Outbound Campaign (V1)