Core REST Recording API

Introduction

AnywhereNow has a Representational State Transfer (REST) Recording service, which can be used by, for example, payment system to control the recording state. This feature enables you to be PCI compliant.

If AnywhereNow Authentication is enabled.

Additional steps are necessary if you are using AnywhereNow Authentication to enable Microsoft Entra Id credentials to login to your AnywhereNow applications.

Read more

Prerequisites

• Enabled AnywhereNow Authentication see: AnywhereNow Authentication Service

Instructions Core REST API use

AnywhereNow Authentication requires a bearer token authentication mechanism need to be implemented in your application.

• To get the token, a POST request needs to be sent to the following URL:
  

  Copy

  Token Request URL

  https://login.anywhere365.cloud/auth/realms/<GUID>/protocol/openid-connect/token

  Note

  Replace <GUID GUID stands for Globally Unique Identifier (format is always like 2ed153b4-f632-4766-b846-5b2a769b36d1) and is a pseudo random number used in software applications that is assumed to be unique. The total number of unique keys (2¹²⁸ of 3.4028×10³⁸) is very large and the probability of the creating the same GUID twice is very small, though not 100% guaranteed. The term GUID is generally used by developers working with Microsoft technologies, while UUID is used everywhere else.> with the "AnywhereNow Tenant ID" provided by your AnywhereNow contact (can be retrieved from Partner Portal).

• In the POST request body, include the following parameters:

• Key	Value	Description
  client_id	coreapi	The fixed client_id name of the Core API.
  username	<string>	The username of a valid user in your Microsoft Entra ID Formerly known as Azure Active Directory (or Azure AD, or AAD).
  password	<string>	The password belonging to the above username in your Microsoft Entra ID Formerly known as Azure Active Directory (or Azure AD, or AAD).
  grant_type	client_credentials	The authentication grant type for your bearer token.
  client_secret	<string>	The Client Secret value defined by Dialogue Cloud (can be retrieved from Partner Portal)

Example

See below example of a bearer token request (click to enlarge)

Get Recording state

When an audio call is in progress this command will allow for the recorder to be controlled.

Recording states are;

• Uninitialized = 0,
• Started = 1,
• Stopped = 2,
• Paused = 3

Marking states are;

• None = 0,
• Mark = 1,
• Unmark = 2

Saving states are;

• None = 0,
• Save = 1,
• Delete = 2

Request

• No Authentication
• With AnywhereNow Authentication

GET http(s)://<fqdn>/attendantservice/api/recording/<uccname>/1d6c6a58-6739-4f0c-98ff-0968292c8c30 HTTP/1.1
Accept: application/json

GET http(s)://<fqdn>/attendantservice/api/v2/recording/<uccname>/1d6c6a58-6739-4f0c-98ff-0968292c8c30 HTTP/1.1
Accept: application/json

Response (session found)

{
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "RecordingState":0,
   "MarkingState":1,
   "SavingState":1,
   "ErrorMessage":null,
   "UCCName":"ucc-demo-name"
}

Possible error messages

Configuration

Response (No recording)

Copy

JSON

{
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "RecordingState":0,
   "MarkingState":0,
   "SavingState":0,
   "ErrorMessage":{
      "ErrorType":1,
      "Message":"Recorder was not available, command could not be executed"
   },
   "UCCName":"ucc-demo-name"
}

Validation

Response (UCC not found)

Copy

JSON

{
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "RecordingState":0,
   "MarkingState":0,
   "SavingState":0,
   "ErrorMessage":{
      "ErrorType":2,
      "Message":"Ucc name ({uccName}) was not recognized"
   },
   "UCCName":"ucc-demo-name"
}

Response (session not found)

Copy

JSON

{
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "RecordingState":0,
   "MarkingState":0,
   "SavingState":0,
   "ErrorMessage":{
      "ErrorType":2,
      "Message":"No Audio session with correlation Id:'{correlationId}' was found."
   },
   "UCCName":"ucc-demo-name"
}

Response (session API not found)

Copy

JSON

{
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "RecordingState":0,
   "MarkingState":0,
   "SavingState":0,
   "ErrorMessage":{
      "ErrorType":2,
      "Message":"No Api Audio session with correlation Id:'{correlationId}' was found."
   },
   "UCCName":"ucc-demo-name"
}

Change recorder state

Actions that modify the state are;

• Start = 1,

• Stop = 2,

• Pause = 3,

• Save = 4,

• Delete = 5,

• Mark = 6,

  Note

  Marking a recording will write a RecorderSetToMarkByAgent record in the UCC A Unified Contact Center, or UCC, is a queue of interactions (voice, email, IM, etc.) that are handled by Agents. Each UCC has its own settings, IVR menus and Agents. Agents can belong to one or several UCCs and can have multiple skills (competencies). A UCC can be visualized as a contact center “micro service”. Customers can utilize one UCC (e.g. a global helpdesk), a few UCC’s (e.g. for each department or regional office) or hundreds of UCC’s (e.g. for each bed at a hospital). They are interconnected and can all be managed from one central location._CallDetail table.

• UnMark = 7

  Note

  Marking a recording will write a RecorderSetToUnMarkByAgent record in the UCC_CallDetail table.

Request with action id

• No Authentication
• With AnywhereNow Authentication

POST http(s)://<fqdn>/attendantservice/api/recording/set HTTP/1.1
Accept: application/json
Content-Type: application/json
{
   "Action":1,
   "RequesterSipUri":"sip:agent@domain.com",
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "UCCName":"ucc-demo-name"
}

POST http(s)://<fqdn>/attendantservice/api/v2/recording/set HTTP/1.1
Accept: application/json
Content-Type: application/json
{
   "Action":1,
   "RequesterSipUri":"sip:agent@domain.com",
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "UCCName":"ucc-demo-name"
}

Request with action name

• No Authentication
• With AnywhereNow Authentication

POST http(s)://<fqdn>/attendantservice/api/recording/set HTTP/1.1
Accept: application/json
Content-Type: application/json
{
   "Action":"Mark",
   "RequesterSipUri":"sip:agent@domain.com",
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "UCCName":"ucc-demo-name"
}

POST http(s)://<fqdn>/attendantservice/api/v2/recording/set HTTP/1.1
Accept: application/json
Content-Type: application/json
{
   "Action":"Mark",
   "RequesterSipUri":"sip:agent@domain.com",
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "UCCName":"ucc-demo-name"
}

Possible error messages

Configuration

Response (Agent cannot edit audio recording)

Copy

JSON

{
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "RecordingState":0,
   "MarkingState":0,
   "SavingState":0,
   "ErrorMessage":{
      "ErrorType":1,
      "Message":"Ucc with name:'{uccName}' AgentCanEditAudioRecording setting is disabled."
   },
   "UCCName":"ucc-demo-name"
}

Response (RequestUri is not an agent or Supervisor)

Copy

JSON

{
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "RecordingState":0,
   "MarkingState":0,
   "SavingState":0,
   "ErrorMessage":{
      "ErrorType":1,
      "Message":"Requester with SipUri:'{sipUri}' is not an agent or supervisor for Ucc with name: '{uccName}'."
   },
   "UCCName":"ucc-demo-name"
}

Response (No recording)

Copy

JSON

{
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "RecordingState":0,
   "MarkingState":0,
   "SavingState":0,
   "ErrorMessage":{
      "ErrorType":1,
      "Message":"Recorder was not available, command could not be executed"
   },
   "UCCName":"ucc-demo-name"
}

Validation

Response (UCC not found)

Copy

JSON

{
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "RecordingState":0,
   "MarkingState":0,
   "SavingState":0,
   "ErrorMessage":{
      "ErrorType":2,
      "Message":"Ucc name ({uccName}) was not recognized"
   },
   "UCCName":"ucc-demo-name"
}

Response (Wrong or no action found)

Copy

JSON

{
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "RecordingState":0,
   "MarkingState":0,
   "SavingState":0,
   "ErrorMessage":{
      "ErrorType":2,
      "Message":"No action was detected in command"
   },
   "UCCName":"ucc-demo-name"
}

Response (Invalid SipUri)

Copy

JSON

{
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "RecordingState":0,
   "MarkingState":0,
   "SavingState":0,
   "ErrorMessage":{
      "ErrorType":2,
      "Message":"Requester with SipUri:'{sipUri}' is invalid."
   },
   "UCCName":"ucc-demo-name"
}

Response (Conversation (correlationId) not found)

Copy

JSON

{
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "RecordingState":0,
   "MarkingState":0,
   "SavingState":0,
   "ErrorMessage":{
      "ErrorType":2,
      "Message":"No Audio session with correlation Id:'{correlationId}' was found."
   },
   "UCCName":"ucc-demo-name"
}

Response (Recording cannot be started)

Copy

JSON

{
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "RecordingState":0,
   "MarkingState":0,
   "SavingState":0,
   "ErrorMessage":{
      "ErrorType":2,
      "Message":"Recorder state is {state}, this state cannot be started"
   },
   "UCCName":"ucc-demo-name"
}

Response (Recording cannot be paused)

Copy

JSON

{
   "CorrelationId":"1d6c6a58-6739-4f0c-98ff-0968292c8c30",
   "RecordingState":0,
   "MarkingState":0,
   "SavingState":0,
   "ErrorMessage":{
      "ErrorType":2,
      "Message":"Recorder state is {state}, this state cannot be paused"
   },
   "UCCName":"ucc-demo-name"
}

Recording capabilities

In order for the change recorder state command to work the UCC must be set to allow AgentCanEditAudioRecording, with this command you can verify the setting.

Other required settings are UseAudioRecording.

Other valuable setting for Save and Delete functions may be may be SaveRecordingByDefault.

Request

• No Authentication
• With AnywhereNow Authentication

GET http(s)://<fqdn>/attendantservice/api/recording/capabilities/ucc-demo-name HTTP/1.1
Accept: application/json

GET http(s)://<fqdn>/attendantservice/api/v2/recording/capabilities/ucc-demo-name HTTP/1.1
Accept: application/json

Response

{
   "AgentCanEditRecordings":true,
   "ErrorMessage":null,
   "UCCName":"ucc_"
}

Possible error messages

Validation

Response (ucc not found)

Copy

JSON

{
   "AgentCanEditRecordings":false,
   "ErrorMessage":{
      "ErrorType":2,
      "Message":"Ucc with name:'ucc-demo-name' not found."
   },
   "UCCName":"ucc-demo-name"
}

Recording events

SignalR hub can be listened to for the RecordingStateChangedEvent which holds UccName, CorrelationId and StateAction. StateAction is the type of action that changed the state of the audiorecorder;

• Start = 1,
• Stop = 2,
• Pause = 3,
• Save = 4,
• Delete = 5,
• Mark = 6,
• UnMark = 7

Error Messages

Each recording command response can contain an ErrorMessage body.

ErrorMessage will be null when the message is successful, otherwise it will contain the following;

{
   "ErrorMessage":{
      "ErrorType":1,
      "Message":"string"
   }
}

The error types that can be returned are;

• Configuration = 1,

  • Description: Error message type 1 Configuration indicates that a superficially valid command was sent, but its content is invalid due to a mismatch with the environment, e.g. a component could not be found or licensing does not allow this command.

• Validation = 2,

  • Description: Error message type 2 Validation indicates that a command was sent that could be determined to be invalid without even attempting to perform it, e.g. a UCC was specified by name or a session by GUID, that could not be found.

• Processing = 3

  • Description: Error message type 3 Processing indicates that command execution was started but something unforeseen prevented it from finishing. It's also used for infrastructural glitches. No predictions can usefully be made for messages in this category. (A useless example would be "ValidateOrThrow must be called before HandleCommand is executed!", a message that is in the source but is not reached by any execution path in the current state of the code.) These errors may be retryable.