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

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

{
  "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

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

{
  "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

POST https://service.giosg.com/api/v5/orgs/64c8fb1c-8673-11e7-a7c7-00163e8edbc5/routers

{
  "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

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

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

{
  "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.