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

# Approvals

> Approve or decline Ravenna ticket approval rounds directly from a Microsoft Teams DM with an interactive Adaptive Card.

When an approval round adds you as an approver, Ravenna sends an approval request as a DM in Microsoft Teams. You can approve or decline (with an optional reason) directly from the card.

<View title="Human" icon="user">
  ## How approvals appear

  Approvers receive a direct message from the Ravenna bot with an Adaptive Card containing:

  * The ticket number and title
  * The requester and current status
  * Approval context (which round, what's being approved)
  * **Approve** and **Decline** action buttons

  Clicking **Decline** reveals an optional reason field before the final submit.

  ***

  ## Approve or decline

  <Steps>
    <Step title="Open the DM from Ravenna">
      The card arrives as a direct message from the Ravenna app. Open the chat to see it.
    </Step>

    <Step title="Click Approve or Decline">
      Approve records your approval and advances the round. Decline asks for an optional reason, then records your decline.
    </Step>

    <Step title="Confirmation">
      The card is replaced with a confirmation showing your decision and a deep link back to the ticket in Ravenna.
    </Step>
  </Steps>

  <Info>
    If the round has multiple approvers, your decision is recorded against your slot in the round. The round completes when its approval rules are satisfied.
  </Info>
</View>

<View title="Agent" icon="bot">
  ## Mental model

  Approval delivery is independent of the per-ticket chat conversation. When `APPROVAL_ROUND_APPROVER_ADDED` fires, Ravenna sends each newly-added approver a 1:1 chat card via the Bot Framework, regardless of whether the ticket already has a Teams conversation.

  This means approval cards are reliably delivered even when the ticket originated from email, the web portal, or another channel that has no Teams thread.

  ***

  ## Event flow

  | Event                           | Behavior                                                                                                |
  | ------------------------------- | ------------------------------------------------------------------------------------------------------- |
  | `APPROVAL_ROUND_APPROVER_ADDED` | DM each added approver an approval request card.                                                        |
  | `TICKET_APPROVAL_COMPLETED`     | Post or update an approval-completed card in the ticket's primary conversation summarising the outcome. |

  The approval-completed card uses `isTicketApproved` to render the correct outcome state (approved vs declined).

  ***

  ## Submission contract

  Approval cards use the same Adaptive Card submission plumbing as other forms:

  * `activity.value.actionType = 'approval_approve' | 'approval_decline'`
  * Decline submissions include the reason from the `DECLINE_REASON_INPUT_ID` input.

  `processFormSubmission` dispatches to `ApprovalService`, which updates the approval round and dispatches downstream events.

  After processing, the card is replaced with `buildApprovalConfirmationCard` (or `buildApprovalErrorCard` on failure).

  ***

  ## Constraints and gotchas

  * Approvers must be provisioned Ravenna users. Ravenna provisions on the fly via Microsoft Graph when an approval card is delivered if the user doesn't exist yet.
  * The bot must be able to reach the approver in a 1:1 chat. If the approver has never installed or interacted with the Ravenna app in Teams, the first interaction may require them to accept the bot. Outbound approval DMs send even though inbound DMs are not yet processed in the beta. Approvers only need to click the Approve / Decline buttons on the card.
  * Approval delivery uses the bot path (proactive messaging via cached client-credentials bot token). The Graph fallback for creating chats is currently deferred.
  * **Biometric / step-up override**: when a workspace requires an additional auth challenge for high-sensitivity approvals, Ravenna sends a biometric-override variant of the card that links the approver to the Ravenna web app to complete the challenge. The Teams card itself only records intent; the recorded decision is committed once the override completes.
</View>