Media—Change Agent State with Reason Code

This API allows a user to change the agent state in an individual non-voice Media Routing Domain, and pass along the code value of a corresponding reason code. Users can use this API only when changing state to NOT_READY or LOGOUT.

URI:

https://<FQDN>/finesse/api/User/<id>/Media/<mrdId>

Example URI:

https://finesse1.xyz.com/finesse/api/User/1234/Media/5001

Security Constraints:

Agents and supervisors can use this API.

Users can only act on their own Media objects.

HTTP Method:

PUT

Content Type:

Application/XML

Input/Output Format:

XML

HTTP Request: 

<Media>
   <state>NOT_READY</state>
   <reasonCodeId>1001</reaasonCodeId>
</Media>

Request Parameters:

id (required): The ID of the user

mrdId (required): The ID of the Media Routing Domain

reasonCodeId (required if reason codes are configured for the given state): The database ID for the reason code

state (required): The new state that the user wants to be in (NOT_READY or LOGOUT)

Header Parameters:

requestId: A user provided unique string used to correlate originating request with the resulting HTTP response or asynchronous error. This parameter is not part of the resulting event/events.

HTTP Response:

202: Successfully Accepted

Note

The requestId is included in the response header if provided.

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

400: Bad Request (for example, malformed or incomplete request)

400: Parameter Missing

401: Unauthorized (for example, the user is not authenticated in the Web Session)

404: Not Found (for example, the user ID or mrdId is not known)

503: Service Unavailable (for example, the Notification Service is not running)

Example Failure Response: 

<ApiErrors>
    <ApiError>
        <ErrorData>1</ErrorData>
        <ErrorMedia>5001</ErrorMedia>
        <ErrorMessage>E_ARM_STAT_AGENT_ALREADY_LOGGED_IN</ErrorMessage>
        <ErrorType>Agent already logged into MRD</ErrorType>
    </ApiError>
</ApiErrors>

Notifications Triggered:

Media notification

Asynchronous Errors

If an error occurs after the initial validation is complete, an error notification is sent over XMPP to the Media notification. The requestId is included in the response XML. The ErrorMedia parameter in the ApiError information indicates the Media Routing Domain to which the error applies.