Enqueue

The Enqueue command adds the current Call to a call Queue. If the specified Queue does not exist, it is created and then the Call is added to it. The default maximum length of the Queue is 100. This can be modified using the REST API.

Enqueue is a terminal command. Actions performed on the Call while waiting in the Queue are provided in a PerCL script in response to the waitUrl property. Actions performed on the Call after it has been dequeued will be provided in a PerCL script in response to the actionUrl provided.

A Call can be removed from a Queue in two ways — REST API invocation or Dequeue PerCL command.

To move a Call to a different Queue, it is necessary to first do a Dequeue operation and then a subsequent Enqueue can be done to satisfy the move.

Nesting Rules

No actions can be nested within Enqueue and Enqueue cannot be nested in any other actions.

Example

Here is a simple enqueue scenario where each incoming caller is put into a Queue.

[
   {
      "Enqueue" : {
         "queueId" : "QU724417978995574707a0774874c053e33fa1900b",
        "actionUrl" : "www.example.com/actionUrl",
        "waitUrl" : "www.example.com/waitUrl"
      }
   }
]

Command Attributes

Enqueue supports the following attributes that modify its behavior:

Attribute	Description
`queueId`	ID of the Queue to which to add the Call.
`waitUrl`	Specifies a URL pointing to a PerCL script containing actions to be executed while the caller is waiting in the Queue.
`actionUrl`	A request is made to this URL when the Call leaves the Queue.
`notificationUrl`	URL to be invoked when the Call enters the Queue.

queueId

REQUIRED

Type: string

ID of the Queue to which to add the Call. If the Queue does not exist, it will be created. The ID must start with QU followed by 40 hex characters.

waitUrl

REQUIRED

Type: absolute URL

Specifies a URL pointing to a PerCL script containing actions to be executed while the caller is waiting in the Queue. Once the script returned by the waitUrl runs out of commands to execute, FreeClimb will re-request the waitUrl and start over, essentially looping the script indefinitely.
The following are the only PerCL commands supported in the PerCL script response to a request to the waitUrl:

Play
Say
Pause
GetDigits
Dequeue
Hangup

You can use the PerCL response to the waitUrl request to do things such as report to the caller their Queue position and expected wait time.

Additional Request Parameters

Request Parameter	Description
`queuePosition`	Current Queue position for the enqueued Call.
`queueId`	ID of the Queue the caller is in.
`queueTime`	Time, in seconds, the caller has been in the Queue.
`averageQueueTime`	Average length of time the current enqueued callers have been in the Queue.
`currentQueueSize`	Current number of enqueued Calls in this Queue.

actionUrl

REQUIRED

Type: absolute URL

A request is made to this URL when the Call leaves the Queue, which can occur if enqueue of the Call fails or when the Call is dequeued via the Dequeue command, the REST API (POST to Queue Member resource), or the caller hangs up. The PerCL script returned in response to the actionUrl will be executed after the caller has been dequeued.

Additional Request Parameters

Request Parameter	Description
`queueResult`	Final result of the enqueued Call.
`queueFull`	Specified Queue was full, so the enqueue attempt was rejected.
`dequeued`	Enqueued caller exited the Queue via a `Dequeue` action (`Dequeue` command or Queue Members POST REST API).
`hangup`	Enqueued caller hung up while in the Queue.
`systemError`	FreeClimb system malfunctioned during the enqueue process.
`queueId`	ID of the Queue. This is available only if the Call was actually enqueued. Note: This is already part of the standard request parameters.
`queueTime`	Time, in seconds, the Call spent in the Queue. This is only available if the Call was actually enqueued.

notificationUrl

OPTIONAL

Type: absolute URL
Default: null

URL to be invoked when the Call enters the Queue. The request to the URL contains the standard request parameters. The queueId parameter contains the ID of the Queue to which the Call was added.

Note: This is a notification only; any PerCL returned will be ignored.