Legacy Dev Forum Posts

Murugan_Duraisamy | 2016-09-28 15:44:16 UTC | #1

Hi Dev,

I am trying place consultant call as on HOLD using 'patchCallsCallIdParticipantsParticipantId' api. But the api gave sucess response but the caller doesn't not put on hold.

Steps I performed

Example: ConversationID: Conversation1

1. I took Inbound call - participant1(Customer)
2. Added consultant call using this api (https://api.{{environment}}/api/v2/conversations/calls/{{callId}}/participants/participant1

{{environment}}/api/v2/conversations/calls/Conversation1/participants/{participantId})

3. Consultant call placed successfully - participant2(Consultant)
4. Passed the following value to api(Conversation1, participant2, held=true)

KevinGlinski | 2016-09-28 15:39:04 UTC | #2

In a consult situation, you would want to use PATCH /api/v2/conversations/calls/{callId}/participants/{participantId}/consult to change who you are speaking to.

So

{ "speakTo": "destination" }

will have you talk to the party that is being consulted to and

{ "speakTo": "object" }

will have you talk to the customer. A little more information on consult calls can be found here: https://developer.mypurecloud.com/api/rest/v2/conversations/transfer.html

Murugan_Duraisamy | 2016-09-28 15:46:07 UTC | #3

Hi Kevin thanks for your quick response, I used below request. The call was went through successfully. Now i want to place this consultant call as oh Hold.

{ "speakTo": "DESTINATION", "destination": { "address": "615***" } }

KevinGlinski | 2016-09-28 15:47:02 UTC | #4

now do a PATCH with

"speakTo": "object"

Murugan_Duraisamy | 2016-09-28 17:35:16 UTC | #5

Thanks kevin it's working now :)

Our use case is

1. Agent can put two call as on hold(1.customer 2. consultant)
2. Agent can put one call is active one call is an hold
3. Agent can swap call two call

Below are my understanding with respect to Hold/Resume,

Both caller is active (customer and consultant ) then we need to invoke

1. 'Change who can speak' api to put customer and consultant on hold/resume

PATCH: /api/v2/calls/{conversation ID}/participants/{participant ID to replace}/consult { "speakTo": "DESTINATION" / "OBJECT" }

Only one caller is active(Customer/Consultant) then we need to invoke 'Update conversation participant' api. where participantId = agentParticipantId PATCH : https://api.{{environment}}/api/v2/conversations/calls/{{callId}}/participants/{participantId} {

"held": false }

To handle above use case do we need to invoke two api ?. If so do we have any api we can use to put call on hold/ resume based on conversations and participantId ?

KevinGlinski | 2016-09-28 18:07:28 UTC | #6

If you are talking to the customer or the consultant and want to talk to both then you just call

{ "speakTo": "BOTH" }

You shouldn't have to patch the participant to set held:false

Murugan_Duraisamy | 2016-09-28 18:55:27 UTC | #7

Got you kevin.

Only one caller is active: Scenario below,

1. Agent take Inbound call
2. Agent added consultant call
3. Now my conversation has two participant
4. Agent dropped Inbound call(i.e customer call)
5. Now my conversation has only one participant(consultant call active)

Now i want to place consultant call on hold. So I updated participant to set "speakTo:object" then the call is not put on hold.

when i patch the participant to set held:true the call is put on hold successfully.

In this case, if two call is an active then i need to set speakTo:destination/both/object if only one call is active in my conversation i need set held:true/false. based on participant list i need to set corresponding value.

To avoid this conditional statement is there any api we have to put call on hold based on conversations and participantId ?

Murugan_Duraisamy | 2016-09-29 14:59:20 UTC | #8

KevinGlinski could you please update on this

KevinGlinski | 2016-09-30 16:58:39 UTC | #9

No, there isn't an alternative to how you are doing it.

Murugan_Duraisamy | 2016-10-04 19:03:10 UTC | #10

Thanks KevinGlinski for the updates

sromocki | 2016-10-06 14:24:16 UTC | #11

Hey Kevin,

I tested the above scenarios and would like to say that I don't think the purecloud API is working as you all have intended it to and would like to put in a change request for at least the patchCallsCallIdParticipantsParticipantId API. Below is a summary of steps.

If the agent receives a call and there is now a conversation between the agent and customer, to place the call on hold, the only way I see is to use the ConversationsAPI like so:

MediaParticipantRequest request = new MediaParticipantRequest(); ConversationsApi apiInstance = new ConversationsApi(); apiInstance.setApiClient(apiClientProvider.getApiClient()); // If we pass the customer's participantId here instead of the agent's participantId we get an exception // We are forced to grab a list of participants from the conversation, loop through them, find the agent, and set the id, which we do in the getAgentParticipantId function participantId = getAgentParticipantId(callId); request.setHeld(isOnHold); apiInstance.patchCallsCallIdParticipantsParticipantId(callId, participantId, request);

The part that confuses me here is that I would expect to use the customer's participantId in order to place THAT customer on HOLD. We already have the customer's participantId from the incoming call and can just pass it along. This way if there were multiple participants on the call, we could selectively place customers on hold. Right now, you can only pass the agent id and so it's either place all customers on hold or none.

The consult API is really a different topic here. I understand we can use that only when there are 3 parties involved in a call. I believe that the consult API works as intended and is easy to swap hold/resume between the two parties and could be a more convenient way of doing a consultation call than just adding a new participant to the conversation and managing those participants via ConversationsAPI.

Does the above make sense? I just tested these scenarios this morning and that's what I see happening.

tim.smith | 2016-10-06 14:44:13 UTC | #12

It makes sense, but if you shift your perspective a little bit, I think the existing design will start to make more sense.

You appear to be looking at the API as a system-level API that grants you control over the system. However, the Platform API is explicitly in the context of a user, and all actions should be seen from the perspective of a single authenticated user; the API is taking actions on behalf of a person with limited permissions and access, not on behalf of a computer.

When you look at the hold process from the perspective of the user, they can only manipulate their own leg of the call. So they place their call on hold, which plays hold music to everyone else, just like if you press the hold button on your cellphone (probably sans hold music on your cell though). If you were to place the customer's leg of the call on hold like you're suggesting, that API action would be like going to the customer's phone and pressing hold on their device.

The options for manipulating other legs of a call will grow as more supervisory features are added (listen and coach/whisper, in particular) and you will be able to have more granular control like you are suggesting, though the context of how a hold works won't change.

Aside from the philosophical explanation of why it was created the way it is, to change the perspective of how calls are held would be an extremely significant and far reaching breaking change. Something like that would require a major API revision, which doesn't happen very often. Feel free to post this suggestion in the API Enhancement Requests category though; that's where the Product Managers collect this kind of feedback to take into consideration for future features and design changes.

sromocki | 2016-10-06 14:48:50 UTC | #13

Thanks Tim, yea my perspective was off, makes sense now.

system | 2017-08-28 19:27:36 UTC | #14

This post was migrated from the old Developer Forum.

ref: 446