SmartRouting HTTP Integrator Guide

- 1.1 Example Smartrouting scenario
2 Endpoint requirements
3 SmartRouting Request
4 SmartRouting Request Extra Data
5 SmartRouting Response
- 5.1 Response body properties
6 Example responses

This document is intended for developers implementing an HTTP endpoint responding to SmartRouting requests, providing routing instructions for Enreach Core.

Example Smartrouting scenario

External CRM system holds information of VIP customers. When VIP customer calls to service, calls should be routed to a separate ‘VIP service queue’, which has higher priority than the normal service queue. If the caller is not recognized as a VIP, the call will be handled in a normal service queue.

Endpoint requirements

Endpoint must work over HTTPS in port 443
Endpoint must respond to requests as soon as possible
Network traffic must be allowed from BeneCloud networks:
- 80.88.186.0/24
- 80.88.187.0/24

SmartRouting Request

SmartRouting makes an HTTP POST request to your endpoint
Request can be authenticated using the following methods
- API Key
  - X-Benemen-APIKey: 1234
- Basic credentials
  - Authorization: Basic b64(username:password)
The request body contains a JSON object with the following properties
- anum - string, E.164-formatted caller phone number
  - “Who’s calling”
- bnum - string, E.164-formatted target phone number
  - “What number did they call”
- targetid - OPTIONAL string. It is possible to configure an additional “symbolic” name (or “tag”) when initiating the SmartRouting.
  - It is possible to share the same targetid between e.g. similar kind of queues.
  - Naturally, the customer’s REST API implementation and the configuration in Enreach Core must match and have a contract about the purpose or targeted.

POST /your-path
X-Benemen-APIKey: 1234
Content-Type: application/json

{ "anum": "+358501231234", "bnum": "+4612312345", "targetid": "SALES_QUEUE" }

SmartRouting Request Extra Data

It is possible to configure the core to send various extra data. The extra data will be sent in sub key “extradata” as JSON dictionary.

This example shows the default values (there is also an extended set for special cases) as well as two dynamically configured parameters (the key name starts with “DYN_”).

{
    "anum": "+358501231234", 
    "bnum": "+4612312345", 
    "targetid: "SALES_QUEUE"
    "extradata": {
        "CallId": "d59d7a2f-318a-469e-bdc0-b092a8fedbc1",
        "LegId": "66299cde606b3db6d413cd208f7e5cab@45.66.192.196_br1",
        "CurrQueueId": "1a89fc22-517a-e611-80c9-00505689257e",
        "CurrUserId": "",
        "IsInternalCaller": false,
        "DYN_PAR_Culture": "en-GB",
        "DYN_PAR_Something": "SOMETHING"
    }
}

SmartRouting Response

Status code
- If you generate a result that should be used, respond with 200 OK
  - “Caller matched, here’s what to do”
- If you successfully process the result but do not have anything to return, return 204 No Content
  - “Don’t know who this is, proceed normally”
Response headers
- Return header Content-Type: application/json
Response body
- Only set the properties you want to touch, do not set your own defaults
  - E.g do not set "Priority" to some "default value" 100. If you do not want to set it to 100, leave it null.

Response body properties

Key	Type	Values	Description

Key	Type	Values	Description
InitialTarget	string	<any-target>/DISCONNECT:	Forward the call to another location (queue, user) for handling or disconnet the call To disconnect call, return “DISCONNECT:” If empty, no direct forwarding is performed
FailTarget	string	<any-target>	If the call would overflow from the initial target, override the default target with this For example, if initial target is user and they do not answer, redirect to some specific queue
RequiredTarget	string	<user-target>	Primary agent who is required to be present in the targeted queue to handle the call If the agent is currently unavailable, but potentially becomes available within the timeout period (10 seconds default), the caller waits until the timeout expires E.g. if the agent is currently in a call, they might just be able to take the next call Only applies if InitialTarget is a queue
AllocationTargets	List<string>	List of <user-target>	Agents that should be preferred in allocation Non-blocking - if the agents are not available, other agents are chosen instead Only applies if InitialTarget is a queue
Priority	int	Integer from 0 to 10000	Priority for the call (e.g for VIP customers). Bigger value is better: makes the call that many seconds "older" in allocation processing. Setting this value overrides the default priority configured for the queues. Only set this if you really want to override and do have the values coordinated with queue configurations.
ExtraPriority	int	Integer from -10000 to 10000	Extra priority for the call (e.g for VIP customers). Bigger value is better: makes the call that many seconds "older" in allocation processing. This is the new preferred way of boosting (or reducing) call priority without overriding the priority set by the routing core, typically with service queue configuration. Both priorities are added for the composite priority value.
CustomTTS	string	TTS prompt definition.	Advanced. When this value is provided the TTS prompt is played forcibly as the next transfer or mandatory prompt. Must be orchestrated with the other configuration! Language can be specified by .NET Culture code in bracets
CustomMSI	string	MSI (dynamic billing) configuration. `<MSI tag>,<validFor>[,<action>,<re-entrant>]`	Advanced: This value must orchestraded with other MSI configuration. See separate documentation.

<any-target>
<queue-target>
- Queue number
- Queue GUID (Benemen internal identifier)
<user-target> can be one of the following
- Agent username (email)
- Agent number
- Agent GUID (Benemen internal identifier)
DISCONNECT:
- The call will be disconnected, possibly stating the CustomTTS if one is provided.

Example responses

Example response: Route to a specific queue

{
  "InitialTarget": "+3581012345"
}

Example response: Play text-to-speech message to caller in English and in Finnish, then route to specific queue by QueueId

Example response: Play Text-to-speech message to the caller, then disconnect the call

Example response: Route to a specific queue and require a specific agent to handle the call

Example response: Route to a specific queue, have one of the preferred agents handle the call

Example response: Make the call high priority overriding priority set in Queue

Example response: Make the call high priority by setting call-specific ExtraPriority

Priority of the call is QueuePrioirty + ExtraPrioirty