Re: Dialog Events - identifying actions etc

lvj00000111 · ‎04-28-2020

I've been working with the Cisco Finesse Web Services Developer Guide, and information there is quite sparse, so I have a question about receiving Dialog events.

If I make a MAKE_CALL command, I assume that I will get a dialog event. But how can I see what action was taken? Or for that matter in case someone hangs up. Which participant hung up? How does an incoming call event look, and is it different wether it came from the outside or another extension?

In the documentation, it says I will get a "full dialog object", though I have yet so see how such an object look and how all the fields are supposed to be used. Some are described in the documentation, but not everything.

I hope someone can help a confused noob :-)

Also, it seems I will need a user for every extension. I'm making a server side interface, so my server tells the phone system "this extension wants to call this number" etc. It seems I will need user/pw for each and every extension. I had hoped to have just one, if possible.

dekwan · ‎04-28-2020

Hi,

I am going to answer this out of order because it helps with understanding.

@lvj00000111 wrote:
In the documentation, it says I will get a "full dialog object", though I have yet so see how such an object look and how all the fields are supposed to be used. Some are described in the documentation, but not everything.

An example of a full dialog object can be found under "Dialog": https://developer.cisco.com/docs/finesse/#!dialog/dialog-object-for-voice-calls

Descriptions of each field can be found under "Dialog Parameters": https://developer.cisco.com/docs/finesse/#dialog-api-parameters

@lvj00000111 wrote:
If I make a MAKE_CALL command, I assume that I will get a dialog event. But how can I see what action was taken? Or for that matter in case someone hangs up. Which participant hung up?

Looking at the dialog object from the above link, you can see the action that each participant took by looking at their participant state:

    <participants>
        <Participant>
            <actions>
                <action>HOLD</action>
                <action>DROP</action>
            </actions>
            <mediaAddress>2002</mediaAddress>
            <mediaAddressType>AGENT_DEVICE</mediaAddressType>
            <startTime>2014-02-11T16:10:23.121Z</startTime>
            <state>ACTIVE</state>
            <stateCause></stateCause>
            <stateChangeTime>2014-02-11T16:10:23.121Z</stateChangeTime>
        </Participant>
        <Participant>
            <actions>
                <action>RETRIEVE</action>
                <action>DROP</action>
            </actions>
            <mediaAddress>2000</mediaAddress>
            <mediaAddressType>AGENT_DEVICE</mediaAddressType>
            <startTime>2014-02-11T16:10:23.121Z</startTime>
            <state>HELD</state>
            <stateCause></stateCause>
            <stateChangeTime>2014-02-11T16:10:36.543Z</stateChangeTime>
        </Participant>
    </participants>

In this example, the user with extension 2002's state is ACTIVE while user with extension 2000 state is in HELD. That means that 2000 pushed the HOLD button. If a participant hung up, you would see the state as DROPPED.

@lvj00000111 wrote:

How does an incoming call event look, and is it different wether it came from the outside or another extension?

All dialog events will look the same no matter it is external, internal, agent, etc. The values of the fields may change as a result of the difference.

@lvj00000111 wrote:

Also, it seems I will need a user for every extension. I'm making a server side interface, so my server tells the phone system "this extension wants to call this number" etc. It seems I will need user/pw for each and every extension. I had hoped to have just one, if possible.

Sorry, I don't understand your use case. Can you explain it with more detail?

Thanx,

Denise

lvj00000111 · ‎04-29-2020

Thank you - you're a real life saver.

Regarding the last part - I suppose I better explain our setup.

We have a bunch of clients running on the users' pcs, which connect to a server. I want to make a server to server interface, so that all commands from our clients go through our server and are sent to Finesse. In return, the server should receive all the events, interpret them and make sure status in our clients are updated accordingly. Our server will know each of the client PCs, and also which extension (and other credentials needed) are associated with that PC.

If I understand things corretly, signing a user in (username/pw) should automatically ensure, that we start seeing user- and dialog events for that user. I'm hoping that we'll get events for all the users we log in on the same machine (the server).

We would rather not make the connections from each of our client PCs, as there is often a firewall between our system and the phone server(s), and making a "hole" in the wall for each client PC will be a pain.

dekwan · ‎04-29-2020

Hi,

@lvj00000111 wrote:

If I understand things corretly, signing a user in (username/pw) should automatically ensure, that we start seeing user- and dialog events for that user. I'm hoping that we'll get events for all the users we log in on the same machine (the server).

We would rather not make the connections from each of our client PCs, as there is often a firewall between our system and the phone server(s), and making a "hole" in the wall for each client PC will be a pain.

Finesse isn't meant to be a server to server integration, so there needs to be a XMPP connection to the Finesse server per user. That being said, it isn't mandatory for the connection to be made from each of the client PC. If you choose to have a server in between the client PC and Finesse, it will be up to that server to make each user connection. Basically, there isn't a supported way to make one connection and get the user/dialog events for all users on the system.

Thanx,

Denise

lvj00000111 · ‎04-29-2020

I've seen, that I can send a message in the XMPP system, where I subscribe to events for a group (in the example being "The A Team") - could I also subscribe to events for other users? Then I would only need one connection.

Also: is there something, that I should have used instead for a server to server integration?

dekwan · ‎04-30-2020

Hi,

@lvj00000111 wrote:
I've seen, that I can send a message in the XMPP system, where I subscribe to events for a group (in the example being "The A Team") - could I also subscribe to events for other users? Then I would only need one connection.

A supervisor can subscribe to their team, but that only gives User events and not dialog events. XMPP will not stop you from subscribing to events or other users, but it is not supported. If you run into any issues and require support, you will need to undo the changes before support will be provided.

@lvj00000111 wrote:
Also: is there something, that I should have used instead for a server to server integration?

Server to server integrations should use the CTI protocol.

UCCX: https://developer.cisco.com/docs/contact-center-express/#!cti-protocol-dev-guide

UCCE: https://developer.cisco.com/site/cti-protocol/overview/

Finesse uses the CTI protocol to connect to CCE/CCX. But, I will warn you that it is not an easy implementation compared to using REST APIs and XMPP. It is pretty heavy.

Thanx,

Denise

dekwan · ‎04-29-2020

Hi,

@lvj00000111 wrote:

Another question - the "Id" on a Dialog - does that identify a given message, or the call? I assume the former, but want to make sure.

I want to make sure that I understand the difference between associatedDialogUri's id and the id tag (they were diffrent in the example).

I must be able to uniquely identify a call to track it in my system - so I want to make sure I save the right one.

The Id on the dialog is 99% the callId that is assigned by callmanager when the call is created. The Id in the associatedDialogUri is usually the same as the id of the dialog object. There are a few situations where it can be different. The id of the dialog should be the id you should be using as the unique identifier.

@lvj00000111 wrote:

I was wondering if I could provide my own id in a call variable during make call, and then get it sent back with the event I get back?

Callvariables will stick with the call unless it is changed via API or script. You could if you want, but it isn't necessary because you can just use the dialogId as the unique identifier.

@lvj00000111 wrote:
Sorry if I'm cluster bombing you with questions. At the moment I'm coding "blind" so to speak - I don't have a test system yet so I can test as I go along.

DevNet has sandboxes that you can reserve for free for up to a week to use to make API requests and see events and such. You can find the list of sandboxes here: https://developer.cisco.com/docs/finesse/#!sandbox. That is probably better than coding blind.

@lvj00000111 wrote:

Edit: mediaAddressType - as I understand it, it will either be AGENT_DEVICE or blank. Can I always assume, that blank means a participant from the outside world (so: not another extension)?

I don't know if I am interpreting "not another extension" the same way, but you the mediaAddressType can be blank if the agent uses their device to dial in without logging in as an agent. Hopefully that makes sense. Also, a participant can also be the CTI routepoint and that also has a blank mediaAddressType. The best thing for you to do is test these scenarios on the free sandbox.

@lvj00000111 wrote:

Edit2 (sorry again for the 20 Questions): If I get a call from the outside world on a main number, can I then see both the main number (there could be more than one, ex Support and Customer Service) and the number of the caller?

I would assume, that the call will be processed, maybe through a hunt group that select an extension to call, or maybe a whole group of extensions will ring (if that is possible), and the call would then go to the first one to pick up (we have both cases at different customers). How would that look? (Ex: an extra participant being a hunt group, main number extension (agent device), only one participant (the caller) etc)

Again, I suggest using the DevNet sandbox to see the dialog events for these scenarios.

Thanx,

Denise

lvj00000111 · ‎04-29-2020

Ragarding the "not another extension" part: I was wondering if calling from an in-house Cisco phone (or other device) would always give mediaAddressType=AGENT_DEVICE and calling from an outside number (either on a main number or a direct call) would always give mediaAddressType=<blank>. If so, that would be an easy way to distinguish between them and decide if I should look for a client PC/user to associate the participant with.

dekwan · ‎04-30-2020

Hi,

As I explained earlier, the mediaAddressType can be blank if the agent uses their device to dial in without logging in as an agent. Hopefully that makes sense. Also, a participant can also be the CTI routepoint and that also has a blank mediaAddressType. The best thing for you to do is test these scenarios on the free sandbox.

So, just because the call is coming from an in-house Cisco phone, it won't always be mediaAddressType=AGENT_DEVICE.

Thanx,

Denise

lvj00000111 · ‎04-29-2020

Also, while I'm at it, I'd like to emphasize my gratefulness for your patience with my million noob questions :-)

lvj00000111 · ‎04-30-2020

I'm wonding how Dialog events look for transferred calls and conferenced calls?
Will each member of a conference call for instance get a Dialog event with the call/dialog seen from their perspective? I would assume then, that if I transfer a call, I will see a DROPPED event, as I'm no longer part of the call?

When a call is "ACTIVE" for a given participant, is there a difference between "the call is now established, and no longer ALERTING" and "we are now back from being "HELD"?

Will the dialog event always use to/from address, or in some cases (like when a call is DROPPED) only TargetMediaAddress?

dekwan · ‎04-30-2020

Hi,

@lvj00000111 wrote:
I'm wonding how Dialog events look for transferred calls and conferenced calls?

As suggested yesterday, I would recommend you reserve a free DevNet sandbox (https://developer.cisco.com/docs/finesse/#!sandbox) and see for yourself.

@lvj00000111 wrote:
Will each member of a conference call for instance get a Dialog event with the call/dialog seen from their perspective? I would assume then, that if I transfer a call, I will see a DROPPED event, as I'm no longer part of the call?

All parties on the call will see the same event, whether it is a regular 2 party call, a conference call, or a transfer call.

@lvj00000111 wrote:
When a call is "ACTIVE" for a given participant, is there a difference between "the call is now established, and no longer ALERTING" and "we are now back from being "HELD"?

There is no difference. Again, please reserve a sandbox and try out all of these scenarios.

@lvj00000111 wrote:
Will the dialog event always use to/from address, or in some cases (like when a call is DROPPED) only TargetMediaAddress?

Off the top of my head, the dialog event always has the to/from address, but you need to check each scenario.

Thanx,

Denise