Setup

My Ruby on Rails app has an initial caller who is successfully enqueued. The music plays while Rails creates an outbound call to a called party. The called party is then successfully connected to the initial caller by dialing into the queue:

response = Twilio::TwiML::VoiceResponse.new

response.dial(action: process_dial_call_status_path) do |dial|
  dial.queue()
end

render xml: response.to_s, status: :ok

The Twilio docs indicate that the action attribute will be used by Twilio make a request to my endpoint specified, but only "after the dialed call ends". I need to know the outcome of how Twilio handled my response. My fear is that the initial caller will be forever listening to queue music because the called party did not successfully Dial the Queue. The default queue music is quite nice though!

Question

How can I know if the Dial into the Queue was successful?

I know a Call can have a status of "in-progress" or "completed" (among others). Does a call-to-call queue have a similar concept in terms of statuses that the app can know about?

Addendum

When I intentionally attempt Dial to Queue by the wrong queue name, the called party line errors ("an application error has occurred") and hangs up. I receive back a parameter that is not in the documentation. The only place I can find a reference to it is https://github.com/BTBurke/twiml/blob/master/callbacks.go#L33

"DequeueResult" => "queue-not-found"

Should I expect this response to be documented?

CodePudding user response：

Twilio developer evangelist here.

This is an interesting question, not one I've come across before. Initially, I thought that the initial <Enqueue> element might be able to help out. <Enqueue> has an action attribute which is a URL that receives a webhook "when the call leaves the queue, describing the dequeue reason and details about the time spent in the queue". However, "in the case where a call is dequeued via the verb, the action URL is hit once when the bridged parties disconnect." So that doesn't tell us about the result of the dequeue until too late.

One other thing that <Enqueue> gives us is the waitUrl. While the default hold music is, ahem, great, providing your own response here can be a better idea because of the information the waitUrl receives each time Twilio comes to the end of the verbs and makes another request to the URL. The request parameters give you information like the current queue position of the call, how long the call has been in the queue, as well as the total queue size and average time calls spend in the queue. This doesn't tell you anything about the success of a <Dial><Queue> though, it's just interesting data to understand.

I think the best bet here is the url attribute on the <Queue>. This is usually used to perform a whisper to the person in the queue to let them know that they are now being moved out of the queue (a nice thing to implement anyway!). When a call is dequeued from the queue with a <Queue> that has a url the URL in the attribute will receive a request. You don't need to return TwiML to this request, an empty response will just bridge the calls, but the request will let you know that the call to the queue was successful.

It won't tell you whether the call was unsuccessful though. And that's where you can use the <Dial> element's action URL. That action URL will receive a request when the dialled call fails.

So, between the <Queue> element's url attribute and the <Dial> element's action attribute you can know whether your call to the queue was placed successfully or failed.

Regarding the "DequeueResult", that's not something I've seen before and we are looking into it internally.