Contact Expert v7.2 for Skype for Business Server

Contact Expert Agent Automation API

Overview

Contact Expert (CE) Automation API is a Microsoft .NET API to automate the agent client application instance running on an agent desktop PC. This programming interface exposes a wide range of agent, task and call specific methods/events. 3rd party developers can use Automation API to programmatically perform almost everything an agent can carry out on the agent application user interface.

API Reference

The code snippets below were created for demonstration purposes.

Initialization

This method is used for setting up an automation. The following method should be invoked:

Automation.Init()

After it is done, the following actions can be done by 3rd party applications:

subscribe to receive events when the agent state changes or a new task is received
sign agent into any media types supported by automation (voice, email, chat)

The following code snippet shows how to perform these initial steps:

try
{
    // Initializing (local) automation
    Agent client = Automation.Init(new LocalContext());

    // Subscribing for agent and task related events
    client.AgentStateChanged += new AgentStateChangedEventHandler(AgentStateChanged); client.TaskReceived += new TaskReceivedEventHandler(TaskReceived); client.ActionAvailabilityChanged += new ActionAvailabilityChangedEventHandler(ActionAvailabilityChanged); client.ServiceStateChanged += new ServiceStateChangedEventHandler(ServiceStateChanged);

    // Invoking asynchronous method to sign agent in
    client.BeginSignIn(MediaType.Voice, new Credentials(null, null, true), null, AgentSignIn_Finish, client);
 }
 catch (AutomationException aex) {
 }

Automation methods follow the Begin/End asynchronous pattern: actions can be initiated by invoking BeginXXX() and finished by invoking EndXXX(). The latter one should be invoked when the automation engine calls back the method passed to BeginXXX().

The following code snippet shows how to finish the above initiated login procedure:

// Method called back when login procedure is to be finished
private void AgentSignIn_Finish(IAsyncResult result)
{
    try {

            // Finishing asynchronous login procedure
            Agent client = result.AsyncState as Agent; client.EndSignIn(result);

    } catch (AutomationException aex) {
    }
}

Besides signing in agents, there are asynchronous methods to perform sign-out, change to active or auxiliary states using different reason codes.

Events

Agent State Changed Event

Each time an agent state change occurs (e.g.: SignedOut, WaitingForSignIn, Idle, Preview, OnConversation, Wrapup, TimedInactive, Auxiliary, WaitingForSignOut), subscribers receive the following event:

AgentStateChanged

The following code snippet shows how to process such events and e.g. how to go to break when the agent becomes idle:

// Event to indicate that agent state is changed
private void AgentStateChanged(object sender, AgentStateChangedEventArgs args)
{
    try {

        Agent client = sender as Agent;

        Console.WriteLine("Agent state is changed - media :" + args.Media + " new agent state: " + args.State + ". Reason: " + args.TransitionReason);

        if (args.State == AgentState.Idle) {
            // changing to break;
            client.BeginBreak(args.Media, client.GetWorkingCodes()[0], AgentBreak_Finish, client);
        }

    } catch (AutomationException aex) {
    }
}

private void AgentBreak_Finish(IAsyncResult result)
{
    try {

        Agent client = result.AsyncState as Agent; client.EndBreak(result);

    } catch (AutomationException aex) {
    }
}

Action Availability Changed Event

Each time the action state changes (Sign-in Agent, Sign-out Agent, Close Task, Reschedule Task, Refresh Task, Answer Customer Call, etc), the following event is received:

ActionAvailabilityChanged

Call State Changed Event

Each time the state of a call changes, the following event is received:

CallStateChanged

Such states include:

Idle state
Alerting agent
Connected to agent
Call is disconnected
Customer is on hold
Dialing customer
Customer is transferred
Customer and consultant is conferenced
Call is redirected from agent to somewhere else
Call is connected
etc

Call State Changed Event (agent ↔ customer call)

Each time the state of a call between an agent and a customer changes (Idle, Alerting, Connected, Disconnected, OnHold, Dialing, Transferred, Conferenced, Deflected) the following event is received:

CustomerCallStateChanged

The following code snippet shows how to process such events and e.g. how to pick up an incoming call:

// Event to indicate that call state between agent and customer is changed
private void CustomerCall_StateChanged(object sender, CallStateChangedEventArgs args)
{
    try {

        CustomerCall call = sender as CustomerCall;

        Console.WriteLine("Call state between agent and customer is changed - " + " new call state: " + args.State + " reason: " + args.TransitionReason);

        if (args.State == CallState.Alerting)
        {
            // Picking up the call
            call.BeginAnswer(CustomerCallAnswer_Finish, call);
        }

    } catch (AutomationException aex) {
    }
}

private void CustomerCallAnswer_Finish(IAsyncResult result)
{
    try {

        CustomerCall call = result.AsyncState as CustomerCall;
        call.EndAnswer(result);

    } catch (AutomationException aex) {
    }
}

Besides picking up alerting (ringing) calls, there are asynchronous methods to drop, hold, resume or transfer calls.

Call State Changed Event (agent ↔ consultant call)

Each time the state of a call between an agent and a consultant changes, the following event is received:

ConsultantCallStateChanged

The following code snippet shows how to process such events and e.g. how to setup conference between agent, customer and consultant after call between agent and consultant is established:

// Event to indicate that call state between agent and consultant is changed
private void ConsultantCall_StateChanged(object sender, CallStateChangedEventArgs args)
{
    try {

        ConsultantCall call = sender as ConsultantCall;

        Console.WriteLine("Call state between agent and consultant is changed - " + " new call state: " + args.State + " reason: " + args.TransitionReason);

        if (args.State == CallState.Connected) {
            call.BeginConference(ConferenceConsultant_Finish, call);
        }

    } catch (AutomationException aex) {
    }
}

private void ConferenceConsultant_Finish(IAsyncResult result)
{
    try {

        ConsultantCall call = result.AsyncState as ConsultantCall;
        call.EndConference(result);

    } catch (AutomationException aex) {
    }
}

Finished Event

If a certain method is completed, the following event is received:

AsynchMethodFinished

Examples include:

Sign-in agent
Sign-out agent
Change agent state to passive/break
Answer customer call
Disconnect customer call
Put customer on hold
Dial customer
etc

Service State Changed

If the automation service state changes, the following event is received:

ServiceStateChanged

Task Received Event

Each time the agent receives a new task, subscribers can receive the following event:

TaskReceived

Upon receiving TaskReceived event, the following additional task related events are available:

Event	Purpose
`TaskStateChanged`	to be notified when task changes state
`CustomerCall.CallStateChanged`	to be notified when call between agent and customer changes state
`ConsultantCall.CallStateChanged`	to be notified when call between agent and consultant changes state

// Event to indicate that a new task is received
private void TaskReceived(object sender, TaskReceivedEventArgs args)
{
    try {

        Agent client = sender as Agent;
        Task task = args.Task;

        Console.WriteLine("New task is received - SDU id :" + task.SduID +
            " media: " + task.Media + " campaign: " + task.CampaignID +
            " contact: " + task.ContactID + " direction: " + task.Direction +
            " dialing mode: " + task.DialingMode + " calling: " + task.Calling +
            " called: " + task.Called);

        // Subscribing for task related events
        task.TaskStateChanged += new TaskStateChangedEventHandler(TaskStateChanged);
        task.CustomerCall.CallStateChanged+= new CallStateChangedEventHandler(CustomerCall_StateChanged);
        task.ConsultantCall.CallStateChanged+= new CallStateChangedEventHandler(ConsultantCall_StateChanged);

    } catch (AutomationException aex) {
    }
}

TaskReceived event delivers useful information, such as the SDU ID, campaign ID and contact ID.

Using the SDU ID, 3rd party applications can manipulate data stored in the Session Data Unit (SDU).

Campaign ID and contact ID can be used to manipulate data in the contact record hosted on the SQL Server and can be used to invoke Client Access Server (CAS) web service methods to implement custom business processes.

Task State Changed Event

Each time a task state change happens (e.g.: Appended, Reloaded, Restarted, Parked, Closed) the following event is received:

TaskStateChanged

// Event to indicate that task state is changed
private void TaskStateChanged(object sender, TaskStateChangedEventArgs args)
{
    try {

        Task task = sender as Task;

        Console.WriteLine("Task state is changed - SDU id :" + task.SduID +
            " new task state: " + args.State + " reason: " + args.TransitionReason);

    } catch (AutomationException aex) {
    }
}

Methods

Method	Description
`IAsyncResult BeginSignIn(MediaType media, Credentials credentials, List<Preference> preferences, AsyncCallback callback, object state)`	Asynch method to start agent login procedure.
`void EndSignIn(IAsyncResult result)`	Method to finish the asynch agent login procedure.
`IAsyncResult BeginSignOut(MediaType media, AsyncCallback callback, object state)`	Asynch method to start agent logout procedure.
`void EndSignOut(IAsyncResult result)`	Method to finish asynch agent logout procedure.
`IAsyncResult BeginActivate(MediaType media, AsyncCallback callback, object state)`	Asynch method to move agent to active state.
`void EndActivate(IAsyncResult result)`	Method to finish agent activation procedure.
`IAsyncResult BeginBreak(MediaType media, WorkingCode reason, AsyncCallback callback, object state)`	Asynch method to move agent to passive/break mode.
`void EndBreak(IAsyncResult result)`	Method to finish moving agent to passive/break status.
`IAsyncResult BeginChangeBreakCode()`	Async method to change break code while the agent is on break.
`void EndChangeBreakCode(IAsyncResult)`	Method to finish the break code change while the agent is on break.
`List<BusinessTag> GetBusinessTags(int campaignID)`	Synch method to retrieve business tags for a given campaign. Use -1 as campaignID to retrieve business tags for all campaigns.
`List<WorkingCode> GetWorkingCodes()`	Synch method to retrieve working codes. This will not return un-selectable work codes, e.g. RONA or undefined entries.
`AgentState GetAgentState(MediaType media)`	Synch method to query current agent state.
`ActionState GetActionAvailability(ActionAvailability action, MediaType media)`	Synch method to query current action availability.
`ServiceState GetServiceState()`	Synch method to query current automation service state.
`IAsyncResult BeginLookupContactByPhone(int campaignID, string phone, AsyncCallback callback, object state)`	Asynch method to search for contact records based on phone number.
`List<ContactKey> EndLookupContactByPhone(IAsyncResult result)`	Method to finish looking up contact records based on phone number.
`IAsyncResult BeginLookupContactByEmail(int campaignID, string email, AsyncCallback callback, object state)`	Asynch method to search for contact records based on email address.
`List<ContactKey> EndLookupContactByEmail(IAsyncResult result)`	Method to finish looking up contact records based on email address.
`List<ContactData> GetContactData(ContactKey key)`	Synch method to retrieve data from the specified contact record.
`void UpdateContactData(ContactKey key, List<ContactData> data)`	Synch method to update data in the specified contact record. Pass only those contact data to the method which are changed. Doing that speeds up the update procedure.
`ContactCard GetContactCard(ContactKey key)`	Synch method to retrieve contact card belonging to the specified contact.
`void UpdateContactCard(ContactKey key, ContactCard card)`	Synch method to update contact card for the specified contact. Contact card can be received by invoking GetContactCard method. If you want to remove specific phone numbers from the contact card then set its value to empty string or null. Do not remove phone number items from the list. Just change their values.
`IAsyncResult BeginRetrieveContactByPhone(int campaignID, string phone, AsyncCallback callback, object state)`	Asynch method to retrieve the 1st contact from the given campaign who has the specified phone number.
`void EndRetrieveContactByPhone(IAsyncResult result)`	Method to finish retrieving contact from the given campaign.

Method	Description
`ConsultantCall(string sduID)`	Creates a new consultative call.
`IAsyncResult BeginDial(string uri, AsyncCallback callback, object state)`	Asynch method to start dialing consultant.
`void EndDial(IAsyncResult result)`	Method to finish dialing consultant.
`IAsyncResult BeginDrop(AsyncCallback callback, object state)`	Asynch method to start disconnecting consultant.
`void EndDrop(IAsyncResult result)`	Method to finish disconnecting consultant.
`IAsyncResult BeginConference(AsyncCallback callback, object state)`	Asynch method to join consultant to conference.
`void EndConference(IAsyncResult result)`	Method to finish joining consultant to conference.
`override void SendTone(string tone)`	Synch method to send DTMF tone.
`override CallState GetCallState()`	Synch method to query current call state.

Method	Description
`CustomerCall(string sduID)`	Creates a new customer call.
`IAsyncResult BeginAnswer(AsyncCallback callback, object state)`	Asynch method to start answering the call.
`void EndAnswer(IAsyncResult result)`	Method to finish answering call.
`IAsyncResult BeginDrop(AsyncCallback callback, object state)`	Asynch method to start disconnecting customer.
`void EndDrop(IAsyncResult result)`	Method to finish disconnecting customer.
`IAsyncResult BeginHold(AsyncCallback callback, object state)`	Asynch method to start putting customer on hold.
`void EndHold(IAsyncResult result)`	Method to finish putting customer on hold.
`IAsyncResult BeginUnhold(AsyncCallback callback, object state)`	Asynch method to start retrieving customer from hold.
`void EndUnhold(IAsyncResult result)`	Method to finish retrieving customer from hold.
`IAsyncResult BeginDial(AsyncCallback callback, object state)`	Asynch method to start dialing customer.
`void EndDial(IAsyncResult result)`	Method to finish dialing customer.
`IAsyncResult BeginTransfer(string uri, AsyncCallback callback, object state)`	Asynch method to start transferring customer to a specific URI.
`void EndTransfer(IAsyncResult result)`	Method to finish transferring customer.
`IAsyncResult BeginTransferToConsultant(AsyncCallback callback, object state)`	Asynch method to start transferring customer to consultant. Consultant call must be established first.
`void EndTransferToConsultant(IAsyncResult result)`	Method to finish transferring customer to consultant.
`override void SendTone(string tone)`	Synch method to send DTMF tone.
`void PauseRecording()`	Synch method to pause recording.
`void ContinueRecording()`	Synch method to continue recording.
`override CallState GetCallState()`	Synch method to query current call state.

Method	Description
`Task(string sduID, MediaType media, Direction direction, DialingMode dialingMode, int campaignID, int contactID, string calling, string called, Dictionary<string, object> properties)`	Task received by agent.
`override string ToString()`	Returns the string representation.
`void Close(ClosureCode reason, BusinessTag tag)`	Synch method to close the task.
`void Reschedule(SchedulingInfo info, BusinessTag tag)`	Synch method to reschedule the task
`void Refresh(bool restartScript)`	Synch method to reload the current script.
`TaskState GetTaskState()`	Synch method to query current task state.
`List<ContactData> GetContactData()`	Synch method to retrieve data from the contact record associated with the task.
`void UpdateContactData(List<ContactData> data)`	Synch method to update specific data items in contact record associated with the task.
`ContactCard GetContactCard()`	Synch method to retrieve contact card belonging to the contact associated with the task.
`void UpdateContactCard(ContactCard card)`	Synch method to update contact card belonging to the contact associated with the task.
`string GetSduData(string dataName)`	Synch method to retrieve data from the SDU.
`void Park()`	Synch method to park the email task.