Documentation

Build support that feels native to your product

Learn how conversations work, how to customize and embed the Tanggap.ai widget, and how to connect a native app or backend with the integration API.

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.

Widget

The fastest path for a website. Drop one script tag on your site and the launcher appears bottom-right.

Dashboard

Your team inbox. Read conversations, reply as a human, hand back to AI, resolve threads, and check usage.

Integration API

Use an API key to create conversations, send messages, stream answers, and receive signed webhooks from your own app.

Knowledge base

Upload PDF, TXT, or Markdown files. Tanggap chunks and embeds them once, then cites the relevant sources in answers.

One quota. Widget and API answers both count toward the same monthly AI message quota. BYOK usage is not counted against the hosted quota.

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.

Contact

The person behind the thread. Widget contacts use a browser session; API contacts use your stable externalUserId, with optional name, email, and metadata.

Conversation

The thread itself: channel, status, last message time, and a link to the contact.

Messages

User, assistant, human, and system/tool turns. Assistant messages can carry citations from the knowledge base.

Handoff

When the AI cannot help, the thread can be escalated and answered by a teammate from the inbox.

Status & lifecycle

StatusWhat it meansWho replies
aiAI is handling the thread. New widget and API conversations start here.Tanggap.ai using your knowledge base.
humanA teammate owns the thread. AI stays quiet.Your team from the Inbox.
escalatedA handoff was requested and the thread is waiting for a teammate.Your team; replying takes ownership.
resolvedThe 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

Open Conversations

The default filter is Unresolved, so AI, human, and escalated threads stay visible. Resolved threads are one filter away.

Read the thread

Citations show which knowledge-base documents supported each AI answer. Use search to find a contact or message.

Reply or take over

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.

Resolve or hand back

Mark the thread resolved when finished. Hand Back to AI reopens it or returns it to automatic replies.

Inbox count. The sidebar badge and the Conversations nav count unresolved threads only. A thread disappears from the badge once it is resolved.

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

PlanDocumentsMax file size
Free / Starter11 MB
Pro102 MB
EnterpriseUnlimited (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

Open the preview

Use Preview widget from the empty inbox or Widget Customization to open the live preview for your workspace.

Ask a real question

Send a question that exists in your knowledge base and confirm the answer includes a citation.

Test the handoff

Ask for a human, then check that the thread appears under Escalated in the inbox.

Check usage

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.

HTML
<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.

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

Add this to your root layout so the widget loads after hydration on every route.

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. 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:

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

Troubleshooting

SymptomCheck
No launcher appearsConfirm the script tag is before </body>, the public ID is correct, and the browser network tab shows widget.js returning 200.
Launcher appears twiceRemove duplicate snippets from layouts, templates, or tag managers. Render the React component once at the app root.
Works locally, not in productionAdd the production domain under allowed domains. Check CSP and any script blocker.
Widget loads but cannot replyCheck 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

Open API & Developers

In the dashboard sidebar, choose API & Developers.

Create a key

Click Create API key, give it a name, and optionally choose an expiry (30 days, 90 days, or 1 year).

Copy it once

The raw key is shown exactly once. Store it in your server's secret manager immediately. Tanggap only stores a SHA-256 hash.

Rotate or revoke

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

ScopeAllows
chat:writeStateless knowledge-base answers with POST /v1/integration/ai/answer.
conversations:readRead conversation details and paginated message history.
conversations:writeCreate 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
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.

1 · Create a 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"
  }'
2 · Send a message
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 · Read history
curl "https://tanggapi.my.id/v1/integration/conversations/CONVERSATION_ID/messages?limit=20" \
  -H "Authorization: Bearer tgp_live_YOUR_KEY"

Endpoints

Method & pathPurposeScope
POST /v1/integration/ai/answerAsk the knowledge base without creating a conversation.chat:write
POST /v1/integration/conversationsCreate or reuse a contact and open a conversation.conversations:write
GET /v1/integration/conversations/:idRead status, contact, external user, and timestamps.conversations:read
GET /v1/integration/conversations/:id/messagesRead messages with cursor pagination (1–100 per page).conversations:read
POST /v1/integration/conversations/:id/messagesSend a message and return the AI answer, or stream it with ?stream=true.conversations:write
POST /v1/integration/conversations/:id/resolveClose the conversation.conversations:write
POST /v1/integration/conversations/:id/escalateMove the conversation to the human queue.conversations:write
Conversation ownership. A conversation created by one workspace is invisible to another API key. Cross-workspace access returns 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.

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

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.

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?"}'

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.

EventFires when
conversation.createdA widget or API conversation is created.
message.createdA user, assistant, or human message is stored.
conversation.escalatedA thread is handed off to the human queue.
conversation.resolvedA 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.

PlanRequests per minute
Pro60
Enterprise240
StatusMeaning
400Invalid JSON or validation error. Check the request body and cursor format.
401Missing, revoked, or expired API key.
402Plan or quota problem: API access requires Pro, or the AI message quota is exhausted.
403The key does not have the required scope.
404Conversation not found in this workspace.
409Conversation resolved, idempotency body mismatch, or a request with the same key is still pending.
429Rate limit exceeded. Retry after the number of seconds in Retry-After.
503The AI provider is not configured or temporarily unavailable.
References. The OpenAPI 3.1 spec lives at 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.