Dokumentasi

Bangun sistem dukungan yang terasa native di produk Anda

Pelajari cara kerja percakapan, cara menyesuaikan dan menyematkan widget Tanggap.ai, serta cara menghubungkan aplikasi native atau backend dengan API integrasi.

Mulai di sini

Ringkasan

Tanggap.ai adalah satu mesin dukungan AI dengan tiga antarmuka: widget situs web yang dapat disematkan, inbox dasbor untuk tim Anda, dan API server-to-server untuk aplikasi native dan backend.

Ketiga antarmuka berbagi workspace, basis pengetahuan, kontak, percakapan, dan kuota pesan AI yang sama. Pengunjung dapat memulai dari widget, berlanjut di inbox, dan ditindaklanjuti melalui aplikasi Anda sendiri tanpa kehilangan konteks.

Widget

Jalur tercepat untuk situs web. Cukup letakkan satu tag skrip di situs Anda dan launcher akan muncul di kanan bawah.

Dasbor

Inbox tim Anda. Baca percakapan, balas sebagai manusia, kembalikan ke AI, selesaikan thread, dan pantau penggunaan.

API Integrasi

Gunakan API key untuk membuat percakapan, mengirim pesan, streaming jawaban, dan menerima webhook bertanda tangan dari aplikasi Anda.

Basis Pengetahuan

Unggah file PDF, TXT, atau Markdown. Tanggap memotong dan membuat embedding sekali, lalu mengutip sumber yang relevan dalam jawaban.

Satu kuota. Jawaban widget dan API dihitung ke dalam kuota pesan AI bulanan yang sama. Penggunaan BYOK tidak mengurangi kuota terkelola.

Percakapan

Apa itu percakapan?

Percakapan adalah satu thread dukungan berkelanjutan antara pengguna akhir dan workspace Anda. Thread ini memuat pesan, penanggung jawab saat ini (AI atau manusia), serta kontak pemiliknya.

Percakapan dimulai otomatis saat pengunjung mengirim pesan widget pertama, atau saat backend Anda memanggil POST /v1/integration/conversations. Kontak otomatis dideduplikasi: pengunjung widget berulang menggunakan sesi browser yang sama, dan pemanggil API menggunakan externalUserId yang sama.

Kontak

Orang di balik thread. Kontak widget menggunakan sesi browser; kontak API menggunakan externalUserId tetap Anda, dengan nama, email, dan metadata opsional.

Percakapan

Thread itu sendiri: channel, status, waktu pesan terakhir, dan tautan ke kontak.

Pesan

Giliran pesan pengguna, asisten, manusia, dan sistem/alat. Pesan asisten dapat memuat sitasi dari basis pengetahuan.

Eskalasi

Ketika AI tidak dapat membantu, thread dapat dieskalasi dan dijawab oleh anggota tim dari inbox.

Status & siklus hidup

StatusArtiPihak yang membalas
aiAI sedang menangani thread. Percakapan baru dari widget dan API dimulai di sini.Tanggap.ai menggunakan basis pengetahuan Anda.
humanAnggota tim menangani thread. AI tidak membalas.Tim Anda dari Inbox.
escalatedEskalasi diminta dan thread sedang menunggu anggota tim.Tim Anda; membalas akan mengambil alih thread.
resolvedThread ditutup. Buka kembali dengan Kembalikan ke AI jika pelanggan kembali.Tidak ada hingga dibuka kembali. API mengembalikan 409 untuk pesan baru pada thread yang sudah selesai.

Channel menunjukkan asal thread: widget untuk obrolan situs web, api untuk integrasi server-to-server, dan voice untuk panggilan dari asisten suara. Status dan channel muncul di setiap baris percakapan di dasbor.

Alur kerja inbox

Buka Percakapan

Filter bawaan adalah Belum Selesai, sehingga thread AI, manusia, dan dieskalasi tetap terlihat. Thread yang selesai dapat dilihat dengan satu klik filter.

Baca thread

Sitasi menunjukkan dokumen basis pengetahuan yang mendukung setiap jawaban AI. Gunakan pencarian untuk menemukan kontak atau pesan.

Balas atau ambil alih

Kirim balasan manusia untuk menjeda AI dan memindahkan thread ke Agen Manusia. Gunakan Tingkatkan dengan AI untuk membuat draf balasan tanpa mengembalikan kendali.

Selesaikan atau kembalikan

Tandai thread selesai jika sudah tuntas. Kembalikan ke AI membukanya kembali atau mengembalikannya ke balasan otomatis.

Jumlah inbox. Badge sidebar dan menu Percakapan hanya menghitung thread yang belum selesai. Thread akan hilang dari badge setelah ditandai selesai.

Penggunaan widget

Kustomisasi widget

Widget adalah kotak obrolan situs web yang dilihat pelanggan Anda. Kustomisasi di Kustomisasi Widget, lalu salin skrip embed dari Pengaturan & Integrasi.

Perubahan disimpan per workspace. Pratinjau langsung widget di sebelah kanan halaman kustomisasi diperbarui secara langsung saat Anda mengedit, sehingga Anda dapat melihat hasilnya sebelum dipublikasikan.

Branding & pengetahuan

  • Launcher — posisi, label tombol, dan logo kustom opsional. Logo kustom dan menyembunyikan branding Tanggap.ai adalah fitur Pro.
  • Tampilan — warna aksen, judul header, pesan sambutan, dan saran pertanyaan.
  • Basis Pengetahuan — unggah file PDF, TXT, atau Markdown dari Basis Pengetahuan. Setiap file di-parse, dipotong, dan di-embed untuk pencarian.
  • Suara — panggilan suara tersedia di paket Pro dan Enterprise. Suara terkelola mencakup 60 menit/bulan di Pro dan 300 menit/bulan di Enterprise.

Batas Basis Pengetahuan

PaketDokumenUkuran file maks
Free / Starter11 MB
Pro102 MB
EnterpriseUnlimited (fair use)2 MB

Format yang didukung adalah PDF, TXT, dan MD. Mengunggah melampaui batas paket atau batas ukuran file akan membuka jendela upgrade Pro.

Uji sebelum peluncuran

Buka pratinjau

Gunakan Pratinjau widget dari inbox kosong atau Kustomisasi Widget untuk membuka pratinjau langsung workspace Anda.

Ajukan pertanyaan nyata

Kirim pertanyaan yang ada di basis pengetahuan Anda dan pastikan jawabannya memuat sitasi.

Uji eskalasi

Minta bantuan manusia, lalu pastikan thread muncul di bawah Dieskalasi di inbox.

Periksa penggunaan

Setiap jawaban AI terkelola menambah meteran pesan AI di Paket & Tagihan. Jawaban BYOK tidak menambah meteran.

Integrasi widget

Pasang widget

Pemasangan hanya memerlukan satu tag skrip. Skrip membaca ID publik organisasi Anda, memuat bundle widget, dan menampilkan launcher di sudut kanan bawah.

1. Salin ID Publik Organisasi Anda

Buka Pengaturan & Integrasi di dasbor. Salin ID Publik Organisasi yang ditampilkan di bagian atas. ID ini berbentuk org_xxxxxxxxxxxxxxxxxxxx dan aman diekspos di HTML sisi klien — ini bukan API key.

2. Tambahkan cuplikan embed

Letakkan tag ini tepat sebelum penutup </body> di setiap halaman tempat widget harus muncul.

HTML
<script
  src="https://tanggapi.my.id/widget.js"
  data-organization-id="org_xxxxxxxxxxxxxxxxxxxx"
  defer
></script>

React

Render komponen ini sekali di app shell Anda. Komponen ini menambahkan pemuat saat mount dan menghapusnya saat unmount.

React
import { useEffect } from 'react'

export function TanggapWidget() {
  useEffect(() => {
    const script = document.createElement('script')
    script.src = 'https://tanggapi.my.id/widget.js'
    script.async = true
    script.setAttribute('data-organization-id', 'org_xxxxxxxxxxxxxxxxxxxx')
    document.body.appendChild(script)
    return () => script.remove()
  }, [])
  return null
}

Next.js

Tambahkan ini ke root layout Anda agar widget dimuat setelah hidrasi di setiap rute.

Next.js App Router
import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://tanggapi.my.id/widget.js"
          data-organization-id="org_xxxxxxxxxxxxxxxxxxxx"
          strategy="afterInteractive"
        />
      </body>
    </html>
  )
}

3. Batasi domain yang diizinkan

Di Pengaturan & Integrasi, tambahkan domain yang diizinkan menyematkan widget. Kosongkan daftar untuk mengizinkan situs apa pun selama pengujian; tambahkan domain produksi sebelum peluncuran.

Jika situs Anda menggunakan Content Security Policy (CSP), izinkan origin skrip widget di script-src dan origin API di connect-src:

CSP
script-src 'self' https://tanggapi.my.id;
connect-src 'self' https://tanggapi.my.id;

Pemecahan Masalah

GejalaPemeriksaan
Launcher tidak munculPastikan tag skrip berada sebelum </body>, ID publik sudah benar, dan tab network browser menunjukkan widget.js mengembalikan 200.
Launcher muncul dua kaliHapus cuplikan duplikat dari layout, template, atau tag manager. Render komponen React sekali saja di root aplikasi.
Berfungsi lokal, tidak di produksiTambahkan domain produksi ke dalam daftar domain yang diizinkan. Periksa CSP dan pemblokir skrip.
Widget termuat tetapi tidak dapat membalasPeriksa origin API di connect-src, lalu pastikan workspace masih memiliki kuota pesan AI.

API key

Dokumentasi API key

API integrasi memungkinkan backend atau aplikasi native Anda membuat percakapan, mengirim pesan, streaming jawaban, dan menerima webhook. API key tersedia pada paket Pro dan Enterprise.

Buat & kelola key

Buka API & Developer

Di sidebar dasbor, pilih API & Developer.

Buat key

Klik <b>Buat API key</b>, beri nama, dan secara opsional pilih masa berlaku (30 hari, 90 hari, atau 1 tahun).

Salin sekali

Key mentah hanya ditampilkan tepat sekali. Segera simpan di secret manager server Anda. Tanggap hanya menyimpan hash SHA-256.

Rotasi atau cabut

Buat key pengganti, deploy, lalu cabut key lama. Pencabutan langsung berlaku saat itu juga.

Key diawali dengan tgp_live_ dan disamarkan di dasbor sebagai tgp_live_••••••••3f9a. Waktu penggunaan terakhir dan status masa berlaku ditampilkan dalam daftar key.

Scope

ScopeMengizinkan
chat:writeJawaban basis pengetahuan stateless dengan POST /v1/integration/ai/answer.
conversations:readMembaca detail percakapan dan riwayat pesan berhalaman.
conversations:writeMembuat percakapan, mengirim pesan, menyelesaikan, dan mengeskalasi.

Otentikasi

Kirimkan key sebagai Bearer token pada setiap permintaan. Jangan pernah menaruh API key di browser, bundle aplikasi seluler, atau repositori publik; panggil API dari server atau backend tepercaya Anda.

cURL
curl https://tanggapi.my.id/v1/integration/ai/answer \
  -H "Authorization: Bearer tgp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"How do I reset my password?"}'

Setiap respons menyertakan X-Request-Id. Sertakan header ini saat menghubungi dukungan agar permintaan dapat dilacak. Header batas rate limit dikembalikan pada setiap permintaan integrasi.

Panduan Cepat

Buat percakapan untuk salah satu pengguna akhir Anda, lalu kirim pesan. API menyimpan giliran pengguna dan jawaban AI, sehingga riwayat tersedia dari percakapan yang sama.

1 · Buat percakapan
curl -X POST https://tanggapi.my.id/v1/integration/conversations \
  -H "Authorization: Bearer tgp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_42",
    "name": "Ayu",
    "email": "ayu@example.com"
  }'
2 · Kirim pesan
curl -X POST https://tanggapi.my.id/v1/integration/conversations/CONVERSATION_ID/messages \
  -H "Authorization: Bearer tgp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f4c2c1e-7a4e-4f0e-9a1e-2b6f8c9d0e11" \
  -d '{"message":"How do I reset my password?"}'
3 · Baca riwayat
curl "https://tanggapi.my.id/v1/integration/conversations/CONVERSATION_ID/messages?limit=20" \
  -H "Authorization: Bearer tgp_live_YOUR_KEY"

Endpoint

Metode & pathTujuanScope
POST /v1/integration/ai/answerTanyakan ke basis pengetahuan tanpa membuat percakapan.chat:write
POST /v1/integration/conversationsBuat atau gunakan kembali kontak dan buka percakapan.conversations:write
GET /v1/integration/conversations/:idMembaca status, kontak, pengguna eksternal, dan timestamp.conversations:read
GET /v1/integration/conversations/:id/messagesMembaca pesan dengan pagination kursor (1–100 per halaman).conversations:read
POST /v1/integration/conversations/:id/messagesKirim pesan dan kembalikan jawaban AI, atau lakukan streaming dengan ?stream=true.conversations:write
POST /v1/integration/conversations/:id/resolveTutup percakapan.conversations:write
POST /v1/integration/conversations/:id/escalatePindahkan percakapan ke antrean manusia.conversations:write
Kepemilikan percakapan. Percakapan yang dibuat oleh satu workspace tidak terlihat oleh API key lain. Akses lintas workspace mengembalikan 404, bukan data workspace lain.

Pesan & streaming

Permintaan pesan normal mengembalikan jawaban, sitasi, informasi penggunaan basis pengetahuan, dan kedua ID pesan. Jika percakapan dieskalasi atau manusia, pesan pengguna disimpan tanpa jawaban AI. Jika selesai, API mengembalikan 409.

JSON response
{
  "conversationId": "conv_...",
  "userMessageId": "msg_...",
  "assistantMessageId": "msg_...",
  "answer": "You can reset your password from Settings → Security.",
  "citations": [
    { "docTitle": "account-guide.pdf", "page": 4 }
  ],
  "usedKnowledgeBase": true,
  "status": "ai"
}

Untuk pengiriman token per token, tambahkan ?stream=true. Responsnya berupa Server-Sent Events dengan empat nama event: citations, delta, done, dan error. Event done membawa kedua ID pesan.

SSE
curl -N -X POST "https://tanggapi.my.id/v1/integration/conversations/CONVERSATION_ID/messages?stream=true" \
  -H "Authorization: Bearer tgp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"How do I reset my password?"}'

Idempotensi. Tambahkan Idempotency-Key pada permintaan pesan JSON agar pengulangan tidak menghasilkan pesan duplikat atau menagih kuota AI dua kali. Memutar ulang key dan body yang sama akan mengembalikan respons asli; body yang berbeda mengembalikan 409. Permintaan SSE menolak header ini dengan 400 karena stream tidak dapat diputar ulang.

Webhook

Daftarkan endpoint HTTPS publik di API & Developer → Webhook. Tanggap mengirimkan event bertanda tangan melalui antrean dan mengulang pengiriman yang gagal dengan backoff.

EventDipicu saat
conversation.createdPercakapan widget atau API dibuat.
message.createdPesan pengguna, asisten, atau manusia disimpan.
conversation.escalatedThread dialihkan ke antrean manusia.
conversation.resolvedThread ditutup.

Setiap pengiriman menyertakan X-Tanggap-Signature: t=<timestamp>,v1=<hmac>. Hitung HMAC atas timestamp dan body permintaan mentah dengan secret tanda tangan endpoint Anda, dan tolak timestamp yang usang. Pengiriman yang gagal akan diulang setelah 60 detik, 300 detik, 900 detik, 1 jam, dan 6 jam. Rotasi secret dengan menghapus dan menambahkan kembali endpoint.

Limit & kode error

Rate limit diterapkan per API key dan direset setiap menit. Setiap respons menyertakan X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset; kode 429 juga menyertakan Retry-After.

PaketPermintaan per menit
Pro60
Enterprise240
StatusArti
400JSON tidak valid atau kesalahan validasi. Periksa body permintaan dan format kursor.
401API key tidak ada, dicabut, atau kedaluwarsa.
402Kendala paket atau kuota: Akses API memerlukan Pro, atau kuota pesan AI telah habis.
403Key tidak memiliki scope yang diperlukan.
404Percakapan tidak ditemukan di workspace ini.
409Percakapan telah selesai, ketidakcocokan body idempotensi, atau permintaan dengan key yang sama masih diproses.
429Batas rate limit terlampaui. Coba lagi setelah jumlah detik dalam Retry-After.
503Penyedia AI belum dikonfigurasi atau sedang tidak tersedia.
Referensi. Spesifikasi OpenAPI 3.1 berada di docs/api/openapi.yaml. SDK TypeScript adalah @tanggap/sdk dengan ai.answer, conversations.*, dan messages.*. Quickstart dasbor mencakup tab curl, TypeScript, React Native, dan Flutter.