Jamdesk Documentation logo

Integrações

Conecte a API de Busca de Documentação do Jamdesk ao Intercom, Zendesk, Slack e chatbots personalizados. Guias passo a passo para cada integração.

Este guia mostra como conectar a API de Busca de Documentação às ferramentas mais comuns: Intercom, Zendesk, Slack e chatbots personalizados.

Intercom (Fin AI Agent)

O Fin AI Agent do Intercom oferece suporte a Data Connectors: fontes de busca externas que o Fin consulta junto com seus artigos do Intercom. Conecte a API de Busca de Documentação para que o Fin possa responder perguntas com base na sua documentação do Jamdesk.

1
Gerar uma chave de API

No painel do Jamdesk, acesse Project Settings → API Keys e clique em Generate Key. Dê o nome "Intercom Fin" e copie a chave jd_live_ (40 caracteres no total).

2
Abrir as configurações do AI Agent do Intercom

No Intercom, acesse AI Agent → Data Sources → Add Source → API.

3
Configurar o conector

Informe os seguintes dados:

CampoValor
Endpoint URLhttps://your-project.jamdesk.app/_api/search
MethodPOST
Auth headerAuthorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a
Query fieldquery
Result pathresults[*].content
4
Testar a conexão

Use a ferramenta de teste integrada do Intercom para enviar uma consulta de exemplo. Verifique se o Fin retorna trechos relevantes da sua documentação.

5
Ativar para sua caixa de entrada

Ative o data connector na configuração do Fin. Agora o Fin cita sua documentação nas respostas às perguntas dos clientes.

O Fin respeita o campo score. Resultados com pontuação mais alta aparecem primeiro nas respostas. Trechos com pontuação abaixo de 0,7 normalmente não são utilizados.


Zendesk (MCP Server)

Os recursos de IA do Zendesk aceitam servidores MCP como fontes de conhecimento. Conecte sua documentação aos agentes de IA do Zendesk por meio do servidor MCP integrado do Jamdesk. Não é necessário código personalizado.

1
Encontrar a URL do seu servidor MCP

Seu servidor MCP está disponível em https://your-project.jamdesk.app/_jd/mcp. O servidor MCP não precisa de chave de API. Ele usa a documentação pública do seu projeto.

2
Adicionar o servidor MCP no Zendesk

No Zendesk Admin Center, acesse AI Agents → Knowledge Sources → Add MCP Server.

3
Informar a URL do servidor

Cole a URL do seu servidor MCP: https://your-project.jamdesk.app/_jd/mcp

4
Verificar a conexão

O Zendesk lista as ferramentas disponíveis (searchDocs, getPage). Confirme que elas aparecem e salve.

O servidor MCP expõe o mesmo índice de busca da API de Busca de Documentação. Use a API de Busca de Documentação (com uma chave jd_live_) quando precisar de acesso autenticado, limitação de taxa por chave ou controle de revogação.


Chatbots personalizados

Adicione busca na documentação a qualquer chatbot ou aplicação web com uma chamada fetch padrão. O CORS está habilitado. Clientes executados no navegador podem chamar a API diretamente, sem um proxy de 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("---");
});

Criar uma ferramenta de AI Agent

Passe os resultados da busca como contexto para um modelo de linguagem para gerar respostas fundamentadas:

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

Bots do Slack

Crie um comando de barra /docs no Slack que pesquisa na sua documentação e publica os resultados em qualquer canal.

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

Defina JAMDESK_API_KEY nas variáveis de ambiente do seu app do Slack. Nunca coloque a chave diretamente no código.


Hospedagem em subcaminho (Cloudflare Worker)

Se você usar hospedagem em subcaminho para servir sua documentação em um caminho do seu domínio (/docs por padrão, ou um subcaminho personalizado como /help), faça também o proxy da rota /_api pelo seu Cloudflare Worker.

Adicione /_api ao array PROXY_PATHS do seu worker, usando o prefixo de caminho configurado no painel:

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

Requisições de busca para yoursite.com/_api/search (ou yoursite.com/help/_api/search em um subcaminho personalizado) passam então a alcançar o seu site de documentação do Jamdesk.

A rota /_api exige autenticação com a sua chave de API jd_live_, independentemente de como a requisição é roteada. O proxy pelo Cloudflare não contorna a autenticação.