> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opigno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Take the battle

Battle taking process is quite similar to the one that is used for [Challenges](/OpignoEnterpriseAPI/Challenge/TakeChallenge).
Once the attempt is created, the user can start answering battle questions.

## Get next question

The questions appear for both battle rivals in the same order and can be retrieved one by one,
by execution of `getNextBattleQuestion` query.

<Note>
  Like in case of a challenge, battle questions will be returned not as iframe, but as a [`ChallengeQuestion`](/OpignoEnterpriseAPI/Challenge/TakeChallenge#challenge-question) object.
  The question form should and the [answer submission](#submit-the-answer) should be implemented on the frontend.
</Note>

Here is an example of the query execution:

<CodeGroup>
  ```filename Next question query theme={null}
  query getBattleNextQuestion {
    getBattleNextQuestion(battleId: 1) {
      id
      title
      question
      answerAlternatives {
        key
        value
      }
      image {
        alt
        title
        url
      }
      timeLimit
    }
  }
  ```

  ```File Next question query result [expandable] theme={null}
  {
    "data": {
      "getBattleNextQuestion": {
        "id": "4",
        "title": "Select the correct answer",
        "question": "What is the capital of Switzerland?",
        "answerAlternatives": [
          {
            "key": "ucqGu5UP",
            "value": "Geneva"
          },
          {
            "key": "q8NPVbBJ",
            "value": "Bern"
          },
          {
            "key": "u1WrLxkW",
            "value": "Zurich"
          },
          {
            "key": "tVruIvyD",
            "value": "Basel"
          },
          {
            "key": "kor2EIrI",
            "value": "Lausanne"
          }
        ],
        "image": null,
        "timeLimit": 30
      }
    }
  }
  ```
</CodeGroup>

## Submit the answer

To submit a battle answer, execute the `saveBattleQuestionAnswer` mutation.
It has one argument - `answerData`:

| Parameter    | Type  | Description                                                                                                                                                                                    |
| :----------- | :---- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `battleId`   | `ID`  | **Required**. ID of the related battle.                                                                                                                                                        |
| `questionId` | `ID`  | **Required**. ID of the question that is being answered.                                                                                                                                       |
| `answerKey`  | `ID`  | **Optional**. The key of the selected answer alternative. If empty, the question will be considered as skipped.                                                                                |
| `timeSpent`  | `Int` | **Required**. The time that was spent to provide the answer. **If the time spent is greater than the limit that is set in the question settings, the question will be considered as skipped.** |

Here is an example of the mutation execution:

<CodeGroup>
  ```filename GraphQL example theme={null}
  mutation saveBattleQuestionAnswer {
    saveBattleQuestionAnswer(answerData: {battleId: 1, questionId: 4, answerKey: 'q8NPVbBJ', timeSpent: 8}) {
      errors
      response {
        givenAnswer {
          key
          value
        }
        correctAnswer {
          key
          value
        }
        isCorrect
        score
        attempt {
          cta {
            actionId
          }
        }
      }
    }
  }
  ```

  ```File Mutation result example [expandable] theme={null}
  {
    "data": {
      "saveBattleQuestionAnswer": {
        "errors": [],
        "response": {
          "givenAnswer": {
            "key": "q8NPVbBJ",
            "value": "Bern"
          },
          "correctAnswer":  {
            "key": "q8NPVbBJ",
            "value": "Bern"
          },
          "isCorrect": true,
          "score": 10,
          "attempt": {
            "cta": [
              {
                "actionId": "NEXT_BATTLE_QUESTION"
              }
            ]
          }
        }
      }
    }
  }
  ```
</CodeGroup>

After the successful execution of the mutation, [`BattleQuestionAnswer`](#battlequestionanswer-object) object will be returned.

When the answer for the last question is submitted, a battle attempt will be automatically closed,
and the user will be able to check their [results](/OpignoEnterpriseAPI/Battle/GetBattle).

### `BattleQuestionAnswer` object

A question answer is represented in Opigno Enterprise API as a `BattleQuestionAnswer` object:

| Parameter       | Type                | Description                                                                                                                                       |
| :-------------- | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| `attempt`       | `BattleAttempt`     | **Required**. The related battle attempt.                                                                                                         |
| `correctAnswer` | `KeyValuePair`      | **Required**. The correct answer.                                                                                                                 |
| `givenAnswer`   | `KeyValuePair`      | **Optional**. The given answer.                                                                                                                   |
| `id`            | `ID`                | **Required**. The answer ID.                                                                                                                      |
| `isCorrect`     | `Boolean`           | **Required**. A marker that indicates if the provided answer is correct or not.                                                                   |
| `question`      | `ChallengeQuestion` | **Required**. The related question. The same object as for [challenges](/OpignoEnterpriseAPI/Challenge/TakeChallenge#challenge-question) is used. |
| `score`         | `Float`             | **Required**. The number of points that the user got for the answer.                                                                              |
| `timeSpent`     | `Int`               | **Required**. The time (in seconds) that is spent by the user to provide an answer for the related question.                                      |

## Terminate battle attempt

Battles designed the same way as [challenges](/OpignoEnterpriseAPI/Challenge/TerminateChallengeAttempt), and all questions must be answered in a single attempt,
without possibility to stop and resume it later. In this flow, a battle attempt should be
terminated immediately if the user leaves the question page. To do this, execute the `terminateBattleAttempt` mutation.

<Note>
  Use `extraTimeSpent` parameter to add an extra time (in seconds) to the general time that the current API user spent on the given battle.
</Note>

<CodeGroup>
  ```filename GraphQL theme={null}
  mutation terminateBattleAttempt {
    terminateBattleAttempt(battleId: 1, extraTimeSpent: 10) {
      errors
      response {
        id
        completedOn
        cta {
          actionId
          title
          arguments {
            key
            value
          }
        }
      }
    }
  }
  ```

  ```File Query result [expandable] theme={null}
  {
    "data": {
      "terminateBattleAttempt": {
        "errors": [],
        "response": {
          "id": "2",
          "completedOn": 1771193604,
          "cta": [
            {
              "actionId": "VIEW_BATTLE_RESULTS",
              "title": "View full results",
              "arguments": [
                {
                  "key": "battleId",
                  "value": "1"
                }
              ]
            }
          ]
        },
      }
    }
  }
  ```
</CodeGroup>