Buzzeasy Callback API
> WARNING: This API is no longer actively worked on and will be deprecated in the near future. Please use Buzzeasy - Unified API
Introduction
Document Purpose
The purpose of this document is to provide the Web Service Interface Contract for the "buzzeasy" solution.
Audience
This document is intended for the readership of all parties concerned with the design and implementation of the solution.
Overview
Buzzeasy provides a Web Service for use to integrate with the Buzzeasy platform. This exposes functionality to request different types of call backs depending on requirement. The functions available are detailed in Section "Request Callback Service" onwards.
Endpoints
The Buzzeasy web services provide a SOAP endpoint|to provide inter-operability across all technologies.
Alternatively, a REST endpoint|is available for integration so requests can also be made via HTTPS
GET.
Security
Please consult with Buzzeasy team regarding access to the web service.
Request Callback Service
RequestCallWhenAvailable
This sends a request to call the user when an agent has been retrieved. The function allows the authorized user to input the destination number with 10 optional fields
Method header
ResponseMessage RequestCallWhenAvailable(string|name, string|phoneNo, int
serviceQueue, int|company, string|password, string|region = null, string|field1 =
null, string|field2 = null, string|field3 = null, string|field4 = null, string|field
= null, string|field6 = null, string|field7 = null, string|field8 = null, string
field9 = null, string|field10 = null)
Parameters
| Name | Type | Description |
|---|---|---|
| name | string | The full name of the requestor. |
| phoneNo | string | The phone number the requestor would like to be reached on. This must be in E.164 format if the region is not supplied. |
| serviceQueue | int | The service queue (ID) that the call wishes to use. This is supplied by Buzzeasy during the setup phase. |
| company | int | The company (ID) the call wishes to use. This is supplied by Buzzeasy during the setup phase. |
| password | string | The password associated with the company. This is supplied by Buzzeasy during the setup phase. |
| region | string | The region of the phone number. This region will be used if the phone number has not been formatted in E.164 format. Please see Appendix A for list of valid regions |
| field1 | string | An optional field that can be used to include further information regarding the request/call |
| field2 | string | An optional field that can be used to include further information regarding the request/call |
| field3 | string | An optional field that can be used to include further information regarding the request/call |
| field4 | string | An optional field that can be used to include further information regarding the request/call |
| field5 | string | An optional field that can be used to include further information regarding the request/call |
| field6 | string | An optional field that can be used to include further information regarding the request/call |
| field7 | string | An optional field that can be used to include further information regarding the request/call |
| field8 | string | An optional field that can be used to include further information regarding the request/call |
| field9 | string | An optional field that can be used to include further information regarding the request/call |
| field10 | string | An optional field that can be used to include further information regarding the request/call |
Returns
| Name | Type | Description |
|---|---|---|
| ConfirmationCode | string | The confirmation code (reference no.) of the request. This can be used to amend or cancel the request. If there is no confirmation code, the request failed. |
| ResultCode | int | The result code of the request. ( Please see below for result code table) |
Result codes
| Result Code | Description |
|---|---|
| 0 | Request successful |
| 1 | Invalid format number |
| 2 | Unable to connect to remote location |
| 3 | Out of hours |
| 4 | Not in white list |
| 5 | Is in black list |
| -1 | Authentication Failed |
Method Body
The method requires an object in JSON with the properties mentioned in the parameters section e.g:
{
"name":"User",
"phoneNo":"+4477794531150",
"serviceQueue":"1",
"company":"1",
"password":"Password",
"field1":"test"
}
Type
The method is of HTTP POST type.
REST URL
The following URL format is required to call the REST endpoint;
https://testservice.buzzeasy.com/RequestCallbackService/Service.svc/rest/RequestCallWhenAvailable
Please Note: Any parameters are not supplied will be passed as NULL, so if field parameters are not required then they do not need to be included in the body.
GetAvailableTimes
This requests the time slots for the requested date from the server after a given time. It returns all values in an array
Method header
TimeSlot[] GetAvailableTimes(int|serviceQueue, int|company, string|password, DateTime requestedDate);
Parameters
| Name | Type | Description |
|---|---|---|
| serviceQueue | int | The service queue (ID) that the call wishes to use. This is supplied by Buzzeasy during the setup phase. |
| requestedDate | DateTime | The date and time after which the timeslots are being requested |
| company | int | The company (ID) the call wishes to use. This is supplied by Buzzeasy during the setup phase. |
| password | string | The password associated with the company. This is supplied by Buzzeasy during the setup phase. |
Returns
An Array of Timeslot objects which have the following fields.
| Name | Type | Description |
|---|---|---|
| TimeSlotID | int | Database ID of the timeslot |
| TimeTo | string | string representation of the end date and time of the slot (yyyy-MM-dd HH-mm-ss) |
| TimeFrom | string | string representation of the start date and time of the slot (yyyy-MM-dd HH-mm-ss) |
| Available | Bool | Whether the slot is usable (should always be true) |
Method body
The method requires an object in JSON with the properties mentioned in the parameters section e.g.:
{
"serviceQueue": "1",
"requestedDate": "2017-04-11 09:00:00",
"company": "1",
"password": "P@ssword"
}
Type
The method is of HTTP POST type.
REST URL
https://testservice.buzzeasy.com/RequestCallbackService/Service.svc/rest/GetAvailableTimes
Please Note: Any parameters are not supplied will be passed as NULL, so if field parameters are not required then they do not need to be included in the URL.
GetNextThreeTimeslots
This requests the next three available timeslots from the server after a given time. It returns up to three values in an array
Method header
TimeSlot[] GetNextThreeTimeSlots(int|serviceQueue, DateTime time, int|company, string
password)
Parameters
| Name | Type | Description |
|---|---|---|
| serviceQueue | int | The service queue (ID) that the call wishes to use. This is supplied by Buzzeasy during the setup phase. |
| time | DateTime | The date and time after which the timeslots are being requested |
| company | int | The company (ID) the call wishes to use. This is supplied by Buzzeasy during the setup phase. |
| password | string | The password associated with the company. This is supplied by Buzzeasy during the setup phase. |
Returns
An Array (size 3 or less) of Timeslot objects which have the following fields.
| Name | Type | Description |
|---|---|---|
| TimeSlotID | int | Database ID of the timeslot |
| TimeTo | string | String representation of the end date and time of the slot (yyyy-MM-dd HH-mm-ss) |
| TimeFrom | string | String representation of the start date and time of the slot (yyyy-MM-dd HH-mm-ss) |
| Available | Bool | Whether the slot is usable (should always be true) |
Method body
The method requires a object in JSON with the properties mentioned in the parameters section e.g.:
{
"serviceQueue":"1",
"requestedDate":"2017-04-11 09:00:00",
"company":"1",
"password":"P@ssword"
}
Type
The method is of HTTP POST type.
REST URL
https://testservice.buzzeasy.com/RequestCallbackService/Service.svc/rest/GetNextThreeTimeSlots
Please Note: Any parameters are not supplied will be passed as NULL, so if field parameters are not required then they do not need to be included in the URL.
UpdateEWTRecord
This function sets the current EWT record for the given service queue. It returns whether the request was successful or not.
Method Header
bool UpdateEWTRecord(int|serviceQueue, int|ewt, int|company, string|password)
Parameters
| Name | Type | Description |
|---|---|---|
| serviceQueue | int | The service queue (ID) that the call wishes to use. This is supplied by Buzzeasy during the setup phase. |
| ewt | int | Value of current EWT in minutes |
| company | int | The company (ID) the call wishes to use. This is supplied by Buzzeasy during the setup phase. |
| password | string | The password associated with the company. This is supplied by Buzzeasy during the setup phase. |
Returns
Boolean representing whether the update was performed successfully or not.
Method body
The method requires an object in JSON with the properties mentioned in the parameters section e.g.:
{
"serviceQueue":"1",
"ewt":"1",
"company":"1",
"password":"P@ssword"
}
Type
The method is of HTTP POST type.
REST URL
https://testservice.buzzeasy.com/RequestCallbackService/Service.svc/rest/UpdateEWTRecord
Please Note: Any parameters are not supplied will be passed as NULL, so if field parameters are not required then they do not need to be included in the URL.
GetEWTByServiceID
Returns the EWT of the given service queue in minutes
Method Header
int|GetEWTByServiceID(int|serviceQueueID, int|companyID, string|password)
Parameters
| Name | Type | Description |
|---|---|---|
| serviceQueueID | int | The service queue (ID) that the call wishes to use. This is supplied by Buzzeasy during the setup phase. |
| companyID | int | The company (ID) the call wishes to use. This is supplied by Buzzeasy during the setup phase. |
| password | string | The password associated with the company. This is supplied by Buzzeasy during the setup phase. |
Returns
int representing the current EWT for the service queue in minutes
Method body
The method requires an object in JSON with the properties mentioned in the parameters section
{
"serviceQueue":"1",
"company":"1",
"password":"P@ssword"
}
Type
The method is of HTTP POST type.
REST URL
https://testservice.buzzeasy.com/RequestCallbackService/Service.svc/rest/GetEWTByServiceID
Please Note: Any parameters are not supplied will be passed as NULL, so if field parameters are not required then they do not need to be included in the URL.
RequestCallSchedule
This sends a request to call the user at a specific time slot when an agent has been retrieved. The timeslot must be collected from the TimeSlot web method. The function allows the authorized user to input the destination number with 10 optional fields
Method Header
ResponseMessage RequestCallSchedule(string|name, string|phoneNo, int|timeslot, DateTime date, int|serviceQueue, int|company, string|password, string|region = null, string|field1 = null, string|field2 = null, string|field3 = null, string|field4 = null, string|field5 = null, string|field6 = null, string|field7 = null, string|field = null, string|field9 = null, string|field10 = null);
Parameters
| Name | Type | Description |
|---|---|---|
| name | string | The full name of the requestor. |
| phoneNo | string | The phone number the requestor would like to be reached on. This must be in E.164 format if the region is not supplied. |
| timeslot | int | The timeslot identity returned from retrieval of available timeslots e.g. 09:30 – 10:00 = 4 |
| date | datetime | the date of the schedule call request. This will be used with the timeslot to determine the time of call. |
| serviceQueue | int | The service queue (ID) that the call wishes to use. This is supplied by Buzzeasy during the setup phase. |
| company | int | The company (ID) the call wishes to use. This is supplied by Buzzeasy during the setup phase. |
| password | string | The password associated with the company. This is supplied by Buzzeasy during the setup phase. |
| region | string | The region of the phone number. This region will be used if the phone number has not been formatted in E.164 format. Please see Appendix A for list of valid regions |
| field1 | string | An optional field that can be used to include further information regarding the request/call |
| field2 | string | An optional field that can be used to include further information regarding the request/call |
| field3 | string | An optional field that can be used to include further information regarding the request/call |
| field4 | string | An optional field that can be used to include further information regarding the request/call |
| field5 | string | An optional field that can be used to include further information regarding the request/call |
| field6 | string | An optional field that can be used to include further information regarding the request/call |
| field7 | string | An optional field that can be used to include further information regarding the request/call |
| field8 | string | An optional field that can be used to include further information regarding the request/call |
| field9 | string | An optional field that can be used to include further information regarding the request/call |
| field10 | string | An optional field that can be used to include further information regarding the request/call |
Returns
| Name | Type | Description |
|---|---|---|
| ConfirmationCode | string | The confirmation code (reference no.) of the request. This can be used to amend or cancel the request. If there is no confirmation code, the request failed. |
| ResultCode | int | The result code of the request. |
Please see below for result code table
| Result Code | Description |
|---|---|
| 0 | Request successful |
| 1 | Invalid format number |
| 2 | Unable to connect to remote location |
| 3 | Out of hours |
| 4 | Not in white list |
| 5 | Is in black list |
| -1 | Authentication Failed |
Method body
The method requires a object in JSON with the properties mentioned in the parameters section e.g.:
{
"name":"User",
"phoneNo":"+4477794531150",
"serviceQueue":"1",
"company":"1",
"password":"Password",
"field1":"test",
"date":"2017-04-11 00:00:00",
"timeslot":"1"
}
Type
The method is of HTTP POST type.
REST URL
The following URL format is required to call the REST endpoint;
https://testservice.buzzeasy.com/RequestCallbackService/Service.svc/rest/RequestCallSchedule
Please Note: Any parameters are not supplied will be passed as NULL, so if field parameters are not required then they do not need to be included in the URL.
Event Notification Service
Buzzeasy provide a service for applications to track the progress of the request in real time to a web application. The following diagram shows the architecture and flow for the event notification service;
- Client sends a connect command to the Service.
- Client sends a subscribe request to the service. The request should include the confirmation code desired to subscribe to. When this has been requested, all status updates relating to the confirmation code will be sent to the client.
- Every status update related to clients subscription, the service will call a method called "UpdateStatus(string|confCode, string|status)" in your javascript code. This will happen many times depending on status of call.
- When call has been completed or events are no longer required, send a disconnect request to the service to unsubscribe.
Integration
In order to integrate to the service, the following Javascript (or similar) is required to be inserted into your web page; (the highlighted fields will be sent to you by Buzzeasy)
<!--Script references. -->
<!--Reference the jQuery library. -->
<script src="Scripts/jquery-1.9.1.min.js" ></script>
<!--Reference the SignalR library. -->
<script src="Scripts/jquery.signalR-2.1.2.min.js"></script>
<!--Add script to update the page and send messages.-->
<script type="text/javascript">
jQuery.support.cors = true;
$(function () {
// connect to the hubs
var connection = $.hubConnection("http://localhost:64819");
var notifyme = connection.createHubProxy('NotifyMe');
// Create a function that the hub can call to update the status of call
notifyme.on("updateStatus", function (confcode, callstatus) {
/*
*
* YOUR CODE GOES HERE
*
*/
});
notifyme.on("closeConnection", function () {
connection.stop();
});
// Start the connection.
connection.start().done(function () {
$('#subscribecode').click(function () {
// Call the Subscribe method on the hub using confirmation code.
notifyme.invoke("Subscribe",confirmationCode);
// Clear text box and reset focus for next comment.
}).fail(function () {
/*
YOUR CODE GOES HERE
*/
});
});
</script>
Events
CallingUser
Buzzeasy is currently calling the user (the requested caller).
UserConnected
The requested caller is now connected.
CallingUserFailed
The requested caller has not been able to be reached. Various reasons could be not picked up, voicemail or no network coverage.
CallingAgent
Buzzeasy is currently calling the queue/agent
AgentConnected
The queue/agent has connected and the call is waiting for a representative to become available.
CallAccepted
The agent has accepted to take the call. This status may be ignored in most circumstances.
CallSucceeded
The call has been completed.
CallFailed
The call has failed. It has exceeded the configured timeout or exceeded the retry attempts.
Rescheduled
The user could not be reached and the call has been rescheduled.
BuzzMeInfo Service
Buzzeasy provides an interface to collect additional data from the current request. This is used when the call has arrived but further information such as inputted data is required for a screen pop to an agent.
GetCallDataByNumber
This sends a request to retrieve information regarding a call using the queue presented number (CLI).
Method Header
CallData GetCallDataByNumber(string|presentedNumber, int|companyId, string|password);
Parameters
| Name | Type | Description |
|---|---|---|
| presentedNumber | string | The full presented number / CLI of the call placed into the queue. |
| companyId | int | The company (ID) the call wishes to use. This is supplied by buzzeasy during the setup phase. |
| password | string | The password associated with the company. This is supplied by buzzeasy during the setup phase. |
Returns
| Name | Type | Description |
|---|---|---|
| CustomerName | string | The full name of the requestor. |
| UserPhoneNo | string | The phone number the requestor would like to be reached on |
| serviceQueueName | string | The Service Queue name the callback originated from |
| Retries | int | The retry attempt number of the request. |
| field1 | string | Data inputted into field1. This will return in the format FieldName | FieldValue |
| field2 | string | Data inputted into field2. This will return in the format FieldName | FieldValue |
| field3 | string | Data inputted into field3. This will return in the format FieldName | FieldValue |
| field4 | string | Data inputted into field4. This will return in the format FieldName | FieldValue |
| field5 | string | Data inputted into field5. This will return in the format FieldName | FieldValue |
| field6 | string | Data inputted into field6. This will return in the format FieldName | FieldValue |
| field7 | string | Data inputted into field7. This will return in the format FieldName | FieldValue |
| field8 | string | Data inputted into field8. This will return in the format FieldName | FieldValue |
| field9 | string | Data inputted into field9. This will return in the format FieldName | FieldValue |
| field10 | string | Data inputted into field10. This will return in the format FieldName,FieldValue |
| ConfirmationCode | string | The confirmation code of the request made. This is supplied to the user on completion of request |
| ScheduledTime | string | The Time the callback was scheduled for |
REST
The following URL format is required to call the REST endpoint;
https://testinfo.buzzeasy.com/BuzzMeInfo/InfoService.svc/rest/GetCallDataByNumber?presentedNumber=<presentedNumber>&companyId=<companyId>&password=<password>
Please Note: Any parameters are not supplied will be passed as NULL, so if field parameters are not required then they do not need to be included in the URL.
GetCallDataByPin
This sends a request to retrieve information regarding a call using a short PIN.
Method Header
CallData GetCallDataByPin(string|pin, int|companyId, string|password);
Parameters
| Name | Type | Description |
|---|---|---|
| pin | string | The pin number of the request |
| companyId | int | The company (ID) the call wishes to use. This is supplied by buzzeasy during the setup phase. |
| password | string | The password associated with the company. This is supplied by buzzeasy during the setup phase. |
Returns
| Name | Type | Description |
|---|---|---|
| CustomerName | string | The full name of the requestor. |
| UserPhoneNo | string | The phone number the requestor would like to be reached on |
| serviceQueue | int | The service queue (ID) that the call wishes to use. This is supplied by buzzeasy during the setup phase. |
| Retries | int | The retry attempt number of the request. |
| field1 | string | Data inputted into field1. This will return in the format FieldName,FieldValue |
| field2 | string | Data inputted into field2. This will return in the format FieldName,FieldValue |
| field3 | string | Data inputted into field3. This will return in the format FieldName,FieldValue |
| field4 | string | Data inputted into field4. This will return in the format FieldName,FieldValue |
| field5 | string | Data inputted into field5. This will return in the format FieldName,FieldValue |
| field6 | string | Data inputted into field6. This will return in the format FieldName,FieldValue |
| field7 | string | Data inputted into field7. This will return in the format FieldName,FieldValue |
| field8 | string | Data inputted into field8. This will return in the format FieldName,FieldValue |
| field9 | string | Data inputted into field9. This will return in the format FieldName,FieldValue |
| field10 | string | Data inputted into field10. This will return in the format FieldName,FieldValue |
| ConfirmationCode | string | The confirmation code of the request made. This is supplied to the user on completion of request |
| TimeCalled | string | The Time the request has been made. |
REST
The following URL format is required to call the REST endpoint;
https://testinfo.buzzeasy.com/BuzzMeInfo/InfoService.svc/rest/GetCallDataByPin?pin=<pin>&companyId=<companyId>&password=<password>
Please Note: Any parameters are not supplied will be passed as NULL, so if field parameters are not required then they do not need to be included in the URL.
Appendix A – Regions
The following table states the available regions able to pass into call requests;
| Region | Code |
|---|---|
| Great Britain | GB |
| Ireland | IE |