> ## 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.

# Creating tickets

> Create Ravenna tickets directly from Microsoft Teams using channel messages, the Ravenna bot, and Adaptive Card forms.

Ravenna offers multiple ways to create tickets directly from Microsoft Teams, making it easy for both your team and end users to get support without switching tools.

<View title="Human" icon="user">
  <Info>
    **One ticket per conversation:** Ravenna follows a one ticket per conversation model. Once a channel thread has a linked ticket, subsequent messages in that thread sync to the same ticket rather than creating new ones.

    <Note>
      1:1 DMs to the Ravenna bot are not yet processed in the Teams beta. Ticket creation flows through connected channels only. DM-initiated tickets are on the roadmap.
    </Note>
  </Info>

  ## Request channels

  Request channels are Teams channels where tickets are created from messages. Use any standard or private Teams channel as a request channel.

  <Steps>
    <Step title="Install Ravenna in the team">
      Install the Ravenna app to the team that contains the channel. A team owner must complete this step so Ravenna receives the resource-specific consent permissions it needs.
    </Step>

    <Step title="Connect the channel">
      Post a message in the channel that @-mentions **@Ravenna**. The bot replies with an Adaptive Card. Click **Set up as request channel** and select your [Ravenna channel](/documentation/platform/channels).
    </Step>
  </Steps>

  <Info>
    Multiple Teams channels can connect to a single Ravenna channel. All connected Teams channels share the same channel settings and automation rules.
  </Info>

  ***

  ## Methods

  <Tabs>
    <Tab title="Channel messages">
      Every message posted in a connected request channel becomes a ticket. The Ravenna bot replies in the thread with a confirmation card linking back to the ticket in Ravenna.

      <Info>
        Channel messages create tickets regardless of whether the bot is @-mentioned. The `ChannelMessage.Read.Group` resource-specific consent permission lets the bot see every message in channels where it's installed.
      </Info>
    </Tab>

    <Tab title="AI creation">
      When an Agent is connected to your channel, end users can ask questions in natural language. The Agent either answers directly from your knowledge base or creates a ticket on the user's behalf.

      <AccordionGroup>
        <Accordion title="Direct command" defaultOpen>
          Type **"Create a ticket: \[your message]"** and the Agent automatically opens a ticket for you.
        </Accordion>

        <Accordion title="Agent prompt">
          If the Agent can't answer a question, it offers to create a ticket. Click the button on the Adaptive Card to confirm.
        </Accordion>

        <Accordion title="Attach a file or screenshot">
          Drag and drop a file into the same Teams message you send to the Agent. The Agent reads PDFs, images, and text files and uses them to answer questions or prefill ticket forms.
        </Accordion>
      </AccordionGroup>
    </Tab>

    <Tab title="Adaptive Card forms">
      When a workspace uses [request types](/documentation/tickets/forms/overview) or [workflow triggers](/documentation/automate/workflows/overview), Ravenna renders the form as an interactive Adaptive Card. Fill in the fields and click **Submit**. The card converts into a ticket card and the ticket is created with the field values you entered.

      <Info>
        Submitting an Adaptive Card form produces a ticket attributed to the submitter.
      </Info>
    </Tab>
  </Tabs>

  ***

  ## Ticket privacy

  Ravenna's privacy rules are consistent across chat integrations.

  ### Privacy behavior

  <AccordionGroup>
    <Accordion title="Form privacy" icon="shield-check" defaultOpen>
      Forms can be configured with a **Private** toggle that sets the default privacy for tickets created with that form.

      When a form has privacy enabled, tickets created in channels become private and the ticket card is only visible to people with access.

      <Callout icon="link" color="#6B7280">
        Learn more about [form configuration](/documentation/tickets/forms/custom-fields).
      </Callout>
    </Accordion>

    <Accordion title="Privacy priority" icon="list-ordered">
      When multiple privacy settings could apply, Ravenna follows this priority order:

      <Steps>
        <Step title="Form setting">
          If the form has privacy enabled, the ticket is private
        </Step>

        <Step title="Default">
          Otherwise, the ticket is public within the workspace
        </Step>
      </Steps>
    </Accordion>
  </AccordionGroup>

  ### Who can see private tickets

  Private tickets are only visible to:

  * The ticket requester
  * Assigned team members
  * Followers explicitly added to the ticket
  * Workspace administrators
</View>

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

  Tickets can be created from Microsoft Teams through multiple entry points. The entry point determines the ticket's source, privacy, and conversation context.

  Inbound Teams activities arrive at the Bot Framework messaging endpoint, are validated against the Microsoft OpenID configuration, and are routed to the right Ravenna integration by **Azure AD tenant ID** (`activity.channelData.tenant.id` → `Integration.externalId`). The webhook handler responds 200 immediately and enqueues the activity to BullMQ for asynchronous processing.

  ***

  ## Ticket creation methods

  | Method                   | Trigger                                      | Where it works                                                         | Notes                                                                                                                                                                                         |
  | ------------------------ | -------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | **Channel message**      | Any message in a connected request channel   | Channels where Ravenna is installed and a `ChatChannel` mapping exists | Bot mention is stripped from the text before processing but is not required to fire                                                                                                           |
  | **AI agent**             | User sends message, agent creates ticket     | Connected request channels with an agent configured                    | Agent collects info conversationally, may render an Adaptive Card form                                                                                                                        |
  | **Adaptive Card form**   | User submits a request-type or workflow form | Anywhere a form card was rendered                                      | Form fields populate `customFields` on the new ticket                                                                                                                                         |
  | **Reaction**             | React with a configured emoji (e.g. ✅)       | Connected request channels                                             | Reaction maps to a ticket action via the static reaction map (see [emoji actions](/integrations/microsoft-teams/emoji-actions)). The 🎫 manual-create reaction is not yet available on Teams. |
  | **Connect-channel flow** | @-mention the bot in an unmapped channel     | Any channel where Ravenna is installed                                 | Bot offers an Adaptive Card to set up the channel as a request or triage channel                                                                                                              |

  Key distinction: channel‑message ticket creation only fires in channels that have an active `ChatChannel` mapping. @-mentions in **unmapped** channels trigger the connect-channel card instead of creating a ticket. 1:1 DMs with the bot are not yet a ticket-creation entry point on Teams.

  ***

  ## One ticket per conversation

  Ravenna links each Teams conversation to at most one ticket via the `ChatConversation` table. The first message in a channel thread creates the ticket and the linkage; subsequent messages in that thread dispatch as `MESSAGE_CREATED` events against the same ticket.

  ***

  ## Privacy rules for Teams-created tickets

  Privacy is determined by a priority chain:

  1. **Form privacy**: If the form used has the "Private" toggle enabled, the ticket is private.
  2. **Default**: Otherwise, the ticket is public within the workspace.

  Private tickets are visible only to the requester, assignee, followers, approvers, and workspace admins.

  ***

  ## Deep links back to Teams

  When a ticket is created from a **channel** message, Ravenna stores a deep link on the ticket pointing back to the originating Teams message:

  ```
  https://teams.microsoft.com/l/message/{channelId}/{messageId}?tenantId=...&groupId=...&parentMessageId=...
  ```

  The link is built purely from identifiers on the inbound activity (`channelData.channel.id`, activity ID, `channelData.tenant.id`, `channelData.team.aadGroupId`), with no Graph API call required.

  1:1 and group chats do not have a stable public deep-link format, so even when a ticket is linked to a chat conversation (for example, an approval card), no Teams deep link is attached.

  ***

  ## Constraints and gotchas

  * Reactions only fire on the message the user reacted to. If the reaction is on a thread reply, Ravenna uses `replyToId` to find the matching `ChatMessage` and target its ticket; if no match is found, it falls back to the conversation's linked ticket.
  * Removing a reaction is a no-op in v1.
  * The `MESSAGE_CREATED` event is skipped for messages that originated in Teams unless they are AI-generated, to avoid echoing user messages back into the same conversation.
  * Private messages from Ravenna (workspace internal notes) are never sent outbound to Teams.
  * Outbound messages from Ravenna are always sent as the **bot user**. Author attribution is preserved by wrapping human-authored messages in an Adaptive Card with an avatar+name header. Bot Framework has no API to post as an arbitrary user.
</View>