5. Callers

VirtualQ.Callers

Line up a caller

When a caller decides to use virtualQ, the call center needs to "line up" the caller with virtualQ. For this purpose the phone number and a notification channel should be passed to virtualQ. Once lined up, the caller is registered with virtualQ and will be notified when up.

Method Call

    public async Task<Result> LineUpCaller(LineUpCallerParameters attributes)

LineUpCallerParameters

Property	Type	Description
LineId	long	(Required) The ID of the line to join
Phone	string	(Required) The callers phone number including country code, e.q. +40 171 1111 22 33
Channel	string	(Required) A string describing if the waiter expects a CallBack or if he will receive a SMS and will CallIn again
Source	string	(Required) A string describing the source where the caller came from, e.q. Widget, Phone, Mobile
Lang	string	A two letter language code, used when sending SMS to the caller, e.q. de, en
Skills	IEnumerable<string>	Array of Skills for caller
Properties	ExpandoObject	Dynamic object that can be extended with additional properties for caller

Setting up the Properties dynamic object

The Properties dynamic object is an ExpandoObject class, this means that an instance of this class can be extended with new properties of any type.

                dynamic properties = new ExpandoObject();
                properties.MyStringProp = "Value1";
                properties.MyArrayProp = new[] { 45, 25, 78 };
                properties.MyDateProp = DateTime.Now;
                properties.MyObjectProp = new { Id = 5, Value = "Value1" };

                LineUpCallerParameters attributes = new LineUpCallerParameters
                {
                    LineId = 3042,
                    Phone = "+17343305027",
                    Channel = "CallIn",
                    Source = "Phone",
                    Language = "en",
                    Skills = new string[] { "Skill1", "Skill2", "Skill3" },
                    Properties = properties
                };

For more information: ExpandoObject

API Request

https://docs.virtualq.io/#create-a-waiter

---

Verify a caller

A caller who has been notified by SMS will call again and served with the highest priority. However, in order to prevent misuse, the call center should verify with virtualQ if the caller is currently up.

Method Call

    public async Task<Result<bool>> VerifyCaller(CallerParameters attributes)

CallerParameters

Parameter	Type	Description
LineId	long	Line ID
Phone	string	Phone number of caller

Response

Value	Description
CallerResult	caller found, conains caller information
Null	caller not found

CallerResult

Property	Type	Description
Id	Nullable<long>	Caller ID
LineId	Nullable<long>	Line ID
Phone	string	The callers phone number including country code, e.q. +40 171 1111 22 33
Channel	string	A string describing if the waiter expects a callback or will receive a text message. Values: CallBack or CallIn
Source	string	A string describing the source where the caller came from. Values: Phone, Mobile, Widget, App, Other
Ewt	Nullable<int>	Estimated wait time
ConnectedAt	Nullable<DateTime>	Connection time
CreatedAt	Nullable<DateTime>	Creation time
EstimatedUpTimeAt	Nullable<DateTime>	Estimated time when up
NotifiedAt	Nullable<DateTime>	Notification time
UpdatedAt	Nullable<DateTime>	Last updated time
Properties	ExpandoObject	Custom properties
Skills	IEnumerable<string>	Skills
VirtualQCallerState	string	State of caller in virtualQ. Values: Waiting, Notified, Connected, Finished, TimeOut
WaitTime	Nullable<int>	Elapsed time the callers has waited

API Request

https://docs.virtualq.io/#list-waiters

---

Get a caller

Retrieves a specific caller by Line ID and Phone number.

Method Call

    public async Task<Result<CallerResult>> GetCaller(CallerParameters attributes)

CallerParameters

Parameter	Type	Description
LineId	long	Line ID
Phone	string	Phone number of caller

Response

Value	Description
CallerResult	caller found, conains caller information
Null	caller not found

CallerResult

Property	Type	Description
Id	Nullable<long>	Caller ID
LineId	Nullable<long>	Line ID
Phone	string	The callers phone number including country code, e.q. +40 171 1111 22 33
Channel	string	A string describing if the waiter expects a callback or will receive a text message. Values: CallBack or CallIn
Source	string	A string describing the source where the caller came from. Values: Phone, Mobile, Widget, App, Other
Ewt	Nullable<int>	Estimated wait time
ConnectedAt	Nullable<DateTime>	Connection time
CreatedAt	Nullable<DateTime>	Creation time
EstimatedUpTimeAt	Nullable<DateTime>	Estimated time when up
NotifiedAt	Nullable<DateTime>	Notification time
UpdatedAt	Nullable<DateTime>	Last updated time
Properties	ExpandoObject	Custom properties
Skills	IEnumerable<string>	Skills
VirtualQCallerState	string	State of caller in virtualQ. Values: Waiting, Notified, Connected, Finished, TimeOut
WaitTime	Nullable<int>	Elapsed time the callers has waited

API Request

https://docs.virtualq.io/#list-waiters

---

Notify that a caller has connected

After verification virtualQ should be notified that the caller has called in. This information will be displayed in interfaces to the caller (e.g. App, Web), and will be stored for reporting.

Method Call

    public async Task<Result> NotifyCallerConnected(CallerParameters attributes)

CallerParameters

Parameter	Type	Description
LineId	long	(required) Line ID
Phone	string	(required) Phone number of caller

API Request

https://docs.virtualq.io/#update-a-waiter

Response

Value	Description
CallerResult	caller found, conains caller information
Null	caller not found

CallerResult

Property	Type	Description
Id	Nullable<long>	Caller ID
LineId	Nullable<long>	Line ID
Phone	string	The callers phone number including country code, e.q. +40 171 1111 22 33
Channel	string	A string describing if the waiter expects a callback or will receive a text message. Values: CallBack or CallIn
Source	string	A string describing the source where the caller came from. Values: Phone, Mobile, Widget, App, Other
Ewt	Nullable<int>	Estimated wait time
ConnectedAt	Nullable<DateTime>	Connection time
CreatedAt	Nullable<DateTime>	Creation time
EstimatedUpTimeAt	Nullable<DateTime>	Estimated time when up
NotifiedAt	Nullable<DateTime>	Notification time
UpdatedAt	Nullable<DateTime>	Last updated time
Properties	ExpandoObject	Custom properties
Skills	IEnumerable<string>	Skills
VirtualQCallerState	string	State of caller in virtualQ. Values: Waiting, Notified, Connected, Finished, TimeOut
WaitTime	Nullable<int>	Elapsed time the callers has waited

---

Notify that a caller has been transferred

Notify virtualQ that a caller has been transferred to an agent and is now speaking. This information will be displayed in interfaces to the caller (e.g. App, Web), and will be stored for reporting.

If NotifyCallerConnected has been called previously, the property WaitTimeWhenUp will be calculated by virtualQ and does not need to be supplied.

Method Call

    public async Task<Result> NotifyCallerTransferred(NotifyCallerTransferredParameters attributes)

NotifyCallerTransferredParameters

Parameter	Type	Description
LineId	long	(required) Line ID
Phone	string	(required) Phone number of caller
WaitTimeWhenUp	Nullable<int>	Time waited before being transferred to agent
AgentId	string	Agent caller was connected with

API Request

http://docs.virtualq.io/#update-a-waiter

---

Update Caller Information

This method can be used to notify virtualQ about additional information about the caller. For example you can transmit the waiting time the caller has waited before being connected, or the agent id the callers has been transferred to.

Method Call

    public async Task<Result> UpdateCallerInformation(UpdateCallerInformationParameters attributes)

UpdateCallerInformationParameters

Parameter	Type	Description
LineId	long	(required) Line ID
Phone	string	(required) Phone number of caller
Skills	IEnumerable<string>	Array of Skills for caller
Properties	ExpandoObject	Dynamic object that can be extended with additional properties for caller
EWT	Nullable<int>	EWT as calculated by service
ServiceState	string	State of caller in service, see table below: ServiceState Values
WaitTimeWhenUp	Nullable<int>	Time waited before being transferred to agent
TalkTime	Nullable<int>	Time spent talking with agent
AgentId	string	Agent caller was connected with

ServiceState Values

Values	Description
Connected	The call has been received by the Call Center. This can be via Call-Back or Call-In
Deferred	The call has been deferred. The caller has not picked up the call back. Call Center will try again or wait for caller to call in.
Canceled	The call has been canceled for any reason. E.g. was disconnected, has not picked up, etc.
Finished	The call has been transferred to an agent. Waiting is finished.

API Request

http://docs.virtualq.io/#update-a-waiter

---

List Callers Waiting

This method can be used to query all callers currently waiting in a call center. Several parameters can be used to filter the result.

Method Call

    public async Task<Result<IEnumerable<CallerResult>>> ListCallersWaiting(ListCallersWaitingParameters attributes)

ListCallersWaitingParameters

Parameter	Type	Description
CallCenterId	long	(required) Call Center ID
LineId	long	Only list callers that are waiting in this line.

Response

Value	Description
{ ... }	Array of CallerResult objects

CallerResult

Property	Type	Description
Id	Nullable<long>	Caller ID
LineId	Nullable<long>	Line ID
Phone	string	The callers phone number including country code, e.q. +40 171 1111 22 33
Channel	string	A string describing if the waiter expects a callback or will receive a text message. Values: CallBack or CallIn
Source	string	A string describing the source where the caller came from. Values: Phone, Mobile, Widget, App, Other
Ewt	Nullable<int>	Estimated wait time
ConnectedAt	Nullable<DateTime>	Connection time
CreatedAt	Nullable<DateTime>	Creation time
EstimatedUpTimeAt	Nullable<DateTime>	Estimated time when up
NotifiedAt	Nullable<DateTime>	Notification time
UpdatedAt	Nullable<DateTime>	Last updated time
Properties	ExpandoObject	Custom properties
Skills	IEnumerable<string>	Skills
VirtualQCallerState	string	State of caller in virtualQ. Values: Waiting, Notified, Connected, Finished, TimeOut
WaitTime	Nullable<int>	Elapsed time the callers has waited

API Request

https://docs.virtualq.io/#list-waiters

---