Skip to main content
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:
ArgumentTypeDescription
domainIdIDID 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.
opponentUserContextIdIDID 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(opponentUserContextId: 1, domainId: 2) {
    errors
    response {
      id
      attempt {
        cta {
          actionId
          title
          arguments {
            key
            value
          }
        }
      }
    }
  }
}
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
  }
}

​
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:
ArgumentTypeDescriptionDefault
afterCursorReturns results that come after the specified cursor. Should be used together with first parameter. Cannot be used if before is set.—
beforeCursorReturns results that come before the specified cursor. Should be used together with last parameter. Cannot be used if after is set.—
firstIntReturns up to the first N elements from the list. Required if after parameter is set. Cannot be used together with last.—
lastIntReturns up to the first N elements from the list. Required if before parameter is set. Cannot be used together with first.—
nameStringAllows 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.—
reverseBooleanAllows 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
  }
}

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.