IVR SDK frontend integration guide

Frontend resources

<!--SDK stylesheet-->
<link rel="stylesheet" type="text/css" href="https://g.alicdn.com/cloudcallcenter/acc-ivr/{version-ivr-sdk}/main.min.css">
<!--SDK JS file-->
<script type="text/javascript" src="https://g.alicdn.com/cloudcallcenter/acc-ivr/{version-ivr-sdk}/accIvrSdk.min.js"></script>

For the static resources above, replace {version-ivr-sdk} with the corresponding version number. The latest version number is:
version-ivr-sdk ==> 1.14.1

Initialize the SDK

Before you integrate the software development kit (SDK), complete the following preparations:

Use Chrome 58 or later. Cloud Contact Center calls use Web Real-Time Communication (WebRTC) technology. Chrome provides high compatibility with WebRTC, which helps ensure call quality and security.

Initialize the SDK:

window.accIvr = new window.AccIvrSdk(config)

Required config parameters

• dom

  The ID of the element to mount.

• instanceId

  The domain name that you specified when you created the Cloud Contact Center instance. You can find the instance ID at https://ccc.console.aliyun.com/AccV2Instance.  
  The instance ID is the `xxx` part of the `workbench/xxx/agentdest` string in the endpoint.

• regionId

  The cluster where the Cloud Contact Center server is deployed. The default value is 'cn-shanghai'.

Optional config parameters

• width

  The width. Default: 100%. Parameter type: Number (px) or String (%).

• height

  The height. Default: 100%. Parameter type: Number (px) or String (%).

• baseURL

  The path to load the IVR page. If you use hash-based routing, this is `window.location.hash`. If you use browser-based routing, this is `window.location.pathname`.

• isBrowserHistory

  A Boolean value. Set this to `true` if you use browser-based routing. You do not need to specify this parameter for hash-based routing.

The following parameters configure the API endpoint and request parameters for frontend requests to the server-side API.

The URI of the request is: ${ajaxOrigin}${ajaxPath}?${ajaxApiParamName}=${apiName}&product=CloudCallCenter&version=2020-07-01&region=${regionId}

• ajaxOrigin

  The request source. By default, requests are sent to the current origin (`location.origin`). Parameter type: String.

• ajaxPath

  The request path. The default value is "/data/api.json".

• withCredentials

  Specifies whether to use credentials and allow cookies for cross-origin requests. Parameter type: Boolean.

• ajaxApiParamName

  The name that distinguishes the action when `ajaxType` is `param`. Default: `action`. Parameter type: String.

• ajaxMethod

  The request method. Valid values: `post` and `get`. Default: `post`. Parameter type: String.

• ajaxOtherParams

  Other custom parameters at the same level as the request. Parameter type: Object.

• ajaxHeaders

  The request header. Parameter type: Object.

• uploadAudioPageUrl

  The path to the custom audio upload page. The default is the audio upload page in the Cloud Contact Center console (`https://ccc-v2.aliyun.com/workbench/{InstanceId}/media`).

The parameter settings for API requests are now complete.

The following hook is a callback function for routing changes. The type is `function`.

• onChangeRouter(url)

  Triggered when the routing changes. You can perform corresponding actions based on the routing change.

The following code provides a configuration example.

window.customIvr = new window.AccIvrSdk({
  dom: 'ivr',
  instanceId: 'XXX',
  regionId: 'cn-shanghai',
  ajaxPath: '/aliyun/ccc/api',
  ajaxMethod: 'post',
  useOpenApiSdk: false,
  width: '800px',
  height: '500px',
  baseURL: '/ivr',
  onChangeRouter(url) {
    console.log(url);
  },
});

SDK description

The IVR SDK includes built-in routing configurations that correspond to different pages and operations.

API	Description
${baseURL}	IVR list page.
${baseURL}/delete	Deletes an IVR.
${baseURL}/publish	Publishes an IVR.
${baseURL}/version	IVR version information.
${baseURL}/export	Exports an IVR.
${baseURL}/create	Creates a new IVR.
${baseURL}/modify/:contactFlowId	Edits an IVR.
${baseURL}/clone	Clones an IVR.
${baseURL}/import	Imports an IVR.

Server-side preparations

The IVR SDK is embedded in your business system. The SDK sends multiple requests to your system's server. You can configure the request endpoint using the `ajax` parameters described in the Optional config parameters section. Your server must forward these requests to the Cloud Contact Center server by calling the corresponding OpenAPI operations. Then, your server must pass the results back to the IVR SDK. The steps are as follows:

• You can use an AccessKey pair (AK/SK) or OAuth 2.0 to make API requests.

• Forward requests from the SDK to the Cloud Contact Center server. Call the corresponding OpenAPI operation as described in the API overview. Pass the returned results back to the IVR SDK. The results must be in JSON format.

Type	API	Description
Business API	ListContactFlows	Gets a list of IVRs.
	GetContactFlowVersion	Gets the version information of an IVR flow.
	ListSnapshotsOfContactFlow	Gets the snapshot information of an IVR flow.
	StartEditContactFlow	Starts editing an IVR flow.
	PublishContactFlow	Publishes an IVR flow.
	GetContactFlow	Gets the canvas information of an IVR flow.
	DiscardEditingContactFlow	Discards the edits of an IVR flow.
	DeleteContactFlow	Deletes an IVR flow.
	RollbackContactFlow	Rolls back an IVR flow to a specified version.
	ListSkillGroups	Gets a list of skill groups.
	ListPhoneNumbers	Gets a list of phone numbers.
	GetSmsConfig	Gets the text message configuration.
	ListConfigItems	Gets the current workbench configuration.
	ListCallTags	Gets a list of blacklist tags.
	ListMedias	Gets a list of audio files in the current instance.
	DeleteMedia	Deletes an audio file.
	GetAudioFileDownloadUrl	Gets the URL of a specified audio file.
	ListAsrSettings	Gets the enabling status of the voice configuration.
	CheckNlsServiceStatus	Checks whether the intelligent Voice Service is authorized.
	ListProjects	Gets a list of voice projects.
	GetTtsAuditionFile	Gets the link to the text-to-speech (TTS) audition audio file.
	ListBriefSkillGroups	Gets a brief list of skill groups.
	ListCustomizedVoiceNavigatorInstances	Gets the mapping between intelligent navigation instances and numbers.

Update log

v1.14.1

Features

• Set Variable node: You can now select a variable when assigning a value.

• History: Added features to save and delete drafts.

• Collect Satisfaction node: Added a Customer Hang Up node.

• Added a Play Video node.

• Added a Transfer to Flow node.

• Get Digits node: Added the `dtmfSource` field.

• Renamed Cloud Call Center to Cloud Contact Center.

• Added a system variable for working hours.

• Optimized the exit behavior during editing.

• Optimized some features and improved user experience.

v1.9.2

Features

• The Customer Hang Up branch can now be connected to a Send Text Message node.

• Connections and configurations are no longer validated when you save them. Validation occurs only when you publish the flow.

• Connection validation: A node connected to a Customer Hang Up branch can no longer be connected to a call-related node.

• Branch modules now automatically adjust to text width. This lets you see the full content of each branch during configuration, which makes it easier to create connections.

v1.8.2

Features

• Get Digits and Collect Satisfaction nodes: Added timeout and error prompts.

v1.7.0

Features

• Optimized error messages for some API request failures.

v1.6.0

Bug Fixes

• Fixed an issue where node data connections became abnormal after a branch node was added or deleted.

• Fixed an issue where system parameters could be selected when setting variable parameters. Only custom parameters should be selectable.

Features

• Added some system audio files.

• Transfer to Agent node: Added a temporary leave node.