Integrazioni

Questa guida mostra come collegare la Docs Search API agli strumenti più comuni: Intercom, Zendesk, Slack e chatbot personalizzati.

Intercom (Fin AI Agent)

Il Fin AI Agent di Intercom supporta i Data Connector: sorgenti di ricerca esterne che Fin interroga insieme ai tuoi articoli Intercom. Collega la Docs Search API per permettere a Fin di rispondere alle domande partendo dalla tua documentazione Jamdesk.

---

Zendesk (MCP Server)

Le funzionalità AI di Zendesk accettano server MCP come sorgenti di conoscenza. Collega la tua documentazione agli agenti AI di Zendesk tramite il server MCP integrato di Jamdesk. Non è richiesto codice personalizzato.

---

Chatbot personalizzati

Aggiungi la ricerca nella documentazione a qualsiasi chatbot o web app con una semplice chiamata fetch. CORS è abilitato. I client basati su browser possono chiamare l'API direttamente senza un proxy backend.

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("---");
});

Creazione di uno strumento per un AI Agent

Passa i risultati della ricerca come contesto a un modello linguistico per generare risposte fondate sulla documentazione:

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;
}

---

Bot Slack

Crea un comando slash /docs per Slack che cerca nella tua documentazione e pubblica i risultati in qualsiasi canale.

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");
})();

Imposta JAMDESK_API_KEY nelle variabili d'ambiente della tua app Slack. Non inserire mai la chiave direttamente nel codice.

---

Hosting su sottopercorso (Cloudflare Worker)

Se usi l'hosting su sottopercorso per servire la documentazione su un percorso del tuo dominio (/docs per impostazione predefinita, oppure un sottopercorso personalizzato come /help), fai passare anche la route /_api attraverso il tuo Cloudflare Worker.

Aggiungi /_api all'array PROXY_PATHS nel tuo worker, usando il prefisso di percorso configurato nella dashboard:

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

Le richieste di ricerca a yoursite.com/_api/search (o yoursite.com/help/_api/search con un sottopercorso personalizzato) raggiungono quindi il tuo sito di documentazione Jamdesk.