Introduction

The MultiChannel Connetor (MCC) is a Web Service that allows the integration of third-party systems for the management of multi-channel sessions of the TVox Contact Center.

The available methods are:

Start new session
Accept session
Check session state
Check session state with session data
Set session data
Close session
Get service state
Logout agent from channel

TVox channels that can be managed with the MCC are:

Channel	ID
Custom channel 1	1
Custom channel 2	2
Custom channel 3	3
LiveHelp	1003

Web Service

MCC is provided as a Web Service on 2 technologies / protocols:

SOAP

Enpoint for SOAP service is:

https://<TVOX_HOST>/mc/cxf/soap

WSDL describing the service can be downloaded here or at this address:

https://<TVOX_HOST>/mc/cxf/soap?wsdl

REST / JSON

Enpoint for REST / JSON service is:

https://<TVOX_HOST>/mc/cxf/rest/json

WADL describing the service can be downloaded here or at this address:

https://<TVOX_HOST>/mc/cxf/rest?_wadl

JSON is the message format intended for exchange through this type of service.

Start new session

Start a new session on TVox to create an interaction on the desired channel and service. Further information can be provided for personalized interaction management.

SOAP

Operation: startSession

REST / JSON

Path: /startSession
Method: GET

Request

Property	Type	Description	Required
channelId	`int`	Channel ID	`*`
serviceid	`String`	Service code	`*`
sessionId	`String`	Session ID (otherwise self-generated)
data	`String`	Additional data
description	`String`	Session description
contactId	`String`	Addressbook contact UUID
contactValue	`String`	Addressbook contact value (e.g. phone number)

Response

`StartSessionResult`

Property	Type	Description
result	`CommandResult`	Result state
sessionId	`String`	Session ID
failReason	`StartSessionFailReasonCode`	Fail reason code (if operation failed)
failReasonMessage	`String`	Fail reason message (if operation failed)
contactId	`String`	Addressbook contact UUID (if provided)
contactValue	`String`	Addressbook contact value (if provided)

`StartSessionFailReasonCode`

Value	Description
`GENERIC`	Generic error
`INVALID_CHANNEL_ID`	Channel ID is not valid
`NO_LICENSE`	License is missing or exceeded
`UNKNOWN_CHANNEL_ID`	Channel ID is not available
`UNKNOWN_SERVICE`	Service is not found or not configured
`CHANNEL_NOT_ENABLED`	Channel is not enabled
`SERVICE_NOT_ENABLED`	Service is not enabled on channel
`REQUIRED_PARAMETERS`	Required parameter is missing in the request
`DUPLICATED_SESSION_ID`	Session ID provided already exists
`TIMEOUT_EXCEEDED`	Server error: Request timeout exceeded
`INVALID_RESPONSE`	Server error: Response is not valid
`DATABASE_ERROR`	Server error: Database error

Accept session

Accept an existing session on TVox to assign the interaction linked to it to an agent or simply let it enter the Contact Center management flow.

SOAP

Operation: sessionAccept

REST / JSON

Path: /sessionAccept
Method: GET

Request

Property	Type	Description	Required
sessionId	`String`	Session ID	`*`
user	`String`	Username of the agent to assign the session to

Response

`SessionAcceptResult`

Property	Type	Description
result	`CommandResult`	Result state
sessionId	`String`	Session ID
status	`SessionStatus`	Session status
failReason	`SessionStatusFailReasonCode`	Fail reason code (if operation failed)
failReasonMessage	`String`	Fail reason message (if operation failed)

`SessionStatusFailReasonCode`

Value	Description
`GENERIC`	Generic error
`SERVICE_NOT_ENABLED`	Service is not enabled on channel
`INVALID_SESSION_ID`	Session ID provided is not valid or does not exist
`SESSION_CLOSED`	Session has already been closed
`REQUEST_REJECTED_BY_SERVICE`	Service reject the request
`TIMEOUT_EXCEEDED`	Server error: Request timeout exceeded
`INVALID_RESPONSE`	Server error: Response is not valid

Check session state

Check state of an existing session on TVox.

SOAP

Operation: checkSessionState

REST / JSON

Path: /checkSession
Method: GET

Request

Property	Type	Description	Required
sessionId	`String`	Session ID	`*`

Response

`CheckSessionResult`

Property	Type	Description
result	`CommandResult`	Result state
sessionId	`String`	Session ID
status	`SessionStatus`	Session status
username	`String`	Username of the agent assigned to the session
customMessage	`String`	Custom message
failReason	`CheckSessionFailReasonCode`	Fail reason code (if operation failed)
failReasonMessage	`String`	Fail reason message (if operation failed)

`CheckSessionFailReasonCode`

Value	Description
`INVALID_SESSION_ID`	Session ID provided is not valid or does not exist

Check session state with session data

Check state of an existing session on TVox by also retrieving the session data.

SOAP

Operation: checkSessionStateWithData

REST / JSON

Path: /checkSessionWithData
Method: GET

Request

Property	Type	Description	Required
sessionId	`String`	Session ID	`*`

Response

`CheckSessionWithDataResult`

Property	Type	Description
result	`CommandResult`	Result state
sessionId	`String`	Session ID
status	`SessionStatus`	Session status
username	`String`	Username of the agent assigned to the session
customMessage	`String`	Custom message
data	`String`	Additional data populated at session start
sessionData	`String`	Additional data populated while session is in progress
failReason	`CheckSessionWithDataFailReasonCode`	Fail reason code (if operation failed)
failReasonMessage	`String`	Fail reason message (if operation failed)

`CheckSessionWithDataFailReasonCode`

Value	Description
`INVALID_SESSION_ID`	Session ID provided is not valid or does not exist

Set session data

Set session data of an existing session on TVox.

SOAP

Operation: setSessionData

REST / JSON

Path: /setSessionData
Method: PUT

Request

Property	Type	Description	Required
setSessionDataRequest	`SetSessionDataRequest`	Session data request	`*`

`SetSessionDataRequest`

Property	Type	Description	Required
sessionId	`String`	Session ID	`*`
sessionData	`String`	Additional data populated while session is in progress

Response

`SetSessionDataResult`

Property	Type	Description
result	`CommandResult`	Result state
sessionId	`String`	Session ID
sessionData	`String`	Additional data populated while session is in progress
failReason	`SetSessionDataFailReasonCode`	Fail reason code (if operation failed)
failReasonMessage	`String`	Fail reason message (if operation failed)

`SetSessionDataFailReasonCode`

Value	Description
`INVALID_RESPONSE`	Server error: Response is not valid
`INVALID_SESSION_ID`	Session ID provided is not valid or does not exist
`SESSION_CLOSED`	Session has already been closed

Close session

Closes an existing session on TVox.

SOAP

Operation: closeSession

REST / JSON

Path: /closeSession
Method: GET

Request

Property	Type	Description	Required
sessionId	`String`	Session ID	`*`
reason	`Reason`	Closing reason

`Reason`

Value	Description
`REQUEST_FROM_CALLER`	Session will be close by service
`REQUEST_FROM_CALLEE`	Session will be close by agent

Response

`CloseSessionResult`

Property	Type	Description
result	`CommandResult`	Result state
sessionId	`String`	Session ID
failReason	`CloseSessionFailReasonCode`	Fail reason code (if operation failed)
failReasonMessage	`String`	Fail reason message (if operation failed)

`CloseSessionFailReasonCode`

Value	Description
`GENERIC`	Generic error
`UNKNOWN_SERVICE`	Service is not found or not configured
`SERVICE_NOT_ENABLED`	Service is not enabled on channel
`IS_PENDING`	Another closing request is in progress
`NOT_FOUND`	Session was not found
`INVALID_SESSION_ID`	Session ID provided is not valid or does not exist
`TIMEOUT_EXCEEDED`	Server error: Request timeout exceeded
`INVALID_RESPONSE`	Server error: Response is not valid
`DATABASE_ERROR`	Server error: Database error

Get service state

Get state of TVox services on the desired channel.

SOAP

Operation: getServiceState

REST / JSON

Path: /getServiceState
Method: GET

Request

Property	Type	Description	Required
channelId	`int`	Channel ID	`*`
serviceCodes	`Set<String>`	Set of service codes	`*`

Response

`GetServiceStateResult`

Property	Type	Description
result	`CommandResult`	Result state
state	`Map<String, [ServiceState](#servicestate)>`	Map of service states (`<ServiceCode, ServiceState>`)
channelId	`int`	Session ID
failReason	`GetServiceStateResultFailReasonCode`	Fail reason code (if operation failed)
failReasonMessage	`String`	Fail reason message (if operation failed)

`ServiceState`

Value	Description
`ACTIVE`	Service is active
`OUT_OF_SERVICE`	Service is out of service
`OVERTIME`	Service is overtime
`UNKNOWN_SERVICE`	Service is not found or not configured
`CHANNEL_NOT_ENABLED`	Channel is not enabled
`SERVICE_NOT_ENABLED`	Service is not enabled on channel
`NO_LICENSE`	License is missing or exceeded
`FAILED`	Generic error

`GetServiceStateResultFailReasonCode`

Value	Description
`INVALID_CHANNEL_ID`	Channel ID is not valid
`INVALID_SERVICE_CODES`	Service code are not valid
`SERVICE_STATE_NOT_FOUND`	Service state can not be found
`SERVICE_NOT_ENABLED`	Service is not enabled on channel
`TIMEOUT_EXCEEDED`	Server error: Request timeout exceeded
`REQUEST_REJECTED_BY_SERVICE`	Service reject the request
`INVALID_RESPONSE`	Server error: Response is not valid

Logout agent from channel

Logout a TVox agent from the desired channel.

SOAP

Operation: logoutAgentFromChannel

REST / JSON

Path: /logoutAgentFromChannel
Method: GET

Request

Property	Type	Description	Required
channelId	`int`	Channel ID	`*`
agentUsername	`String`	Username of the agent to logout	`*`

Response

`LogoutAgentResult`

Property	Type	Description
result	`CommandResult`	Result state
failReason	`LogoutAgentResultFailReasonCode`	Fail reason code (if operation failed)
failReasonMessage	`String`	Fail reason message (if operation failed)

`LogoutAgentResultFailReasonCode`

Value	Description
`INVALID_CHANNEL_ID`	Channel ID is not valid
`INVALID_USERNAME`	Username of the agent is not valid or does not exist
`INVALID_USER_PROFILES`	Agent profile is not valid
`USER_NOT_LOGGED`	Agent is not logged
`LOGOUT_DATABASE_ERROR`	Server error: Database error
`LOGOUT_LICENSE_ERROR`	Server error: License error
`LOGOUT_EXTENSION_ERROR`	Server error: Extension error
`LOGOUT_USERNAME_ERROR`	Server error: Username error
`LOGOUT_ASTERISK_ERROR`	Server error: Asterisk error
`LOGOUT_TWIN_ERROR`	Server error: Twin error
`LOGOUT_UNKNOWN_ERROR`	Server error: Unknown error

Common objects

`CommandResult`

Value	Description
SUCCESS	Operation was successful
FAILED	Operation failed

`SessionStatus`

Value	Description
`NEW`	Session is new
`QUEUED`	Session is queued
`BOOKED`	Session is booked
`ASSIGNED`	Session is assigned to an agent
`CLOSED`	Session is closed
`UNKNOW`	Session is in unknown status

Changelog

1.0.0

First release
- Start new session
- Accept session
- Check session state
- Close session
- Get service state
- Logout agent from channel

1.0.1

Features / Enhancements
- Added method: check session state with session data
- Added method: set session state