Start here
Overview
Tanggap.ai is one AI support engine with three surfaces: an embeddable website widget, a dashboard inbox for your team, and a server-to-server API for native apps and backends.
All three surfaces share the same workspace, knowledge base, contacts, conversations, and AI message quota. A visitor can start in the widget, continue in the inbox, and be followed up through your own app without losing context.
The fastest path for a website. Drop one script tag on your site and the launcher appears bottom-right.
Your team inbox. Read conversations, reply as a human, hand back to AI, resolve threads, and check usage.
Use an API key to create conversations, send messages, stream answers, and receive signed webhooks from your own app.
Upload PDF, TXT, or Markdown files. Tanggap chunks and embeds them once, then cites the relevant sources in answers.
Conversations
What is a conversation?
A conversation is one continuous support thread between an end user and your workspace. It holds the messages, the current owner (AI or a human), and the contact it belongs to.
Conversations start automatically when a visitor sends the first widget message, or when your backend calls POST /v1/integration/conversations. Contacts are deduplicated: a returning widget visitor reuses the browser session, and an API caller reuses the same externalUserId.
The person behind the thread. Widget contacts use a browser session; API contacts use your stable externalUserId, with optional name, email, and metadata.
The thread itself: channel, status, last message time, and a link to the contact.
User, assistant, human, and system/tool turns. Assistant messages can carry citations from the knowledge base.
When the AI cannot help, the thread can be escalated and answered by a teammate from the inbox.
Status & lifecycle
| Status | What it means | Who replies |
|---|---|---|
| ai | AI is handling the thread. New widget and API conversations start here. | Tanggap.ai using your knowledge base. |
| human | A teammate owns the thread. AI stays quiet. | Your team from the Inbox. |
| escalated | A handoff was requested and the thread is waiting for a teammate. | Your team; replying takes ownership. |
| resolved | The thread is closed. Reopen it with Hand Back to AI if the customer returns. | Nobody until reopened. The API returns 409 for new messages on a resolved thread. |
Channels tell you where the thread came from: widget for the website chatbox, api for server-to-server integrations, and voice for calls created by the voice assistant. Status and channel appear on every conversation row in the dashboard.
Inbox workflow
The default filter is Unresolved, so AI, human, and escalated threads stay visible. Resolved threads are one filter away.
Citations show which knowledge-base documents supported each AI answer. Use search to find a contact or message.
Send a human reply to pause the AI and move the thread to Human Agent. Use Enhance with AI to draft a reply without handing control back.
Mark the thread resolved when finished. Hand Back to AI reopens it or returns it to automatic replies.
Using the widget
Customize the widget
The widget is the website chatbox your customers see. Customize it in Widget Customization, then copy the embed script from Setup & Integrations.
Changes are saved per workspace. The live widget preview on the right side of the customization page updates as you edit, so you can check the result before publishing.
Branding & knowledge
- Launcher — position, button label, and optional custom logo. Custom logos and hiding the Tanggap.ai branding are Pro features.
- Appearance — accent color, header title, greeting message, and suggested questions.
- Knowledge base — upload PDF, TXT, or Markdown files from Knowledge Base. Each file is parsed, chunked, and embedded for retrieval.
- Voice — voice calling is available on Pro and Enterprise. Managed voice includes 60 minutes/month on Pro and 300 minutes/month on Enterprise.
Knowledge base limits
| Plan | Documents | Max file size |
|---|---|---|
| Free / Starter | 1 | 1 MB |
| Pro | 10 | 2 MB |
| Enterprise | Unlimited (fair use) | 2 MB |
Supported formats are PDF, TXT, and MD. Uploading beyond the plan limit or above the size cap opens the Pro upgrade paywall instead of accepting the file.
Test before launch
Use Preview widget from the empty inbox or Widget Customization to open the live preview for your workspace.
Send a question that exists in your knowledge base and confirm the answer includes a citation.
Ask for a human, then check that the thread appears under Escalated in the inbox.
Every hosted AI answer increments the AI message meter in Plans & Billing. BYOK answers do not.
Widget integration
Install the widget
Installation is one script tag. The script reads your organization public ID, loads the widget bundle, and renders the launcher in the bottom-right corner.
1. Copy your Organization Public ID
Open Setup & Integrations in the dashboard. Copy the Organization Public ID shown at the top. It looks like org_xxxxxxxxxxxxxxxxxxxx and is safe to expose in client-side HTML — it is not an API key.
2. Add the embed snippet
Place this tag immediately before the closing </body> on every page where the widget should appear.
<script
src="https://tanggapi.my.id/widget.js"
data-organization-id="org_xxxxxxxxxxxxxxxxxxxx"
defer
></script>
React
Render this component once in your app shell. It appends the loader on mount and removes it on 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
Add this to your root layout so the widget loads after hydration on every route.
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. Restrict allowed domains
In Setup & Integrations, add the domains that may embed the widget. Leave the list empty to allow any site during testing; add production domains before launch.
If your site uses a Content Security Policy, allow the widget script origin in script-src and the API origin in connect-src:
script-src 'self' https://tanggapi.my.id;
connect-src 'self' https://tanggapi.my.id;
Troubleshooting
| Symptom | Check |
|---|---|
| No launcher appears | Confirm the script tag is before </body>, the public ID is correct, and the browser network tab shows widget.js returning 200. |
| Launcher appears twice | Remove duplicate snippets from layouts, templates, or tag managers. Render the React component once at the app root. |
| Works locally, not in production | Add the production domain under allowed domains. Check CSP and any script blocker. |
| Widget loads but cannot reply | Check the API origin in connect-src, then confirm the workspace still has AI message quota. |
API keys
API key documentation
The integration API lets your backend or native app create conversations, send messages, stream answers, and receive webhooks. API keys are available on Pro and Enterprise plans.
Create & manage keys
In the dashboard sidebar, choose API & Developers.
Click Create API key, give it a name, and optionally choose an expiry (30 days, 90 days, or 1 year).
The raw key is shown exactly once. Store it in your server's secret manager immediately. Tanggap only stores a SHA-256 hash.
Create a replacement key, deploy it, then revoke the old key. Revocation takes effect immediately.
Keys start with tgp_live_ and are masked in the dashboard as tgp_live_••••••••3f9a. The last-used timestamp and expiry status are shown in the key list.
Scopes
| Scope | Allows |
|---|---|
| chat:write | Stateless knowledge-base answers with POST /v1/integration/ai/answer. |
| conversations:read | Read conversation details and paginated message history. |
| conversations:write | Create conversations, send messages, resolve, and escalate. |
Authentication
Send the key as a Bearer token on every request. Never put an API key in a browser, mobile app bundle, or public repository; call the API from your server or a trusted backend.
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?"}'
Every response includes X-Request-Id. Include it when contacting support so the request can be traced. Rate-limit headers are returned on every integration request.
Quickstart
Create a conversation for one of your end users, then send a message. The API stores both the user turn and the AI answer, so history is available from the same conversation.
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"
Endpoints
| Method & path | Purpose | Scope |
|---|---|---|
| POST /v1/integration/ai/answer | Ask the knowledge base without creating a conversation. | chat:write |
| POST /v1/integration/conversations | Create or reuse a contact and open a conversation. | conversations:write |
| GET /v1/integration/conversations/:id | Read status, contact, external user, and timestamps. | conversations:read |
| GET /v1/integration/conversations/:id/messages | Read messages with cursor pagination (1–100 per page). | conversations:read |
| POST /v1/integration/conversations/:id/messages | Send a message and return the AI answer, or stream it with ?stream=true. | conversations:write |
| POST /v1/integration/conversations/:id/resolve | Close the conversation. | conversations:write |
| POST /v1/integration/conversations/:id/escalate | Move the conversation to the human queue. | conversations:write |
404, not another workspace's data.Messages & streaming
A normal message request returns the answer, citations, whether the knowledge base was used, and both message IDs. If the conversation is escalated or human, the user message is stored without an AI answer. If it is resolved, the API returns 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"
}
For token-by-token delivery, add ?stream=true. The response is Server-Sent Events with four event names: citations, delta, done, and error. The done event carries both message IDs.
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?"}'
Idempotency. Add an Idempotency-Key to JSON message requests so a retry cannot create a duplicate message or double-charge AI usage. Replaying the same key and body returns the original response; a different body returns 409. SSE requests reject the header with 400 because streams cannot be replayed.
Webhooks
Register a public HTTPS endpoint under API & Developers → Webhooks. Tanggap sends signed events through a queue and retries failed deliveries with backoff.
| Event | Fires when |
|---|---|
| conversation.created | A widget or API conversation is created. |
| message.created | A user, assistant, or human message is stored. |
| conversation.escalated | A thread is handed off to the human queue. |
| conversation.resolved | A thread is closed. |
Each delivery includes X-Tanggap-Signature: t=<timestamp>,v1=<hmac>. Compute the HMAC over the timestamp and raw request body with your endpoint's signing secret, and reject stale timestamps. Failed deliveries retry after 60s, 300s, 900s, 1 hour, and 6 hours. Rotate a secret by deleting and re-adding the endpoint.
Limits & errors
Rate limits are applied per API key and reset every minute. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset; a 429 also includes Retry-After.
| Plan | Requests per minute |
|---|---|
| Pro | 60 |
| Enterprise | 240 |
| Status | Meaning |
|---|---|
| 400 | Invalid JSON or validation error. Check the request body and cursor format. |
| 401 | Missing, revoked, or expired API key. |
| 402 | Plan or quota problem: API access requires Pro, or the AI message quota is exhausted. |
| 403 | The key does not have the required scope. |
| 404 | Conversation not found in this workspace. |
| 409 | Conversation resolved, idempotency body mismatch, or a request with the same key is still pending. |
| 429 | Rate limit exceeded. Retry after the number of seconds in Retry-After. |
| 503 | The AI provider is not configured or temporarily unavailable. |
docs/api/openapi.yaml. The TypeScript SDK is @tanggap/sdk with ai.answer, conversations.*, and messages.*. The dashboard quickstart includes curl, TypeScript, React Native, and Flutter tabs.