chat-adapter-jira

Jira Cloud adapter for the Vercel Chat SDK. Maps Jira issues to Chat SDK threads and issue comments to messages, with bidirectional ADF (Atlassian Document Format) conversion.

Install

pnpm add chat-adapter-jira chat @chat-adapter/shared

Quick Start

import { Chat } from "chat";
import { createJiraAdapter } from "chat-adapter-jira";

const adapter = createJiraAdapter({
  site: process.env.JIRA_SITE,           // e.g., "mycompany" for mycompany.atlassian.net
  email: process.env.JIRA_EMAIL,
  apiToken: process.env.JIRA_API_TOKEN,
  webhookSecret: process.env.JIRA_WEBHOOK_SECRET,
});

const chat = new Chat({
  adapter,
  async onMessage({ message, thread, reply }) {
    await reply(`Got it — looking into ${message.raw.issue.key} now.`);
  },
});

// Mount the webhook handler on your HTTP server
// POST /api/webhooks/jira → chat.handleWebhook(request)

Configuration

Environment Variables

| Variable | Required | Description | |---|---|---| | JIRA_SITE | Yes | Site domain (e.g., mycompany for mycompany.atlassian.net) | | JIRA_EMAIL | Yes | Email for API token auth | | JIRA_API_TOKEN | Yes | API token from id.atlassian.com | | JIRA_WEBHOOK_SECRET | Yes | Webhook HMAC secret | | JIRA_BOT_NAME | No | Bot display name (auto-detected if omitted) | | JIRA_BOT_ACCOUNT_ID | No | Bot account ID (auto-detected if omitted) |

Jira Webhook Setup

In Jira, go to Settings → System → Webhooks and add:

• URL: Your webhook endpoint (e.g., https://your-app.com/api/webhooks/jira)
• Secret: Same value as JIRA_WEBHOOK_SECRET
• Events: Check comment_created (and optionally comment_updated)
• JQL filter (optional): project = PROJ to limit to specific projects

Features

Issue Comments

Inbound comments on Jira issues are delivered as Chat SDK messages. The adapter handles the full comment lifecycle.

async onMessage({ message, reply }) {
  // message.threadId is "jira:PROJ-42"
  // message.text is the plain text extracted from ADF
  // message.formatted is the mdast AST converted from ADF
  await reply("Thanks for the update!");
}

Rich Text (ADF) Support

The adapter bidirectionally converts between Jira's Atlassian Document Format and the Chat SDK's mdast AST. Supported elements: paragraphs, headings, bold, italic, strikethrough, code (inline and blocks), links, lists, blockquotes, tables, mentions, emoji, and horizontal rules.

Edit and Delete Comments

await chat.editMessage(threadId, commentId, "Updated response");
await chat.deleteMessage(threadId, commentId);

Markdown Messages

Send formatted comments using markdown (automatically converted to ADF):

await reply({ markdown: "**Status:** Fixed in `v2.1.0` :rocket:" });

Fetch Comment History

const { messages, nextCursor } = await chat.fetchMessages(threadId, { limit: 50 });

List Issues (JQL)

const { threads } = await chat.listThreads(channelId);
// channelId = "jira:PROJ" — lists open issues in the PROJ project

Thread and Project Info

const thread = await chat.fetchThread("jira:PROJ-42");
// thread.metadata: { summary, status, issueType, assignee, priority, ... }

const channel = await chat.fetchChannelInfo("jira:PROJ");
// channel: { name, metadata: { key, description, lead, issueTypes } }

Thread ID Format

| Format | Example | |---|---| | jira:{issueKey} | jira:PROJ-42 |

Channel IDs represent projects: jira:PROJ

Unsupported Operations

These methods throw NotImplementedError:

• addReaction() / removeReaction() — Jira has reactions in the UI but no public API
• startTyping() — no Jira equivalent
• openDM() — issues are created by users, not the bot
• stream() / openModal() / postEphemeral() / scheduleMessage()

Self-Echo Prevention

The adapter automatically skips comments from the bot's own account (resolved on initialize() via GET /myself).

License

MIT