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.
Jalur tercepat untuk situs web. Cukup letakkan satu tag skrip di situs Anda dan launcher akan muncul di kanan bawah.
Inbox tim Anda. Baca percakapan, balas sebagai manusia, kembalikan ke AI, selesaikan thread, dan pantau penggunaan.
Gunakan API key untuk membuat percakapan, mengirim pesan, streaming jawaban, dan menerima webhook bertanda tangan dari aplikasi Anda.
Unggah file PDF, TXT, atau Markdown. Tanggap memotong dan membuat embedding sekali, lalu mengutip sumber yang relevan dalam jawaban.
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.
Orang di balik thread. Kontak widget menggunakan sesi browser; kontak API menggunakan externalUserId tetap Anda, dengan nama, email, dan metadata opsional.
Thread itu sendiri: channel, status, waktu pesan terakhir, dan tautan ke kontak.
Giliran pesan pengguna, asisten, manusia, dan sistem/alat. Pesan asisten dapat memuat sitasi dari basis pengetahuan.
Ketika AI tidak dapat membantu, thread dapat dieskalasi dan dijawab oleh anggota tim dari inbox.
Status & siklus hidup
| Status | Arti | Pihak yang membalas |
|---|---|---|
| ai | AI sedang menangani thread. Percakapan baru dari widget dan API dimulai di sini. | Tanggap.ai menggunakan basis pengetahuan Anda. |
| human | Anggota tim menangani thread. AI tidak membalas. | Tim Anda dari Inbox. |
| escalated | Eskalasi diminta dan thread sedang menunggu anggota tim. | Tim Anda; membalas akan mengambil alih thread. |
| resolved | Thread 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
Filter bawaan adalah Belum Selesai, sehingga thread AI, manusia, dan dieskalasi tetap terlihat. Thread yang selesai dapat dilihat dengan satu klik filter.
Sitasi menunjukkan dokumen basis pengetahuan yang mendukung setiap jawaban AI. Gunakan pencarian untuk menemukan kontak atau pesan.
Kirim balasan manusia untuk menjeda AI dan memindahkan thread ke Agen Manusia. Gunakan Tingkatkan dengan AI untuk membuat draf balasan tanpa mengembalikan kendali.
Tandai thread selesai jika sudah tuntas. Kembalikan ke AI membukanya kembali atau mengembalikannya ke balasan otomatis.
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
| Paket | Dokumen | Ukuran file maks |
|---|---|---|
| Free / Starter | 1 | 1 MB |
| Pro | 10 | 2 MB |
| Enterprise | Unlimited (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
Gunakan Pratinjau widget dari inbox kosong atau Kustomisasi Widget untuk membuka pratinjau langsung workspace Anda.
Kirim pertanyaan yang ada di basis pengetahuan Anda dan pastikan jawabannya memuat sitasi.
Minta bantuan manusia, lalu pastikan thread muncul di bawah Dieskalasi di inbox.
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.
<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.
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.
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:
script-src 'self' https://tanggapi.my.id;
connect-src 'self' https://tanggapi.my.id;
Pemecahan Masalah
| Gejala | Pemeriksaan |
|---|---|
| Launcher tidak muncul | Pastikan tag skrip berada sebelum </body>, ID publik sudah benar, dan tab network browser menunjukkan widget.js mengembalikan 200. |
| Launcher muncul dua kali | Hapus cuplikan duplikat dari layout, template, atau tag manager. Render komponen React sekali saja di root aplikasi. |
| Berfungsi lokal, tidak di produksi | Tambahkan domain produksi ke dalam daftar domain yang diizinkan. Periksa CSP dan pemblokir skrip. |
| Widget termuat tetapi tidak dapat membalas | Periksa 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
Di sidebar dasbor, pilih API & Developer.
Klik <b>Buat API key</b>, beri nama, dan secara opsional pilih masa berlaku (30 hari, 90 hari, atau 1 tahun).
Key mentah hanya ditampilkan tepat sekali. Segera simpan di secret manager server Anda. Tanggap hanya menyimpan hash SHA-256.
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
| Scope | Mengizinkan |
|---|---|
| chat:write | Jawaban basis pengetahuan stateless dengan POST /v1/integration/ai/answer. |
| conversations:read | Membaca detail percakapan dan riwayat pesan berhalaman. |
| conversations:write | Membuat 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 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.
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"
}'
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?"}'
curl "https://tanggapi.my.id/v1/integration/conversations/CONVERSATION_ID/messages?limit=20" \
-H "Authorization: Bearer tgp_live_YOUR_KEY"
Endpoint
| Metode & path | Tujuan | Scope |
|---|---|---|
| POST /v1/integration/ai/answer | Tanyakan ke basis pengetahuan tanpa membuat percakapan. | chat:write |
| POST /v1/integration/conversations | Buat atau gunakan kembali kontak dan buka percakapan. | conversations:write |
| GET /v1/integration/conversations/:id | Membaca status, kontak, pengguna eksternal, dan timestamp. | conversations:read |
| GET /v1/integration/conversations/:id/messages | Membaca pesan dengan pagination kursor (1–100 per halaman). | conversations:read |
| POST /v1/integration/conversations/:id/messages | Kirim pesan dan kembalikan jawaban AI, atau lakukan streaming dengan ?stream=true. | conversations:write |
| POST /v1/integration/conversations/:id/resolve | Tutup percakapan. | conversations:write |
| POST /v1/integration/conversations/:id/escalate | Pindahkan percakapan ke antrean manusia. | conversations:write |
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.
{
"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.
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.
| Event | Dipicu saat |
|---|---|
| conversation.created | Percakapan widget atau API dibuat. |
| message.created | Pesan pengguna, asisten, atau manusia disimpan. |
| conversation.escalated | Thread dialihkan ke antrean manusia. |
| conversation.resolved | Thread 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.
| Paket | Permintaan per menit |
|---|---|
| Pro | 60 |
| Enterprise | 240 |
| Status | Arti |
|---|---|
| 400 | JSON tidak valid atau kesalahan validasi. Periksa body permintaan dan format kursor. |
| 401 | API key tidak ada, dicabut, atau kedaluwarsa. |
| 402 | Kendala paket atau kuota: Akses API memerlukan Pro, atau kuota pesan AI telah habis. |
| 403 | Key tidak memiliki scope yang diperlukan. |
| 404 | Percakapan tidak ditemukan di workspace ini. |
| 409 | Percakapan telah selesai, ketidakcocokan body idempotensi, atau permintaan dengan key yang sama masih diproses. |
| 429 | Batas rate limit terlampaui. Coba lagi setelah jumlah detik dalam Retry-After. |
| 503 | Penyedia AI belum dikonfigurasi atau sedang tidak tersedia. |
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.