TABLE OF CONTENTS [Document Version - 1.0]

• Contents
• Usage
• Authentication
• Tokens API
  • Token URL
  • Password
  • Steps
• Common API Parameters
• Important Notes
• Responses
  • CallbackResponse
  • DialCallbackResponse
• Methods
  • Get Callback
  • Get Callbacks by User ID
  • Create Callback
  • Update Callback
  • Delete Callback
  • Dial Callback
• Appendix
  • Appendix 1: Windows Time Zones

Usage

This API is designed as a Management Remote Control. The API methods allow the caller to perform the following actions.

• Retrieve Existing Callbacks
• Create, Update & Delete Callbacks
• Dial an Existing Callback

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 some common parameters that are used by a number of the API methods, along with details of what each parameter represents.

• Callback Id – This is the unique id of a callback once created by the system as recorded in the MaxContact database.
• Lead Id – This is the unique id of a particular lead, lead ids can be accessed via the ‘Lead Search and Edit’ page in Manager Portal.
• Lead Phone Id – This is the unique id of a particular phone belonging to a lead these values can be obtained from the correspondingly named table in the MaxContact 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. List Ids can be obtained from the ‘Lists’ page in Manager Portal
• User Id – Unique id of a particular user within the system, user ids can be obtained from the CTU page (Campaigns, Team and Users) within Manager Portal.
• Notes – Optional free-text note supplied by the caller. It is worth noting that notes containing certain characters (i.e. < > “ ‘) will be escaped as a security precaution.

Important Notes

• Where date time values are supplied to the API (either as query parameters or within the body of the request) they should be formatted in ISO8601 format (‘yyyy-mm-ddThh:mm:ss’)
• Dates and times will be treated as being within the time zone of the web server (assuming no offset is supplied).
• The TimeZoneId value used by a number of the methods is an integer (from 1 to 138) relating to the Windows Time Zone of the end customer to be called. A default value of 0 is also allowed if the time zone id is unknown consult the appendix for a full list of the Windows Time Zones that are supported.
• When creating or updating a callback the supplied callback time must be in the future (i.e. callbacks cannot be created or updated to dates and times in the past).
• It is worth noting that the Dial Callback API method sends instructions to the live CCaaS system. A successful response from this API method simply indicates that the instruction has been relayed to the system but, this does not indicate that the requested action was necessarily successful. For instance, if an instruction is sent to dial a callback when the agent is not logged into the system or they are already talking to a customer then the instruction from the API will be ignored by the system

Responses

All endpoints return either JSON or XML depending on the Accept header. Successful responses return a CallbackResponse or DialCallbackResponse object. Errors return standard HTTP status codes with optional error messages.

CallbackResponse

The CallbackResponse (or an array of these responses) is returned by the majority of the API methods including Create, Get, Update etc.

{
"Id": int,
"PhoneNumber": string,
"ListId": int,
"LeadId": int,
"LeadPhoneId": int,
"UserId": int,
"TimeZoneId": int,
"CallDateTime": datetime,
“Notes”: string
}

{
"CallbackId": int,
"IsSuccess": bool,
"CallId": string,
"Message": string,
"DialedAt": datetime
}

GET
/webservices/services/callbacks/{CallbackID}
Params:
CallbackID: int
Returns:
CallbackResponse

GET
/webservices/services/callbacks/{UserID}?startDate={StartDate}&endDate={En
dDate}
Params:
UserID: int
StartDate: Start date time string (in ISO8601 format)
EndDate: End date time string (in ISO8601 format)
Returns:
CallbackResponse[]

POST
/webservices/services/callbacks
Body:
{
"UserId": int,
"LeadPhoneId": int,
"CallDateTime": datetime,
"TimeZoneId": int,
“Notes”: string
}
Returns:
CallbackResponse

PUT
/webservices/services/callbacks/{CallbackID}
Params:
CallbackID: int
Body:
{
"UserId": int?,
"CallDateTime": datetime?,
“Notes”: string
}
Returns:
CallbackResponse

DELETE
/webservices/services/callbacks/{CallbackID}
Params:
CallbackID: int
Returns:
No content

POST
/webservices/services/callbacks/{CallbackID}/dial
Params:
CallbackID: int
Returns:
DialCallbackResponse