---
title: 集成
description: 将 Jamdesk Docs Search API 连接到 Intercom、Zendesk、Slack 和自定义聊天机器人，包含各集成的分步指南。
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

本指南介绍如何将 Docs Search API 连接到最常用的工具：Intercom、Zendesk、Slack 和自定义聊天机器人。

## Intercom（Fin AI Agent）

Intercom 的 Fin AI Agent 支持 **Data Connectors**：Fin 可与 Intercom 文章一起查询的外部搜索源。连接 Docs Search API 后，Fin 可以直接从 Jamdesk 文档中回答问题。

<Steps>
  <Step title="生成 API 密钥">
    在 Jamdesk 仪表板中，前往 **Project Settings → API Keys**，然后点击 **Generate Key**。将其命名为 "Intercom Fin"，并复制 `jd_live_` 密钥（总长度为 40 个字符）。
  </Step>
  <Step title="打开 Intercom 的 AI Agent 设置">
    在 Intercom 中，前往 **AI Agent → Data Sources → Add Source → API**。
  </Step>
  <Step title="配置连接器">
    输入以下详细信息：

    | 字段 | 值 |
    |-------|-------|
    | **Endpoint URL** | `https://your-project.jamdesk.app/_api/search` |
    | **Method** | `POST` |
    | **Auth header** | `Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a` |
    | **Query field** | `query` |
    | **Result path** | `results[*].content` |
  </Step>
  <Step title="测试连接">
    使用 Intercom 内置的测试工具发送示例查询。确认 Fin 返回了文档中的相关段落。
  </Step>
  <Step title="为收件箱启用">
    在 Fin 配置中启用数据连接器。Fin 现在会在回答客户问题时引用您的文档。
  </Step>
</Steps>

<Info>
Fin 会使用 `score` 字段，因此得分较高的结果会优先出现在其回答中。得分低于 0.7 的段落通常不会被使用。
</Info>

---

## Zendesk（MCP 服务器）

Zendesk 的 AI 功能支持将 MCP 服务器作为知识源。使用 Jamdesk 内置的 MCP 服务器，无需编写自定义代码即可将文档连接到 Zendesk 的 AI 代理。

<Steps>
  <Step title="查找 MCP 服务器 URL">
    MCP 服务器位于 `https://your-project.jamdesk.app/_jd/mcp`。MCP 服务器不需要 API 密钥；它使用项目的公开文档。
  </Step>
  <Step title="在 Zendesk 中添加 MCP 服务器">
    在 Zendesk Admin Center 中，前往 **AI Agents → Knowledge Sources → Add MCP Server**。
  </Step>
  <Step title="输入服务器 URL">
    粘贴 MCP 服务器 URL：`https://your-project.jamdesk.app/_jd/mcp`
  </Step>
  <Step title="验证连接">
    Zendesk 将列出可用工具（`searchDocs`、`getPage`）。确认两个工具都已检测到，然后保存。
  </Step>
</Steps>

<Info>
MCP 服务器公开的搜索索引与 Docs Search API 使用的索引相同。需要经过身份验证的访问、按密钥限流或撤销控制时，请使用 Docs Search API（配合 `jd_live_` 密钥）。
</Info>

---

## 自定义聊天机器人

通过标准的 `fetch` 调用，为任何聊天机器人或 Web 应用添加文档搜索。由于已启用 CORS，基于浏览器的客户端无需后端代理即可直接调用 API。

```javascript
async function searchDocs(query) {
  const response = await fetch(
    "https://your-project.jamdesk.app/_api/search",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ query, limit: 5 }),
    }
  );

  if (!response.ok) {
    const { error } = await response.json();
    throw new Error(error);
  }

  const data = await response.json();
  return data.results;
}

// Example usage
const results = await searchDocs("How do I configure a custom domain?");

results.forEach((result) => {
  console.log(`[${result.score.toFixed(2)}] ${result.title}`);
  console.log(result.content);
  console.log(result.url);
  console.log("---");
});
```

### 构建 AI 代理工具

将搜索结果作为上下文传递给语言模型，以生成基于文档的回答：

```javascript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function answerFromDocs(userQuestion) {
  // 1. Search your docs
  const results = await searchDocs(userQuestion);
  const context = results
    .map((r) => `[${r.title}](${r.url})\n${r.content}`)
    .join("\n\n---\n\n");

  // 2. Pass context to Claude
  const message = await client.messages.create({
    model: "claude-sonnet-4-5-20241022",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: `Answer the following question using only the provided documentation excerpts.
If the answer isn't in the docs, say so.

Documentation:
${context}

Question: ${userQuestion}`,
      },
    ],
  });

  return message.content[0].text;
}
```

---

## Slack 机器人

构建一个 `/docs` Slack 斜杠命令，搜索文档并将结果发布到任意频道。

```javascript
import { App } from "@slack/bolt";

const app = new App({
  token: process.env.SLACK_BOT_TOKEN,
  signingSecret: process.env.SLACK_SIGNING_SECRET,
});

app.command("/docs", async ({ command, ack, respond }) => {
  await ack();

  const query = command.text.trim();
  if (!query) {
    await respond("Usage: `/docs <your question>`");
    return;
  }

  try {
    const response = await fetch(
      "https://your-project.jamdesk.app/_api/search",
      {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${process.env.JAMDESK_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ query, limit: 3 }),
      }
    );

    const data = await response.json();

    if (data.results.length === 0) {
      await respond(`No results found for: _${query}_`);
      return;
    }

    const blocks = [
      {
        type: "section",
        text: {
          type: "mrkdwn",
          text: `*Results for:* _${query}_`,
        },
      },
      { type: "divider" },
      ...data.results.flatMap((result) => [
        {
          type: "section",
          text: {
            type: "mrkdwn",
            text: `*<${result.url}|${result.title}>*\n${result.content}`,
          },
        },
        { type: "divider" },
      ]),
    ];

    await respond({ blocks });
  } catch (err) {
    await respond(`Error searching docs: ${err.message}`);
  }
});

(async () => {
  await app.start(process.env.PORT || 3000);
  console.log("Slack bot is running");
})();
```

在 Slack 应用的环境变量中设置 `JAMDESK_API_KEY`。切勿将密钥硬编码。

---

## 子路径托管（Cloudflare Worker）

如果您使用[子路径托管](/cn/deploy/subpath-hosting)，将文档通过域名下的某个路径提供服务（默认为 `/docs`，也可以使用 `/help` 等自定义子路径），则还需要通过 Cloudflare Worker 代理 `/_api` 路由，并同时代理文档路径。

将 `/_api` 添加到 Worker 中的 `PROXY_PATHS` 数组，并使用您在仪表板中配置的路径前缀：

```javascript
const PROXY_PATHS = [
  "/docs",  // or your custom subpath, e.g. "/help"
  "/_jd",
  "/_api",  // Add this line
];
```

这样，发送到 `yoursite.com/_api/search` 的搜索请求（如果使用自定义子路径，则为 `yoursite.com/help/_api/search`）就会转发到您的 Jamdesk 文档站点。

<Warning>
无论请求通过何种方式路由，`/_api` 路由都要求使用 `jd_live_` API 密钥进行身份验证。通过 Cloudflare 代理不会绕过身份验证。
</Warning>