Start a new battle

In scope of gamification features, Opigno Enterprise API provides endpoints to implement Battles. A battle consists of a predefined sequence of random questions related to the selected domain, presented in the same order to both participants. Each question must be answered within a specified time limit. Participants earn points based on the correctness of their answers, and (if such option is enabled in the backoffice) on the time spent. The winner is a participant with the higher number of correct answers. In case when the number of earned points is the same for both users, the rival who spent less time wins the battle.

Create a battle

To start a new battle, the createBattle mutation should be executed. It accepts two required arguments:

Argument	Type	Description
`domainId`	`ID`	ID of a domain term associated with the battle. The list of the questions will be randomly generated based on the selected domain. To get the list of available options, call the `getPossibleBattleOpponents` query.
`opponentUserContextUuid`	`ID`	UUID of a user context associated with an opponent. To get the list of available options, call the `getBattleDomains` query.

Here is an example of the mutation execution:

mutation createBattle {
  createBattle(opponentUserContextUuid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", domainId: 2) {
    errors
    response {
      id
      attempt {
        cta {
          actionId
          title
          arguments {
            key
            value
          }
        }
      }
    }
  }
}

{
  "data": {
    "createBattle": {
      "errors": [],
      "response": {
        "id": "1",
        "attempt": {
          "cta": [
            {
              "actionId": "NEXT_BATTLE_QUESTION",
              "title": "Next question",
              "arguments": [
                {
                  "key": "battleId",
                  "value": "1"
                }
              ]
            }
          ]
        }
      }
    }
  }
}

After the mutation is successfully executed, a Battle object will be returned.

The initiator’s attempt will be created automatically when a new battle is created. This means that the user can immediately proceed with the take battle flow.

Get available domains

To get the list of allowed domains that contain an appropriate number of questions, the getBattleDomains query should be executed. The query returns the list of TaxonomyTerm objects, sorted according to their weight configured in the backoffice:

query getBattleDomains {
  getBattleDomains {
    id
    name
  }
}

{
  "data": {
    "getBattleDomains": {
      [
        "id": "1",
        "name": "History"
      ],
      [
        "id": "2",
        "name": "Geography"
      ],
      [
        "id": "3",
        "name": "Math"
      ]
    }
  }
}

Get possible opponents

A battle can be initiated only between two user contexts assigned to the same hierarchy level. The list of possible opponents can be retrieved by calling the getPossibleBattleOpponents query. Results will be returned with the pagination, sorted by the user context label, and possibility to change the order (default sort order is ascending). The following arguments can be used:

Argument	Type	Description	Default
`after`	`Cursor`	Returns results that come after the specified cursor. Should be used together with `first` parameter. Cannot be used if `before` is set.	—
`before`	`Cursor`	Returns results that come before the specified cursor. Should be used together with `last` parameter. Cannot be used if `after` is set.	—
`first`	`Int`	Returns up to the first N elements from the list. Required if `after` parameter is set. Cannot be used together with `last`.	—
`last`	`Int`	Returns up to the first N elements from the list. Required if `before` parameter is set. Cannot be used together with `first`.	—
`name`	`String`	Allows to search by the user context label. It makes sense to use it only if the real names are sent to the API during the user context data synchronization.	—
`reverse`	`Boolean`	Allows to reverse the order of the underlying list (default order is ascending).	`false`

The query returns a paginated list of BattleRival objects:

query getPossibleBattleOpponents {
  getPossibleBattleOpponents(first: 10, name: "John") {
    edges {
      node {
        id
        uuid
        displayName
      }
    }
    totalItems
  }
}

{
  "data": {
    "getPossibleBattleOpponents": {
      "edges": [
        "node": {
          "id": "1",
          "uuid": "1234abcd-5e67-8900-123b-92f88908df44",
          "displayName": "John Doe"
        },
        "node": {
          "id": "14",
          "uuid": "0abc1de2-3f35-6789-012b-01a23456bc67",
          "displayName": "John Raynolds"
        }
      ],
      "totalItems": 2
    }
  }
}

Pagination

Learn how to efficiently navigate through large sets of items using cursor-based pagination.

Take a battle

Now, when the initiator’s attempt is created, the user can take the battle.

Getting started

Integration & Concepts

Use cases

Hierarchy Management

Zapier Integration

Mobile application

Start a new battle

Create a battle

Get available domains

Get possible opponents

Pagination

Take a battle

​Create a battle

​Get available domains

​Get possible opponents

​Related Features

Pagination

Take a battle

Create a battle

Get available domains

Get possible opponents

Related Features