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

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