Skip to content

Routers API

Routers are used to assign traffic from websites to chat agents. Routers are used to define where chat agents can be online, and where they are allowed to get pending chat tasks.

For example, let's say your organization has two websites and a team of chat agent users. You would like to have the team to chat in the websites. You can define a router including this particular team, and then link the router to be used on your domain rooms.

Routers can also include simple rules that allows routing the pending chats further to additional chat agents, when given conditions match. For example, new pending chats should first be assigned to a primary chat agent team. However, if all of those chat agents are offline, then the chat should be assigned to a secondary chat agent team.

Routing system consists of the following core concepts:

  • Routers can be linked to rooms, and they consist of routing steps.
  • Routing steps define a set of users or teams.
  • Routing preconditions define situations in which the pending chat task can be incrementally assigned to users defined in the next step.

Routers

"Routers" are the core of the chat routing system. A router defines a set of users or teams. The router can then be set up to be used with any number of room(s).

In order to use a router for an organization in some specific room, you need to update the router_id attribute of the related room settings. This can be done by updating the organization's room settings resource.

A router always contains at least one "routing step" that defines a set of users and teams. The first step in the router is always required and it describes to whom new pending tasks are immediately assigned when this router is used.

Router may contain more than one router steps and steps may have "routing preconditions". These additional steps can be used to define additional users to whom a pending chat will be assigned incrementally when certain conditions match.

For example: there could be a router whose first step defines the primary chat team. The second step defines that if all of those chat agents are offline, then the pending chat will be assigned to some other, secondary chat team.

Take a look at the "Routing steps" section for more information about incremental pending chat assignments. Also, see the "Routing preconditions" for a list of all supported condition types.

A router object contains the following attributes:

Attribute Type Editable Description
id UUID read-only The unique identifier of this router.
name string required Name of the router. Must be a non-empty string.
steps array of objects required Array of routing step objects for this router.
organization_id string read-only ID of the organization that owns the router.
created_at datetime read-only When the router resource was created.
created_by_user_id UUID read-only ID of the user who created this router.
created_by_user object read-only The user resource created this router.
updated_at datetime read-only When the router resource was updated last time.
updated_by_user_id UUID read-only ID of the user who last updated this router.
updated_by_user object read-only The user resource who last updated this router.

Get a collection of organization's routers

Return a paginated collection of all the router resources of an organization (<organization_id>).

GET https://service.giosg.com/api/v5/orgs/<organization_id>/routers

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings permission

Retrieve router details

Example request and payload: Retrieve organization's router details

1
GET https://service.giosg.com/api/v5/orgs/64c8fb1c-8673-11e7-a7c7-00163e8edbc5/routers/0b77ca4a-6308-11e7-9d23-00163e07eae6
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
{
  "id": "0b77ca4a-6308-11e7-9d23-00163e07eae6",
  "name": "My Router",
  "organization_id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
  "created_at": "2017-07-07T11:33:06.137Z",
  "created_by_user": {
    "id": "97abf1ee-6308-11e7-9d09-00163ec04961",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "organization_id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
    "is_bot": false
  },
  "created_by_user_id": "97abf1ee-6308-11e7-9d09-00163ec04961",
  "updated_at": "2017-07-07T11:33:06.137Z",
  "updated_by_user": {
    "id": "97abf1ee-6308-11e7-9d09-00163ec04961",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "organization_id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
    "is_bot": false
  },
  "updated_by_user_id": "97abf1ee-6308-11e7-9d09-00163ec04961",
  "steps": [
    {
      "id": "12cbb144-6308-11e7-92a0-00163e16030c",
      "index": 0,
      "user_ids": [],
      "team_ids": [
        "153be836-630d-11e7-bef1-00163e250c85",
        "a56d5476-630d-11e7-8fa2-00163ec04961"
      ],
      "organization_ids": [],
      "preconditions": []
    },
    {
      "id": "12cbb144-6308-11e7-92a0-00163e16030c",
      "index": 1,
      "user_ids": [],
      "team_ids": [],
      "organization_ids": ["9635070c-6311-11e7-9c20-00163edd2ecc"],
      "preconditions": [
        {
          "type": "task_waited_in_previous_step",
          "value": 10
        }
      ]
    }
  ]
}

Get a single router object (<router_id>) of an organization (<organization_id>).

GET https://service.giosg.com/api/v5/orgs/<organization_id>/routers/<router_id>

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings permission
  • 404 if router was not found

Update a router

Example request and payload: Update router's steps with PATCH

1
PATCH https://service.giosg.com/api/v5/orgs/64c8fb1c-8673-11e7-a7c7-00163e8edbc5/routers/0b77ca4a-6308-11e7-9d23-00163e07eae6
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "steps": [
    {
      "user_ids": [],
      "team_ids": ["153be836-630d-11e7-bef1-00163e250c85"],
      "organization_ids": [],
      "preconditions": []
    },
    {
      "user_ids": [],
      "team_ids": ["a56d5476-630d-11e7-8fa2-00163ec04961"],
      "organization_ids": [],
      "preconditions": [
        {
          "type": "users_offline",
          "value": 100
        }
      ]
    }
  ]
}

Update a single router object (<router_id>) of an organization (<organization_id>).

Update specific fields with PATCH:

PATCH https://service.giosg.com/api/v5/orgs/<organization_id>/routers/<router_id>

Update the whole router with PUT:

PUT https://service.giosg.com/api/v5/orgs/<organization_id>/routers/<router_id>

This endpoint returns:

  • 200 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings permission
  • 404 if router was not found

Create a new router

Example request and payload: Create a new router with POST

1
POST https://service.giosg.com/api/v5/orgs/64c8fb1c-8673-11e7-a7c7-00163e8edbc5/routers
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "name": "My new router",
  "steps": [
    {
      "user_ids": [],
      "team_ids": [
        "153be836-630d-11e7-bef1-00163e250c85",
        "026e1b80-f7b1-11e4-8e23-00163e0c01f2"
      ],
      "organization_ids": [],
      "preconditions": []
    },
    {
      "user_ids": [],
      "team_ids": [],
      "organization_ids": ["a56d5476-630d-11e7-8fa2-00163ec04961"],
      "preconditions": [
        {
          "type": "users_absent",
          "value": 100
        },
        {
          "type": "task_waited",
          "value": 10
        }
      ]
    }
  ]
}

Create a new router object (<router_id>) for an organization (<organization_id>).

POST https://service.giosg.com/api/v5/orgs/<organization_id>/routers

This endpoint returns:

  • 201 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings permission

Delete a router

Example request and payload: Delete a router with DELETE

1
DELETE https://service.giosg.com/api/v5/orgs/64c8fb1c-8673-11e7-a7c7-00163e8edbc5/routers/0b77ca4a-6308-11e7-9d23-00163e07eae6

Delete a router object (<router_id>) of an organization (<organization_id>).

DELETE https://service.giosg.com/api/v5/orgs/<organization_id>/routers/<router_id>

This endpoint returns:

  • 204 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings permission
  • 404 if router was not found

List rooms where a router is in use

Example request and payload: Retrieve rooms which use current router

1
GET https://service.giosg.com/api/v5/orgs/64c8fb1c-8673-11e7-a7c7-00163e8edbc5/routers/0b77ca4a-6308-11e7-9d23-00163e07eae6/rooms
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "id": "0b77ca4a-6308-11e7-9d23-00163e07eae6",
  "organization_id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
  "organization": {
    "id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
    "name": "Giosg.com"
  },
  "domain": "giosg.com",
  "name": "My room",
  "display_name": "Customer service",
  "is_shared": false,
  "language_code": "en",
  "created_at": "2017-07-07T11:33:06.137Z",
  "updated_at": "2017-07-07T11:33:06.137Z",
  "updated_by_user_id": "97abf1ee-6308-11e7-9d09-00163ec04961",
  "updated_by_user": {
    "id": "97abf1ee-6308-11e7-9d09-00163ec04961",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "organization_id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
    "is_bot": false
  },
  "is_online": true,
  "is_deleted": false,
  "is_service_hours_enabled": true,
  "is_open": true
}

Return a paginated collection of all the room resources in which the given router is in use for the given organization.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/routers/<router_id>/rooms

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings permission
  • 404 if router was not found

Routing steps

A routing step defines a set of users and teams to whom new pending tasks will be assigned whenever the step becomes in effect.

Routing steps have a meaningful order within the router. The first step will take effect immediately for the pending tasks. Any latter steps will take effect whenever any of their routing preconditions match. In addition, the step can only become in effect if each of their preceding step have become in effect.

Note that task assignments done by routers are always incremental. This means that once a user has been assigned with a pending chat, then that pending chat is being assigned to them even if the pre-conditions are no more in effect, or if the router is modified. However, only one assigned user can actually take and join to the pending chat.

A routing step object contains the following attributes:

Attribute Type Editable Description
id UUID read-only The unique identifier of this routing step.
index integer read-only Index of the routing step relative to other routing steps in a router. Index is set automatically when router is created or updated. The first item in the router's steps array will get index of 0.
preconditions array of objects required Array of routing precondition objects for this step. This should be an empty array for the first step. Otherwise it should contain at least one routing precondition object!
organization_ids array of strings required Array of organization IDs that tasks will be routed to. Can contain only your organization and your partner organizations. Can be an empty array.
team_ids array of strings required Array of team IDs that tasks will be routed to. Can contain only your organization's teams. Can be an empty array.
user_ids array of strings required Array of user IDs that tasks will be routed to. Can contain only your organization's users. Can be an empty array.
created_at datetime read-only When the routing step resource was created.
created_by_user_id UUID read-only ID of the user who created this routing step resource.
created_by_user object read-only The user resource that created this routing step resource.
updated_at datetime read-only When the routing step resource was updated last time.
updated_by_user_id UUID read-only ID of the user who last updated this routing step resource.
updated_by_user object read-only The user resource that created this routing step resource.

Routing preconditions

A routing precondition describes a possible situation in which the related routing step may become in effect. If a step has multiple preconditions, the step becomes in effect when any of its preconditions match.

Currently, you can choose from the following 4 condition types:

"Are all (or part of) the users, defined in previous steps, offline?"

For example, if no user is logged in to the Giosg Console, or no logged user has become online by pressing the "Start" button, then this condition would match. The type of this condition is users_offline.

"Are all (or part of) the users, defined in previous steps, not present?"

For example, if no user is logged in to the Giosg Console, then this condition would match. The type of this condition is users_absent.

"Has the chat task waited too long?"

For example, when the chat is assigned to a step of users, and no one of these users take the chat in more than, let's say 10 seconds, then this condition would match. The type of this condition is task_waited_in_previous_step.

A routing precondition object contains the following attributes:

Attribute Type Editable Description
type string required Type of precondition. Can be one of the following: users_offline, users_absent, task_waited
value integer required Value of precondition. See the table below for explanation.

Routing precondition value

Routing precondition value can have a different meaning depending on the chosen type. See the table below:

Type Value
users_offline Percentage (%) of users that are offline in all previous steps. Value of 100 means that 100% of users are offline in all previous steps. Value of 0 means that all users are online in all previous steps.
users_absent Percentage (%) of users that are absent in all previous steps. Value of 100 means that 100% of users are absent in all previous steps. Value of 0 means that all users are present in all previous steps.
task_waited How many seconds the task has waited all in all. Value of 100 means that the task has waited for 100 seconds all in all.