Updated on 2023-09-27 GMT+08:00

Modifying an Outbound Campaign (V1)

Scenario

This interface is invoked to modify the configurations of an outbound campaign.

Usage Description

  • Prerequisites
    • You have applied for a developer account.
    • The ID of the outbound campaign to be modified has been obtained.
    • The outbound campaign task must exist and is not complete.
  • Restrictions
    • After an outbound campaign is created, the device type cannot be changed.

Method

This interface supports only the PUT method.

URI

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

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.

2

campaignId

Integer

Yes

Outbound campaign task ID.

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

No

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

No

Time when an outbound campaign ends.

The format is yyyy-MM-ddHH:mm:ss.

5

deviceType

Integer

Yes

Type of an outbound device.

The options are as follows:

  • 1: IVR in intelligent outbound calls (available in the SaaS environment when the intelligent feature is enabled)
  • 2: skill queue in predicted outbound calls
  • 3: IVR in automatic outbound calls
  • 5: skill queue in previewed outbound calls
  • 6: skill queue in preempted outbound calls

The default value is the value set during creation and cannot be changed.

6

callerNo

String

Yes

Calling number.

Number displayed on the phone of a customer after a call is connected.

The value can contain a maximum of 24 characters, including only digits, asterisks (*), and number signs (#).

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

scheduleParam

Object

Yes

Outbound call time segment.

For details about the parameters of this object, see Table 4.

9

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.

10

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.

11

callBackUrl

String

Yes

Callback notification URL 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.

The start time and end time of an outbound campaign are optional but must meet the following rules:

  1. If one of the parameters is set, the other parameter must also be set.

  2. The start time cannot be later than the end time.

  3. The end time cannot be earlier than the current time.

Table 4 Parameter description of scheduleParam

No.

Parameter

Type

Mandatory or Not

Description

8.1

workdayBeginTime1

String

No

Start time of outbound call time segment 1 on workdays, in HH:mm format.

8.2

workdayEndTime1

String

No

End time of outbound call time segment 1 on workdays, in HH:mm format.

8.3

workdayBeginTime2

String

No

Start time of outbound call time segment 2 on workdays, in HH:mm format.

8.4

workdayEndTime2

String

No

End time of outbound call time segment 2 on workdays, in HH:mm format.

8.5

workdayBeginTime3

String

No

Start time of outbound call time segment 3 on workdays, in HH:mm format.

8.6

workdayEndTime3

String

No

End time of outbound call time segment 3 on workdays, in HH:mm format.

8.7

holidayBeginTime1

String

No

Start time of outbound call time segment 1 on holidays, in HH:mm format.

8.8

holidayEndTime1

String

No

End time of outbound call time segment 1 on holidays, in HH:mm format.

8.9

holidayBeginTime2

String

No

Start time of outbound call time segment 2 on holidays, in HH:mm format.

8.10

holidayEndTime2

String

No

End time of outbound call time segment 2 on holidays, in HH:mm format.

8.11

holidayBeginTime3

String

No

Start time of outbound call time segment 3 on holidays, in HH:mm format.

8.12

holidayEndTime3

String

No

End time of outbound call time segment 3 on holidays, in HH:mm format.

  1. Among the outbound call time segments 1, 2, and 3 on workdays, at least one segment must be specified.

  2. The start time and end time must be specified or left empty at the same time.

  3. The start time must be earlier than the end time.

  4. Outbound calls are made by workday unless a date or a day in a week is specified as a holiday.

  5. After the holiday time segment is configured, to be compatible with the AICC-isales page, the interface of 6.2 (Adding an Outbound Call Campaign Holiday) must be invoked to specify the relationship between the outbound call 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

9.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 the flow access code of a common IVR or the chatbot access code of an intelligent IVR.

To obtain the flow access code of a common IVR, sign in to the AICC as a tenant administrator and choose Configuration Center > Flow Configuration > Flow Management.

To obtain the chatbot access code of an intelligent IVR, sign in to the AICC as a tenant administrator and choose Configuration Center > Flow Configuration > Intelligent IVR > Chatbot Management.

9.2

callCount

Integer

Yes

Number of outbound calls that are made in an outbound task each time.

The value ranges from 1 to 100.

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

The IVR is used after outbound calls are made. The number of outbound calls is calculated as follows: The value of (callCount/callInterval) x Interval rounded up to 3 (only when the number of outbound calls is greater than 1). If the outbound call interval is greater than 3, outbound calls are made every 3 seconds. If the outbound call interval is less than 3, the configured outbound call interval is used.

Table 6 Parameter description of skillParam

No.

Parameter

Type

Mandatory or Not

Description

10.1

skillId

Integer

Yes

ID of a skill queue.

The value ranges from 1 to 1000.

10.2

skillName

String

No

Skill queue name.

The value can contain a maximum of 100 characters.

10.3

outBoundType

Integer

Yes

Outbound call mode.

The options are as follows:

  • 2: predicted outbound call
  • 5: previewed outbound call
  • 6: preempted outbound call

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

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

10.5.1

failInterval

Integer

Yes

Outbound call interval, in seconds. The value ranges from 3 to 60.

10.5.2

obCallCount

Integer

Yes

Number of outbound calls each time. The value ranges from 1 to 100.

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

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

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

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

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

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

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

10.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 smaller than or equal to the value of maxAvgCallTime.

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

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

10.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 smaller than or equal to the value of maxAvgCallTime.

10.4.3.3

lossRate

Integer

Yes

Minimum call loss rate.

The value ranges from 0 to 100. The default value is 3.

10.4.3.4

utilRate

Integer

Yes

Agent usage.

The value ranges from 0 to 100. The default value is 70.

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

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

10.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 smaller than or equal to the value of maxAvgCallTime.

10.4.4.3

lossRate

Integer

Yes

Minimum call loss rate.

The value ranges from 0 to 100. The default value is 3.

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

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

10.4.5.1

offHookRate

Integer

Yes

Off-hook rate.

The value ranges from 50 to 200. The default value is 100.

Response Description

Table 13 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 14.

2

resultDesc

String

Description.

3

returnCode

String

Error code. The value 0200000 indicates success, and other values indicate failure.

For details, see Table 14.

4

returnDesc

String

Description.

Triggered Event

None

Error Codes

Table 14 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

0200005

The outbound campaign name must be unique.

4

0200007

The outbound campaign does not exist.

5

0200016

The outbound campaign has expired.

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": "Data Package Recommendation for National Day",
        "description": "Data Package Recommendation for National Day",
        "strBeginTime": "2020-09-10 00:00:00",
        "strEndTime": "2020-10-07 23:59:59",
        "deviceType": 2,
        "callerNo": "10085",
        "maxAlertingTime": 20,
        "scheduleParam": {
            "workdayBeginTime1": "08:00",
            "workdayEndTime1": "11:30",
            "workdayBeginTime2": "13:00",
            "workdayEndTime2": "17:30",
            "workdayBeginTime3": "",
            "workdayEndTime3": "",
            "holidayBeginTime1": "10:00",
            "holidayEndTime1": "11:00",
            "holidayBeginTime2": "13:00",
            "holidayEndTime2": "17:30",
            "holidayBeginTime3": "",
            "holidayEndTime3": ""
        },
        "skillParam": {
            "skillId": 5,
            "skillName": "Voice Skill Queue",
            "outBoundType": 2,
            "predictParam": {
                "predictMethod": 5,
                "offhookPredictParam": {
                    "offHookRate": 100
                }
            }
        },
        "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": ""
    }