SmartRouting WebHooks

This document describes Enreach SmartRouting webhook implementation, providing possibility to implement advanced callcontrol based on external logic.

Simply put, SmartRouting webhooks send a HTTPS POST request to predefined URL for each incoming call. The request contains JSON data providing information about the call. Receiving party is expected to respond with JSON data containing routing instructions for the call.

Some possible use scenarios include:

IVR menu by-pass. Route incoming service calls to different queues based on caller number, if caller is recognized. If caller is not recognized prompt for menu selection.
Modify service queue allocation parameters for incoming service calls based on caller number
- Set required agent to handle the call. Call will wait or overflow if the agent is not available.
- Set preferred agents to handle the call. Call will be allocated to the preferred agents if they are available, if not the call will be allocated to other agents.
- Set extra priority for the call
Play dynamic text-to-speech messages to the caller

Example use case

Business need:

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.

Solution:

Implement SmartRouting endpoint to CRM system, which does lookup based on caller number and responds with routing instructions for the call
Service queue is configured to make SmartRouting request to the endpoint in the CRM system

Smartrouting

Configuration

Smartrouting can be configured to any EnreachVoice service queue or IVR queue.

Smartrouting configuration is done by Enreach support.

Endpoint implementation

Endpoint requirements

Endpoint must work over HTTPS in port 443
Endpoint must respond to requests as soon as possible, default timeout is 5 seconds
Network traffic must be allowed from EnreachVoice networks:
- 80.88.186.0/24
- 80.88.187.0/24

SmartRouting Request

Example SmartRouting request

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

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

SmartRouting makes an HTTP POST request to your endpoint

Authentication

Smartrouting webhook request can use either API Key or HTTP Basic Authentication for authentication.

API Key

If using API key method, additiona header X-Benemen-APIKey is included in the request, containing the API key value.

HTTP Basic Authentication

If using HTTP Basic Authentication, the request contains Authorization header with value Basic <base64(username:password)>

Request body

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 SmartRouting.
  - It is possible to share the same targetid between, e.g., similar kinds of queues.
  - Naturally, the customer's REST API implementation and the configuration in Enreach Core must match and have a contract about the purpose of targetid.

SmartRouting Response

Status code

Endpoint should respond with 200 OK status code only, if enfpoint can provide routing instructions for the call, which differs from default routing.

For example in Example use case, if the caller is recognized as a VIP customer like in , the endpoint should respond with 200 OK and routing instructions for the call. If the caller is not recognized, the endpoint should respond with 204 No Content, which means that the call will be handled normally.

Error codes should be reserved for proper error situations.

StatusCode	Description	Call Contorl
200 OK	Caller recognized, special routing instructions included	Call is routed according to the routing instructions
204 No Content	Caller not recognized	Call is routed according default configuration
4xx,5xx Errors	Error	Call is routed according default configuration

Response content

Response content must be JSON formatted.

Response header must have Content-Type: application/json

Only set the properties you want to touch, do not set your own defaults

See Example responses for some example scenarios.

Response body properties

Key	Type	Values	Description
InitialTarget	string	`<any-target>/DISCONNECT:`	Forward the call to another location (queue, user) for handling or disconnect 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 the initial target is a 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. Only applies if InitialTarget is a queue.
AllocationTargets	List	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 brackets.
CustomMSI	string	MSI (dynamic billing) configuration	Advanced: This value must be orchestrated with other MSI configuration. See separate documentation. `<MSI tag>,<validFor>[,<action>,<re-entrant>]`

Legend

<any-target>
- Any number, queue GUID, user number etc.
<queue-target>
- Queue number
- Queue GUID (Enreach internal identifier)
- NOTE: When forwarding with Queue GUID the call will always pass the Service Queue schedules if any.
<user-target> can be one of the following
- Agent username (email)
- Agent number
- Agent GUID (Enrech internal identifier)
DISCONNECT:
- The call will be disconnected, possibly stating the CustomTTS if one is provided.

Example responses

Below are some common scenarios and example responses for them.

Example response: Route to a specific target number

{
  "InitialTarget": "+358123456789"
}

Route call to the target number

Example response: Text-to-speech message and route call

{
  "InitialTarget": "cd1258fb-0aae-4159-ba9e-41c57c69c398",
  "CustomTTS": "[en-GB] Greetings caller. [fi-FI] Tervehdys soittaja"
}

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

Example response: Text-to-speech and disconnect

{
  "InitialTarget": "DISCONNECT:",
  "CustomTTS": "This call will be disconnected, sorry about that"
}

Play text-to-speech message to the caller, then disconnect the call

Example response: Required agent

{
  "InitialTarget":"+358123456789",
  "RequiredTarget":"agent1@customer.com"
}

Route to a specific queue and require a specific agent to handle the call.

If teh agent is currently on a call or i a wrap up state, the call will wait for a configured timeout period (default 10s) until the agent becomes available or the timeout expires.

If the agent is not available, the call will overflow based on queue configuration.

Example response: Preferred agents

{
  "InitialTarget": "+358123456789",
  "AllocationTargets": [
    "agent1@customer.com", 
    "agent2@customer.com"
  ]
}

Route call to a specific queue, have one of the preferred agents handle the call.

If the preferred agents are not available for immediate allocation, the call will be allocated to other agents.

Example response: Override priority

{
  "Priority": 10000
}

Make the call high priority overriding the QueuePriority configured for the service queue

Example response: Add extra priority

{
  "ExtraPriority": 100
}

Make the call high priority by setting call-specific ExtraPriority.

Total priority of the call will be QueuePriority + ExtraPriority