Telephony API

This API acts as your Agent Remote Control. Use it to control an agent who is already logged into the system, for example to change their status, dial or dispose of a call, or transfer a call to another agent.

TABLE OF CONTENTS [Document Version - 1.9]

• 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
  • 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

Authentication

You need an authentication token to access this API. Request a token from the token service using the Token API.

Token API

Every API method requires a security token. This token is stored in the HTTP cookie so you can make multiple API calls from one authentication request. Request a token by authenticating with a user and password combination. The Token service API returns a token on success.

Token URL

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

Password

Send the password in the authorization header of the request. Convert the password to Base64 with ASCII encoding to get the bytes[] from the password string.

Steps

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

A successful call to the API Token service returns a JSON or XML object. Pass the token key with every API request.

Common API Parameters

The following common parameters are used across a significant number of the API methods.

• Call Id – The unique integer Id of a 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 the customer is dialling from, if supplied.
• Lead Id – Unique Id of a particular lead as recorded in the correspondingly named table in the database.
• Lead Phone Id – Unique Id for each phone linked to a particular lead. You can find these values in the database.
• List Id – When leads are imported into the system, they're 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, you can supply an external reference number, for example a customer Id from an external CRM system. Use a reference Id parameter to supply one of these external reference numbers in place of other parameters, such as a lead Id or phone number.
• Result Code – When an agent completes a call with a customer, they 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. You can configure this list of result codes to meet your business needs.
• User Id – Unique Id of a particular user (often representing an agent) as recorded in the corresponding table in the database.

Responses

By default, the API returns an XML response. Supply Accept and Content-Type headers with a value of application/json in your request to receive JSON formatted responses instead.

CallActionResponse

Every method returns a CallActionResponse object. The “data” property’s type depends on the method used.

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

Entities

Call

Returned by /dial, and as an array by /getcalls. Represents an active call.

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

Agent Name ID Pair

Returned as an array by /users.

{
 FullName: string,
 ID: int
}

Lead Phone

Returned by /leadphones.

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

Campaign

Returned by /campaigns.

{
 CampaignID: int,
 CampaignName: string,
 Type: string,
 Active: boolean,
 AlwaysRun: boolean,
 AutoRecord: boolean,
 BlackoutDates: string array,
 MaxLines: int,
 CallerID: string,
 …
}

ACD (Skill) Queue

Returned as an array by /acdqueues.

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

Result Code

Returned as an array by /resultcodes. A list of the default result codes is available in the appendix.

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

Methods

Log In

Logs the agent into the system.

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

Log Out

Logs the agent out of the system.

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

Get Calls

Returns the current active calls for the specified user.

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

Go Ready

Puts the specified user into the ready status for the campaign they’re logged into.

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

Go Not Ready

Puts the specified user into the not ready status for the campaign they’re logged into.

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

Request Break

Requests to put the specified user into break status, using the break type specified by the Break Id.

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

Dial

Initiates a manual dial for the specified user to the given phone number. You can optionally specify a lead Id and campaign Id. By default, the number is matched to the newest lead. If there’s no match, the system creates a new lead.

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

Dial Ext

Initiates a manual dial for the specified user to the given phone number. The user Id and phone number are mandatory; all other parameters are optional.

When performing a manual dial, the system attempts to match a lead using the phone number, reference Id and list Id, if provided. Use this when the same phone number has multiple leads. If you supply a campaign Id, the call links to that campaign rather than the campaign the agent is currently on.

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

Dial Preview

When a user is assigned a Preview Dial, use this endpoint to trigger the dialling of the preview call. Set the call Id parameter to the integer Id of the call the agent is currently previewing.

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

Hangup

Hangs up the specified call and puts the agent into the wrapping status.

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

Dispose

Dispositions the specified call with the chosen result code. The call is also hung up if it hasn’t been already.

GET
/webservices/services/telephony/dispose/user/{userId}/call/{callId}?resultCode={resultCode}&goReady={goReady}
Params:
userId: int
callId: int
resultCode: string (required)
goReady: boolean (optional, default: false)
Returns:
CallActionResponse containing integer result code

goReady controls whether the agent returns to the ready state after the call is disposed.

Hold

Places the specified call on hold.

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

Retrieve

Retrieves the specified call from hold.

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

Start Recording

Starts or continues the recording for the specified call.

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

Stop Recording

Stops the recording of the specified call. Use this to prevent sensitive information, such as bank details, from being recorded.

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

Campaigns

Gets an object containing all the campaigns in the system.

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

Users

Gets an object containing the names and Ids of all users.

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

Result Codes

Gets an array of all the available result codes.

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

ACD Queues

Returns a list of ACD queues in the system, also known as skill queues.

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

Lead Phones

Returns the lead phones associated with the supplied lead Id.

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

Change Lead Phone

Changes the lead of a call that’s in progress. Supply a lead phone Id, and the call is associated with that lead phone’s corresponding lead.

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

Create New Lead

Creates a new lead with the specified phone number, then assigns the new lead to the specified call.

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

Connect Calls

Bridges two calls that are currently in progress together. Use this to perform a warm transfer to a third party or an external DDI. You can also specify a success count and notes relating to the call. The result codes and call Ids are required; notes and the number of successes are optional. A list of the default result codes is available in the appendix.

GET
/webservices/services/telephony/connectcalls/user/{userId}?call1={call1Id}&call2={call2Id}&resultcode1={resultCode1}&resultcode2={resultCode2}&notes1={notes1}&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
Returns:
CallActionResponse containing integer result code

Transfer To User

Begins the transfer of an existing call from one agent to another.

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

Complete Transfer

Completes the transfer of an existing call from one agent to another.

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

Appendix

Appendix 1: Response Codes

The following table lists the response codes returned by the API methods.

Appendix 2: Record/Phone Types

The following table lists the available phone types recorded against each record in the lead phone table. This value identifies what type of contact details the lead phone record relates to.

Appendix 3: Recording States

The following table lists the recording states the system supports.

Appendix 4: Break Codes

The following table lists the default break types included with the system. You can amend this list in the Manager Portal application.

Appendix 5: Result Codes

Result codes record the outcome of an interaction between an agent and an end customer, for example Sale, Callback or No Answer. The following table lists the result codes set up in the system when it’s shipped. You can edit this list in the Manager Portal application to meet your business requirements.

Appendix 6: Call Statuses

Calls typically pass through a number of statuses during their lifetime. The following table lists these call statuses.

Appendix 7: Call States

Calls typically pass through a number of states during their lifetime. The following table lists these call states.

Appendix 8: Cause Values

The following table lists the cause values the system supports.