External Tools Mitrachat: Hubungkan n8n, API Sendiri, atau Serverless ke AI Agent

Banyak tim bertanya hal yang sama setelah melihat tab External Tools di form AI Agent: "Tool tambahan ini harus dibuat di n8n saja, atau bisa pakai API sendiri?"

Jawaban singkatnya: bukan harus n8n. Yang dibutuhkan Mitrachat hanyalah satu URL webhook HTTPS publik yang bisa menerima POST JSON, memverifikasi tanda tangan HMAC, lalu mengembalikan hasil dalam format yang disepakati. n8n hanyalah salah satu cara paling nyaman untuk membangun endpoint itu.

Artikel ini menjelaskan konsep, tiga jalur integrasi yang umum dipakai, dan cara mengisi form di dashboard.

Apa itu External Tools

External Tool adalah kemampuan tambahan yang AI agent boleh panggil saat chat berlangsung. Contohnya:

• Cek status order di sistem ERP
• Validasi kode voucher
• Ambil stok real-time dari gudang
• Trigger proses panjang seperti generate laporan

Alurnya sederhana:

1. Customer mengirim pesan ("Cek order #12345")
2. AI menilai bahwa butuh data eksternal
3. Mitrachat mengirim POST ke Webhook URL tool kamu
4. Endpoint kamu memproses request dan mengembalikan JSON
5. AI menyusun jawaban natural language untuk customer

Yang penting dipahami: Mitrachat tidak menjalankan logika bisnismu. Mitrachat hanya menjadi jembatan antara AI dan sistem yang sudah kamu punya.

Kapan pakai External Tools vs fitur bawaan

Gunakan fitur bawaan Mitrachat jika kebutuhannya sudah tercakup:

Gunakan External Tools jika data atau aksi ada di sistem di luar Mitrachat — ERP, CRM lama, spreadsheet internal, microservice, atau workflow n8n yang sudah berjalan.

Field di form Add External Tool

Saat menambah tool di Agents > [agent kamu] > External Tools, setiap field punya peran spesifik:

Contoh Input Schema minimal

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "Nomor order yang ingin dicek"
    }
  },
  "required": ["order_id"]
}

Contoh Output Schema minimal

{
  "type": "object",
  "properties": {
    "status": { "type": "string" },
    "total": { "type": "number" }
  }
}

Tips menulis Description yang bagus:

• Sebut kapan tool dipakai: "Gunakan saat customer menanyakan status pesanan dan memberikan nomor order."
• Sebut batasan: "Jangan dipakai jika customer hanya bertanya kebijakan pengiriman umum."
• Hindari deskripsi terlalu generik seperti "tool untuk order".

Payload yang dikirim Mitrachat

Setiap invocation dikirim sebagai POST dengan body JSON:

{
  "invocation_id": "8b39e1a2-....",
  "agent_id": "uuid-agent",
  "chatroom_id": "uuid-chatroom",
  "input": {
    "order_id": "12345"
  },
  "timestamp": "2026-06-26T10:00:00.000Z"
}

Header penting:

Wajib verifikasi HMAC sebelum memproses request. Tanpa verifikasi, siapa pun yang tahu URL webhook bisa memalsukan invocation.

Cara kerja signature (ringkas)

Signature dihitung dari string:

POST\n{path}\n{timestamp}\n{sha256_hex_raw_body}

Gunakan X-Mitrachat-Signed-Path sebagai {path} — jangan rekonstruksi dari URL penuh, karena proxy/n8n bisa mengubah path yang terlihat.

Contoh verifikasi Node.js:

const crypto = require("crypto");

function verifyMitrachatSignature({
  rawBody,
  method,
  signedPath,
  signatureHeader,
  timestampHeader,
  signingSecret,
}) {
  const ts = Number.parseInt(timestampHeader, 10);
  if (Number.isNaN(ts) || Math.abs(Date.now() - ts) > 300_000) {
    return false;
  }

  const provided = (signatureHeader || "").replace(/^sha256=/, "");
  const bodyHash = crypto.createHash("sha256").update(rawBody, "utf8").digest("hex");
  const signingString = `${method.toUpperCase()}\n${signedPath}\n${timestampHeader}\n${bodyHash}`;
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(signingString, "utf8")
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(provided, "hex"),
    Buffer.from(expected, "hex"),
  );
}

Sync vs Async

Respons sync (sukses)

HTTP 200 dengan JSON, misalnya:

{
  "data": {
    "status": "shipped",
    "total": 150000
  }
}

Mitrachat juga menerima object langsung tanpa wrapper data — keduanya diproses.

Respons async (diterima, proses belakangan)

Balas dengan indikasi async, lalu setelah selesai POST hasil ke:

POST /api/n8n/tools/{invocation_id}/complete

dengan HMAC signature baru. Di n8n, node MitraChat Tool Response (mode Async) menangani langkah complete ini.

Jalur 1: n8n workflow (paling mudah)

Cocok untuk tim yang sudah pakai n8n atau ingin integrasi tanpa deploy backend baru.

Penting: invocation tool datang langsung dari AI agent — bukan dari event subscription. Jadi untuk external tool, pakai Webhook node bawaan n8n, bukan MitraChatWebhookTrigger (node itu untuk event seperti contact.created).

Langkah singkat:

1. Buat workflow baru di n8n
2. Tambah Webhook node — method POST, salin URL-nya
3. (Opsional) Tambah node Code untuk validasi input dan verifikasi HMAC
4. Tambah HTTP Request ke API bisnis kamu, atau Code untuk mock data saat testing
5. Tambah MitraChat Tool Response — mode sync, isi Result Data
6. Aktifkan workflow
7. Paste Webhook URL ke form External Tool di Mitrachat
8. Simpan agent, lalu uji lewat Playground atau chat live

Contoh transformasi di Code node:

const body = $input.first().json.body ?? $input.first().json;
const orderId = body.input?.order_id;
if (!orderId) {
  throw new Error("order_id wajib diisi");
}
return [{ json: { order_id: orderId, invocation_id: body.invocation_id } }];

Untuk testing lokal tanpa API nyata, ganti HTTP Request dengan Code node:

return [{
  json: {
    status: "shipped",
    total: 150000,
  },
}];

Jalur 2: API / backend sendiri

Cocok jika kamu sudah punya REST API (Express, FastAPI, Laravel, Go, dll.).

Pola endpoint:

POST /tools/check-order-status

Handler minimal:

1. Baca raw body (sebelum JSON parse) untuk verifikasi HMAC
2. Parse JSON, ambil input
3. Query database / panggil service internal
4. Return JSON 2xx

Contoh pseudo-handler (Express):

app.post("/tools/check-order-status", express.raw({ type: "application/json" }), (req, res) => {
  const rawBody = req.body.toString("utf8");
  const ok = verifyMitrachatSignature({
    rawBody,
    method: "POST",
    signedPath: req.get("X-Mitrachat-Signed-Path"),
    signatureHeader: req.get("X-Mitrachat-Signature"),
    timestampHeader: req.get("X-Mitrachat-Timestamp"),
    signingSecret: process.env.MITRACHAT_TOOL_SECRET,
  });

  if (!ok) {
    return res.status(401).json({ error: "invalid signature" });
  }

  const payload = JSON.parse(rawBody);
  const order = lookupOrder(payload.input.order_id);

  return res.json({
    data: {
      status: order.status,
      total: order.total,
    },
  });
});

Keuntungan jalur ini: logika bisnis tetap di codebase yang kamu kontrol penuh, tanpa dependensi workflow engine.

Jalur 3: Serverless function

Cocok untuk tim yang ingin endpoint ringan tanpa maintain server permanen.

Platform yang umum dipakai:

• Vercel Functions / Cloudflare Workers
• AWS Lambda + API Gateway
• Google Cloud Functions

Prasyarat sama: URL HTTPS publik, verifikasi HMAC, respons JSON valid.

Contoh minimal Cloudflare Worker (konsep):

export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const rawBody = await request.text();
    const valid = verifyMitrachatSignature({
      rawBody,
      method: "POST",
      signedPath: request.headers.get("X-Mitrachat-Signed-Path"),
      signatureHeader: request.headers.get("X-Mitrachat-Signature"),
      timestampHeader: request.headers.get("X-Mitrachat-Timestamp"),
      signingSecret: env.MITRACHAT_TOOL_SECRET,
    });

    if (!valid) {
      return Response.json({ error: "unauthorized" }, { status: 401 });
    }

    const { input } = JSON.parse(rawBody);
    return Response.json({
      data: {
        status: "available",
        sku: input.sku,
        qty: 42,
      },
    });
  },
};

Perhatikan cold start: jika function butuh beberapa detik untuk wake up, pertimbangkan naikkan timeout_ms di form tool atau gunakan mode async.

Batasan teknis yang perlu diketahui

1. URL harus publik HTTPS — localhost, IP private, dan jaringan internal diblokir (SSRF protection).
2. Port yang diizinkan: 80, 443, 8080, 8443.
3. Respons harus JSON valid dengan HTTP status 2xx untuk dianggap sukses.
4. invocation_id bersifat idempoten — pemanggilan ulang dengan ID sama harus menghasilkan respons konsisten (penting untuk retry).
5. Rate limit per tool — jika terlampaui, invocation ditolak sampai bucket refill.

Contoh use case

Cek status order (sync + n8n)

• Input: order_id
• n8n memanggil API toko
• Agent menjawab: "Order #12345 statusnya shipped, total Rp150.000"

Validasi voucher (custom API)

• Input: voucher_code
• Backend cek ke tabel promo
• Output: { valid: true, discount_percent: 10 }

Generate laporan penjualan (async)

• Input: date_range
• Function menerima job, balas async accepted
• Setelah selesai, complete invocation dengan file URL atau ringkasan angka

Troubleshooting

AI tidak memanggil tool

• Perjelas Description — sebut trigger phrase dan kondisi pemakaian.
• Pastikan Input Schema mencantumkan field yang AI bisa isi dari chat.
• Uji di Playground dengan kalimat eksplisit: "Cek order 12345"

HTTP 401 / signature invalid

• Pastikan Signing Secret di Mitrachat sama dengan yang dipakai verifier.
• Verifikasi memakai raw body, bukan object JSON yang sudah di-reformat.
• Gunakan header X-Mitrachat-Signed-Path, bukan path hasil rekonstruksi.

Timeout

• Naikkan timeout_ms di form tool (maksimum yang diizinkan UI).
• Optimasi downstream API atau pindah ke mode async.

Tool rate limited

• Naikkan rate_limit_per_min jika traffic legitimate.
• Cache hasil query yang sering diulang di sisi kamu.

SSRF blocked

• Webhook URL harus hostname publik yang resolve ke IP publik.
• Tunneling development (ngrok, cloudflared) boleh untuk testing, asal endpoint HTTPS publik.

Langkah berikutnya

Setelah external tool berjalan, pertimbangkan kombinasi ini:

• Panduan setup Mitrachat — fondasi WhatsApp + agent + knowledge base
• Optimasi Knowledge Base — kurangi halusinasi AI pada pertanyaan yang bisa dijawab dari dokumen
• Automation Rules — routing otomatis sebelum atau sesudah AI memanggil tool

Untuk integrasi n8n lebih luas (bukan hanya tool invocation), buka Settings > Integrations dan lihat dokumentasi API n8n di dashboard.