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

• <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

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

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

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

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

{
  "InitialTarget":"+3581012345",
  "RequiredTarget":"john.smith@customer.com"
}

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

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

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

{
  "Priority": 10000
}

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

Priority of the call is QueuePrioirty + ExtraPrioirty

{
  "ExtraPriority": 100
}