TABLE OF CONTENTS [Document Version - 1.8]

• Contents
• Usage
• Authentication
• Token API
  • Token URL
  • Password
  • Steps
• Common API Parameters
• Responses
• CallActionResponse
• Entities
  • Call
  • Agent Name ID Pair
  • Lead Phone
  • Campaign
  • ACD (Skill) Queue
  • Result Code
• Methods
• Log In
• Log Out
• Get Calls
• Go Ready
• Go Not Ready
• Request Break
• Dial
• Dial Ext
• Dial Preview
• Shotgun Dial
• Hangup
• Dispose
• Hold
• Retrieve
• Start Recording
• Stop Recording
• Campaigns
• Users
• Result Codes
• ACD Queues
• Lead Phones
• Change Lead Phone
• Create New Lead
• Connect Calls
• Transfer To User
• Complete Transfer
• Appendix 
  • Appendix 1: Response Codes
  • Appendix 2: Record/Phone Types
  • Appendix 3: Recording States
  • Appendix 4: Break Codes
  • Appendix 5: Result Codes
  • Appendix 6: Call Statuses
  • Appendix 7: Call States
  • Appendix 8: Cause Values

Usage

This API is designed as an Agent Remote Control. The API commands will control an already existing agent that is currently logged into the system.

Authentication

An authentication token is required to access this API. A token can be requested from the token service using the Token API.

Tokens API

All API methods require a security token to use the system. This token is stored in the HTTP cookie to allow multiple API calls from one authentication request.

A token is requested by authenticating with a user and password combination. The Token service API will return a token on success.

Token URL

https://[CUSTOMER].maxcontact.com/webservices/services/apitoken/login/{login}

Password

The password needs to be sent in the authorization header of the request; the password needs to be converted to Base64 with ASCII encoding to get the bytes[] from the password string.

Steps

1. Make a request to the token Uri
2. Store token key for any subsequent requests
3. Make request to the Callbacks API

Recommendations

• It is recommended that you keep track of the Token Key and its expiry as making a request every time can slow down the import process.
• Login should be plain text.

When a successful API call is made to the API Token service, it will return a json/xml object A token key must be passed to each API endpoint along with the request.

Common API Parameters

The following is a list of common parameters that are used by a significant number of the API methods, along with details of what each parameter represents.

• Call Id – The unique integer id of particular call, these Ids are maintained in- memory within the system, with values starting at 1,000 each time the system starts up.
• Campaign Id – The unique identifier of a particular campaign as recorded in the correspondingly named table in the system’s database.
• CLI (Caller ID) – for inbound calls this is the number that the customer is dialling from (if supplied).
• Lead Id – Unique id of a particular campaign as recorded in the correspondingly named table in the database.
• Lead Phone Id – Unique id for each phone linked to a particular lead, these values can be found in the database.
• List Id – When leads are imported into the system they are grouped together into lists this is the unique id of a particular list as recorded in the database.
• Reference Id – When importing leads into the system it is possible to supply an external reference number (e.g. a customer Id from an external CRM system etc). Reference Id parameters allow the caller to supply one of these external reference numbers in place of other parameters (e.g. lead Id or Phone Number etc.).
• Result Code – When an agent completes a call with a customer they are required to select a result code that outlines the outcome of the call. A list of the result codes included by default with the system is available in the appendix, but it is worth noting that it is possible to configure this list of the result codes to meet the needs of your business.
• User Id – Unique id of a particular user (often representing an agent) as recorded in the corresponding table in the database.

Responses

The API by default will return an XML response, but Accept and Content-Type headers with values of application/json can be supplied in your requests if desired and this will result in the API returning JSON formatted responses.

CallActionResponse

All methods will return a CallActionResponse object. The “data” property will be a different type dependent on the method used.

{
Success: Bool,
Data: This type is dependent on the method used, entities are described below
ResponseCode: int,
ResponseDetail: string
}

{
CallId: int,
CallStartTime: dateTime,
CallState: int,
CallStatus: int,
CustomerName: string,
CustomerName2: string,
PhoneNumber: string,
RecordingState: int
CauseValue: int
}

{
FullName: string,
ID: int
}

{
LeadId: int64,
PhoneNumber: string,
RecordType: string,
RecordTypeId: int
}

{
CampaignID: int
CampaignName: string
Type: string
Active: boolean
AlwaysRun: boolean
AutoRecord: boolean
BlackoutDates: string array
MaxLines: int
CallerID: string
...

{
AbandonThreshold: int
AcceptableQueueTime: int
AcdIcon: string
AcdName: string
Active: boolean
DefaultTimeout: int
DefaultTimeoutIvr: int
ID: int
…
}

{
Code: string
Description: string
IsAgentViewable: boolean
IsCallAgain: boolean
IsCallback: boolean
IsSuccess: boolean
…
}

POST
/webservices/services/telephony/login
Body:
{
UserId: int
CampaignId: int
Extension: string
}
Returns:
CallActionResponse containing integer result code

POST
/webservices/services/telephony/logout
Body:
{
UserId: int
CampaignId: int
}
Returns:
CallActionResponse containing integer result code

GET
/webservices/services/telephony/getcalls/user/{userId}
Params:
userId: int
Returns:
CallActionResponse containing an array of Calls

GET
/webservices/services/telephony/goready/user/{userId}
Params:
userId: int
Returns:
CallActionResponse containing integer result code

PATCH
/webservices/services/telephony/gonotready/user/{userId}
Params:
userId: int
Returns:
CallActionResponse containing integer result code

PATCH
/webservices/services/telephony/gotobreak/user/{userId}
Params:
userId: int
Body:
{
BreakId: int
}
Returns:
CallActionResponse containing integer result code

GET
/webservices/services/telephony/dial/user/{userId}/phone/{PhoneNum}?leadid
={leadId}&campaignId={campaignId}
Params:
userId: int
phoneNum: string
leadId: long
campaignId: int
Returns:
CallActionResponse containing Call data

POST
/webservices/services/telephony/dialext
Body:
{
UserId: int
PhoneNum: string
CampaignId: int
CLI: string
LeadId: long
ListId: int
ReferenceId: string
UniqueRef: string
AdvancedLeadLookUp: Boolean
}
Returns:
CallActionResponse containing Call data

PATCH
/webservices/services/telephony/placepreviewdial/user/{userId}/call/{callId}
Params:
userId: int
callId: int
Returns:
CallActionResponse containing integer result code

POST
/webservices/services/telephony/shotgun-dial
Body:
{
UserId: int
PhoneNumbers: string[] – max 5 numbers
LeadId: long
ReferenceId: string
ListId: int
CampaignId: int
CLI: string
UniqueRef: string
}
Returns:
CallActionResponse containing an array of CallIds

GET
/webservices/services/telephony/hangup/user/{userId}/call/{callId}
Params:
userId: int
callId: int
Returns:
CallActionResponse containing integer result code

GET
/webservices/services/telephony/dispose/user/{userId}/call/{callId}?resultCod
e={resultCode}
Params:
userId: int
callId: int
resultCode: string
Returns:
CallActionResponse containing integer result code

GET
/webservices/services/telephony/hold/user/{userId}/call/{callId}
Params:
userId: int
callId: int
Returns:
CallActionResponse containing integer result code

GET
/webservices/services/telephony/retrieve/user/{userId}/call/{callId}
Params:
userId: int
callId: int
Returns:
CallActionResponse containing integer result code

GET
/webservices/services/telephony/startrecord/user/{userId}/call/{callId}
Params:
userId: int
callId: int
Returns:
CallActionResponse containing an array of Calls

GET
/webservices/services/telephony/stoprecord/user/{userId}/call/{callId}
Params:
userId: int
callId: int
Returns:
CallActionResponse containing an array of Calls

GET
/webservices/services/telephony/campaigns/user/{userId}
Params:
userId: int
Returns:
CallActionResponse containing an array of Campaigns

GET
/webservices/services/telephony/users/user/{userId}
Params:
userId: int
Returns:
CallActionResponse containing an array of agent names and ids

GET
/webservices/services/telephony/resultcodes/user/{userId}
Params:
userId: int
Returns:
CallActionResponse containing an array of result codes

GET
/webservices/services/telephony/acdqueues/user/{userId}
Params:
userId: int
Returns:
CallActionResponse containing an array of ACD queues

GET
/webservices/services/telephony/leadphones/user/{userId}/lead/{leadId}
Params:
userId: int
leadId: long
Returns:
CallActionResponse containing an array lead phones

GET
/webservices/services/telephony/changelead/user/{userId}/call/{callId}/leadp
hone/{leadPhoneId}
Params:
userId: int
callId: int
leadPhoneId: int64
Returns:
CallActionResponse containing integer result code

GET
/webservices/services/telephony/createnewlead/user/{userId}/call/{callId}/ph
one/{phoneNum}
Params:
userId: int
callId: int
phoneNum: string
Returns:
CallActionResponse containing integer result code

GET
/webservices/services/telephony/connectcalls/user/{userId}?call1={call1Id}&cal
l2={call2Id}&resultcode1={resultCode1}&resultcode2={resultCode2}&notes1={no
tes1}&notes2={notes2}&numsales1={numSales1}&numsales2={numSales2}
Params Required:
userId: int
call1Id: int
call2Id: int
resultCode1: string
resultCode2: string
Params Optional:
notes1: string
notes2: string
numSales1: int
numSales2: int

POST
/webservices/services/telephony/transfertouser
Body:
{
SendingUserId: int
ReceivingUserId: int
CallId: int
IsAttended: boolean
ResultCode: string
}
Returns:
CallActionResponse containing integer result code

POST
/webservices/services/telephony/transfertouser
Body:
{
SendingUserId: int
ReceivingUserId: int
CallId: int
IsAttended: boolean
ResultCode: string
}
Returns:
CallActionResponse containing integer result code