Avaya Experience Platform™
Developer Guides

Match

Suggest Edits

This page talks about Match Admin in Avaya Experience Platform™.

Overview

Match Admin in Avaya Experience Platform™ defines Queues and Categories of Attributes to partition incoming chat, email, and messaging engagements. These Queues and Categories of Attributes are associated with Agents which allows Avaya Experience Platform™ Matching Service to match an engagement to the best Agent and match a just-available Agent to a waiting engagement.

Routing is implemented by matching the queue specified on an engagement against the available agents associated with the queue. Routing may be refined by matching the attributes specified on an engagement against the attributes associated with the members of the pool of available agents in the specified queue.

A queue often represents a business domain or department (sales, billing, etc). Depending on reporting and other requirements a customer may decide to specify subdivisions like region, product, or language at the queue level.

Alternatively, a customer may choose to keep queues at a high-level and rely on attributes to partition engagements among available agents. Besides the above examples of region, product or language, an attribute could be one of the following.

  • A predicted value like priority of an engagement based on login-id or handle.
  • A gathered value like reason for engagement, conversation context or mood.

Attributes that are similar in nature are grouped together into a Category. In the examples above, Language, Mood and Priority are categories.

Queues

Avaya Experience Platform™ Match Admin APIs and User APIs can be used to integrate with existing enterprise directory / HR and CRM systems to automatically configure the contact center with expected business needs (queues, attributes) and resources (agents, supervisors) that fulfil them.

Queues often align with existing business concepts such as Department, Sales Region or Product Class that are documented or stored in your own systems already.

It may be useful to create scripts or programs to define queues through the API rather than rely on manual input.

A Queue is composed of:

  • queueId
    • A unique resource ID generated by the API to be used when referring to the queue.
  • name
    • The name of the queue which must be unique per account. For example, 'EU Sales'.
  • description
    • A brief description of the intent of the queue.
  • timetableId
    • Optionally associated with a queue to determine the queue's availability.
  • defaultAccountQueue
    • This indicates whether a queue is the default queue for an account. It cannot be modified through the API.
  • afterContactWork
    • True indicates that an agent will undertake additional work after a contact (Engagement) on this queue ends.

Default Queue

When your account is created it will be given a default queue. This queue can be renamed and assigned business hours, but it can never be deleted.

It will be the only queue to ever have a true value for the defaultAccountQueue property.

{
  "queueId": "f5c6ec92-8c67-437d-9aaf-35d4b81acdec",
  "name": "Default",
  "description": "Default queue",
  "defaultAccountQueue": true,
  "afterContactWork": false
}

Creating a Queue

To create a queue, you must provide a name. Optionally, a description can be provided to describe the purpose of a queue. Optionally, a timetableId can be used to assign business hours. Queues with no assigned timetable will be considered always open.
If a value for afterContactWork is not provided, the setting defaults to false.

If you are creating multiple queues at once, use bulkCreate instead.

POST /queues

{
  "name": "EMEA Sales",
  "description": "Route engagements to sales agents in the EMEA Region",
  "timetableId": "28002f8e-c952-428c-b67f-5a6a4dc96260",
  "afterContactWork": true
}

After creation you will receive a queueId, which you should then use to refer to the queue from that point on.

HTTP 201 Created

{
  "queueId": "689e0f6b-1d27-42a9-af19-9d0b244af0b3",
  "name": "EMEA Sales",
  "description": "Route engagements to sales agents in the EMEA Region",
  "timetableId": "28002f8e-c952-428c-b67f-5a6a4dc96260",
  "defaultAccountQueue": false,
  "afterContactWork": true
}

Retrieving a Queue

To retrieve a queue, you simply need to provide the queueId.

GET /queues/{queueId}

/queues/689e0f6b-1d27-42a9-af19-9d0b244af0b3

HTTP 200 OK

{
  "queueId": "689e0f6b-1d27-42a9-af19-9d0b244af0b3",
  "name": "EMEA Sales",
  "description": "Route engagements to sales agents in the EMEA Region",
  "timetableId": "28002f8e-c952-428c-b67f-5a6a4dc96260",
  "defaultAccountQueue": false,
  "afterContactWork": true
}

Listing Queues

Multiple queues for an account can be retrieved using the list API which is paginated. There are several optional filters that can be applied, refer to the API reference for more details.

GET /queues

/queues?name=EMEA%20Sales&defaultAccountQueue=false&pageNumber=1&pageSize=10

HTTP 200 OK

{
  "pagination": {
    "pageNumber": 1,
    "pageSize": 3,
    "total": 5
  },
  "queues": [
    {
      "queueId": "f5c6ec92-8c67-437d-9aaf-35d4b81acdec",
      "name": "Default",
      "description": "Default queue",
      "defaultAccountQueue": true,
      "afterContactWork": false
    },
    {
      "queueId": "689e0f6b-1d27-42a9-af19-9d0b244af0b3",
      "name": "EMEA Sales",
      "description": "Route engagements to sales agents in the EMEA Region",
      "timetableId": "28002f8e-c952-428c-b67f-5a6a4dc96260",
      "defaultAccountQueue": false,
      "afterContactWork": true
    },
    {
      "queueId": "d62d5178-9920-415a-a5d9-066716384750",
      "name": "NA Support",
      "description": "Route engagements to support agents in the NA Region",
      "timetableId": "7893b4a3-c952-43f5-87c7-8cefa1f49685",
      "defaultAccountQueue": false,
      "afterContactWork": false
    }
  ],
  "links": {
    "next": "/api/admin/match/v1/accounts/ABCDEF/queues?pageNumber=2&pageSize=3",
    "previous": ""
  }
}

Bulk Creation of Queues

Multiple queues can be created in bulk with a maximum of 10 queues being allowed per request. Simply provide the queues within an array.

POST /queues:bulkCreate

[
  {
    "name": "EMEA Sales",
    "description": "Route engagements to sales agents in the EMEA Region",
    "timetableId": "28002f8e-c952-428c-b67f-5a6a4dc96260",
    "afterContactWork": true
  },
  {
    "name": "NA Support",
    "description": "Route engagements to support agents in the NA Region",
    "timetableId": "7893b4a3-c952-43f5-87c7-8cefa1f49685",
    "afterContactWork": false
  }
]

After creation you will receive each queue that was created with its queueId, which you should then use to refer to the queue from that point on.

HTTP 201 Created

[
  {
    "queueId": "689e0f6b-1d27-42a9-af19-9d0b244af0b3",
    "name": "EMEA Sales",
    "description": "Route engagements to sales agents in the EMEA Region",
    "timetableId": "28002f8e-c952-428c-b67f-5a6a4dc96260",
    "defaultAccountQueue": false,
    "afterContactWork": true
  },
  {
    "queueId": "d62d5178-9920-415a-a5d9-066716384750",
    "name": "NA Support",
    "description": "Route engagements to support agents in the NA Region",
    "timetableId": "7893b4a3-c952-43f5-87c7-8cefa1f49685",
    "defaultAccountQueue": false,
    "afterContactWork": false
  }
]

Bulk Deletion of Queues

Multiple queues can be deleted in bulk with a maximum of 10 queues being allowed per request. Simply provide the queueIds within an array.

POST /queues:bulkDelete

[
  "689e0f6b-1d27-42a9-af19-9d0b244af0b3",
  "d62d5178-9920-415a-a5d9-066716384750"
]

No response body is returned from this request.

HTTP 204 No Content

Categories and Attributes

In the same way as Queues, Categories and Attributes often align with existing business concepts.

A Category is composed of:

  • name
    • A unique name assigned to the category that will be used to refer to it. For example, 'Language'.
  • attributes
    • The list of values contained within the category. The name field of an attribute is generated based on the name of the category and the attribute value. For example, 'Language.French'.

Creating a Category

To create a category, you must provide a name and a list of attributes.

If you are creating multiple categories at once, use bulkCreate instead.

POST /categories

{
  "name": "Language",
  "attributes": [
    {
      "value": "French"
    },
    {
      "value": "German"
    }
  ]
}

The category, including its categoryId, are returned in the response.

HTTP 201 Created

{
  "categoryId": "4331fa35-9671-4ea0-94e0-517097a5a13a",
  "name": "Language",
  "attributes": [
    {
      "value": "French",
      "name": "Language.French"
    },
    {
      "value": "German",
      "name": "Language.German"
    }
  ]
}

Retrieving a Category

To retrieve a category you simply need to provide the categoryId.

GET /categorys/{categoryId}

/categorys/4331fa35-9671-4ea0-94e0-517097a5a13a

HTTP 200 OK

{
  "categoryId": "4331fa35-9671-4ea0-94e0-517097a5a13a",
  "name": "Language",
  "attributes": [
    {
      "value": "French",
      "name": "Language.French"
    },
    {
      "value": "German",
      "name": "Language.German"
    }
  ]
}

Listing Categories

Multiple categories for an account can be retrieved using the list API which is paginated.

GET /categories

/categories?pageNumber=1&pageSize=10

HTTP 200 OK

{
  "pagination": {
    "pageNumber": 2,
    "pageSize": 10,
    "total": 3
  },
  "categories": [
    {
      "categoryId": "4331fa35-9671-4ea0-94e0-517097a5a13a",
      "name": "Language",
      "attributes": [
        {
          "value": "French",
          "name": "Language.French"
        },
        {
          "value": "German",
          "name": "Language.German"
        }
      ]
    },
    {
      "categoryId": "a730d229-c386-43df-9241-b5191af2725c",
      "name": "Product",
      "attributes": [
        {
          "value": "Landline",
          "name": "Product.Landline"
        },
        {
          "value": "Mobile",
          "name": "Product.Mobile"
        }
      ]
    }
  ],
  "links": {
    "next": "/api/admin/match/v1/accounts/ABCDEF/categories?pageNumber=3&pageSize=10",
    "previous": "/api/admin/match/v1/accounts/ABCDEF/categories?pageNumber=1&pageSize=10"
  }
}

Bulk Creation of Categories

Multiple categories can be created in bulk with a maximum of 10 categories being allowed per request. Simply provide the categories within an array.

POST /categories:bulkCreate

[
  {
    "name": "Language",
    "attributes": [
      {
        "value": "French"
      },
      {
        "value": "German"
      }
    ]
  },
  {
    "name": "Product",
    "attributes": [
      {
        "value": "Mobile"
      },
      {
        "value": "Landline"
      }
    ]
  }
]

After creation you will receive each category that was created with its categoryId, which you should then use to refer to the category from that point on.

HTTP 201 Created

[
  {
    "categoryId": "4331fa35-9671-4ea0-94e0-517097a5a13a",
    "name": "Language",
    "attributes": [
      {
        "value": "English",
        "name": "Language.English"
      },
      {
        "value": "French",
        "name": "Language.French"
      }
    ]
  },
  {
    "categoryId": "a730d229-c386-43df-9241-b5191af2725c",
    "name": "Product",
    "attributes": [
      {
        "value": "Landline",
        "name": "Product.Landline"
      }
    ]
  }
]

Bulk Deletion of Categories

Multiple categories can be deleted in bulk with a maximum of 10 categories being allowed per request. Simply provide the categoryIds within an array.

POST /categories:bulkDelete

[
  "4331fa35-9671-4ea0-94e0-517097a5a13a",
  "a730d229-c386-43df-9241-b5191af2725c"
]

No response body is returned from this request.

HTTP 204 No Content

Updated about 2 months ago