Dialog—Create a New Dialog (Make a Call)

This API allows a user to make a call. To make a call, a new Dialog object is created that specifies the fromAddress (the caller's extension) and the toAddress (the destination target). The new Dialog object is posted to the Dialog collection for that user.

In a Unified CCE deployment, you can also use this API to pass call variables with the MAKE_CALL request. The API supports call variable 1 through call variable 10 and ECC variables. You cannot pass BA variables or wrap-up reasons with the request.

This API supports the use of any ASCII character in the toAddress. Finesse does not convert any entered letters into numbers, nor does it remove non-numeric characters (including parentheses and hyphens) from the toAddress.


Note


In a Unified CCX deployment, you cannot use this API to pass call variables. If you supply the mediaProperties parameter with a MAKE_CALL request in a Unified CCX deployment, Finesse returns a 400 Invalid Input error.


URI:

http://<FQDN>/finesse/api/User/<id>/Dialogs

Example URI:

http://finesse1.xyz.com/finesse/api/User/1234/Dialogs

Security Constraints:

All users can use this API.

Users can only create dialogs using a fromAddress to which they are currently signed in.

HTTP Method:

POST

Content Type:

Application/XML

Input/Output Format:

XML

HTTP Request:

<Dialog>
   <requestedAction>MAKE_CALL</requestedAction>
   <fromAddress>1001001</fromAddress>
   <toAddress>1002002</toAddress>
</Dialog>

HTTP Request with Call Variables (Unified CCE only):

<Dialog>
   <requestedAction>MAKE_CALL</requestedAction>
   <fromAddress>1001001</fromAddress>
   <toAddress>1002002</toAddress>
   <mediaProperties>
      <callvariables>
         <CallVariable>
            <name>callVariable1</name>
            <value>testcallvar1</value>
         </CallVariable>
         <CallVariable>
            <name>user.Finesse_ecc2</name>
            <value>A</value>
         </CallVariable>
         <CallVariable>
            <name>user.finesse_array[0]</name>
            <value>array_val_0</value>
         </CallVariable>
         <CallVariable>
            <name>user.finesse_array[1]</name>
            <value>array_val_1</value>
         </CallVariable>
         <CallVariable>
            <name>user.finesse_array[2]</name>
            <value>array_val_2</value>
         </CallVariable>
         <CallVariable> 
            <name>user.finesse_array[3]</name>
            <value>array_val_3</value>
         </CallVariable>
         <CallVariable>
            <name>user.finesse_array[4]</name>
            <value>array_val_4</value>
         </CallVariable>
      </callvariables>
   </mediaProperties>
</Dialog>

Request Parameters:

id (required): The ID of the user

requested Action (required): The way in which the dialog is created (MAKE_CALL)

fromAddress (required): The extension with which the user is currently signed in

toAddress (required): The destination for the call

mediaProperties (optional): Collection of media-specific properties related to the dialog

callvariables (optional): Collection of call variables to include as part of the initial call

CallVariable (optional): Name and value pair for a call variable

HTTP Response:

202: Successfully Accepted

Note   

This response only indicates successful completion of the request. The request is processed and the actual response is sent as part of a dialog notification.

400: Bad Request (the request body is invalid)

400: Parameter Missing

400: Invalid Input (a request in a Unified CCX deployment includes mediaProperties)

400: Invalid Destination (the toAddress and fromAddress are the same)

401: Authorization Failure

401: Invalid Authorization

500: Internal Server Error

Example Failure Response:

<ApiErrors>
     <ApiError>
          <ErrorType>Authorization Failure</ErrorType>
          <ErrorMessage>Unauthorized</ErrorMessage>
          <ErrorData>jsmith</ErrorData>
   </ApiError>
</ApiErrors>

Notifications Triggered:

Dialog notification

Asynchronous Errors


Note


When accessing the Finesse REST API through the Finesse JavaScript library, asynchronous errors have a status code of 400. When receiving the asynchronous error directly through XMPP, the error message has the format described in "Dialog CTI Error Notification."


ErrorType Reason Deployment Type

Invalid State

Attempt to POST a Dialog when the agent is in an invalid state to make a call. For example, trying to POST a Dialog when the agent is in Ready state.

All

Invalid State

Supervisor attempts to POST a Dialog when that supervisor is silently monitoring another agent.

All

Generic Error

Attempt to POST a Dialog to a route point when there are no agents in Ready state in the queue corresponding to that route point.

All

Generic Error

Attempt to POST a Dialog in which the toAddress is an E164 extension.

Unified CCE

Related References
Dialog CTI Error Notification