# Tars Docs

- [Welcome to Tars](https://hellotars.com/docs/index.md): Build, deploy, and operate AI and human-agent conversations from one platform.
- [What is Tars?](https://hellotars.com/docs/get-started/what-is-tars.md): The Tars mental model: one organization that owns agents, deployments, channels, and conversations.
- [Quickstart: build your first agent](https://hellotars.com/docs/get-started/quickstart.md): Build, test, publish, and share your first agent in about 15 minutes, without writing code.
- [Organizations and members](https://hellotars.com/docs/get-started/organizations-and-members.md): How organizations, members, roles, seats, and plans fit together in Tars.
- [Agents, flows, and deployments](https://hellotars.com/docs/get-started/agents-flows-deployments.md): The Tars mental model: agent, flow, deployment, and channel.
- [Plans overview](https://hellotars.com/docs/get-started/plans-overview.md): Compare the Free, Premium, and Enterprise plans, and see exactly which capability unlocks on each one.
- [Invite your team](https://hellotars.com/docs/get-started/invite-your-team.md): Invite members to your organization, assign their roles, and grant live-chat seats.
- [Create an agent](https://hellotars.com/docs/guides/building/create-an-agent.md): Create a new agent from the library, fill in the create dialog, and duplicate an existing agent from its draft or published version.
- [Builder basics](https://hellotars.com/docs/guides/building/builder-basics.md): Find your way around the builder, add gambits from the palette, and connect them into a flow.
- [Gambit mastery](https://hellotars.com/docs/guides/building/gambits/overview.md): Every gambit type you can place in the builder, what it does, and where its settings live.
- [AI Agent gambit](https://hellotars.com/docs/guides/building/gambits/ai-agent.md): Every section of the AI Agent gambit editor, from Instructions to Exit Routes.
- [Text gambit](https://hellotars.com/docs/guides/building/gambits/text.md): Collect a typed answer, and constrain it to a format such as email or phone.
- [Button gambit](https://hellotars.com/docs/guides/building/gambits/button.md): Offer a set of choices, capture the one the end user picks, and branch on it.
- [Card gambit](https://hellotars.com/docs/guides/building/gambits/card.md): Offer rich tiles with an image, a title, and their own buttons, and branch on the tile the end user picks.
- [Star Rating gambit](https://hellotars.com/docs/guides/building/gambits/star-rating.md): Capture a rating on a row of stars, and branch on the score.
- [Date & Time gambit](https://hellotars.com/docs/guides/building/gambits/date-time.md): Capture a date, a time, or both from an inline picker, with bounds you set.
- [Media Upload gambit](https://hellotars.com/docs/guides/building/gambits/media-upload.md): Accept files from the end user, with the types and size cap you allow.
- [Geo Location gambit](https://hellotars.com/docs/guides/building/gambits/geo-location.md): Capture the end user's device location, optionally converted to an address.
- [Auto Suggestion gambit](https://hellotars.com/docs/guides/building/gambits/auto-suggestion.md): Offer typeahead suggestions from a built-in list or your own, and capture the pick.
- [Start and End gambits](https://hellotars.com/docs/guides/building/gambits/start-and-end.md): The two gambits that bound every flow, and what each one means at run time.
- [No Input gambit](https://hellotars.com/docs/guides/building/gambits/no-input.md): Send messages and move on without waiting for the end user to answer.
- [Redirect gambit](https://hellotars.com/docs/guides/building/gambits/redirect.md): Send the end user to an external address, after a countdown or through a link that opens a new tab.
- [Language gambit](https://hellotars.com/docs/guides/building/gambits/language.md): Let the end user choose the conversation language, and set the locale for everything after.
- [API Call gambit](https://hellotars.com/docs/guides/building/gambits/api-call.md): Call an HTTP endpoint mid-conversation and use the response in later gambits.
- [Custom Code gambit](https://hellotars.com/docs/guides/building/gambits/custom-code.md): Run JavaScript against the flow's variables and write results back.
- [Channel gambit](https://hellotars.com/docs/guides/building/gambits/channel.md): Send a message out over a connected channel, and branch on whether it lands.
- [Trigger gambit](https://hellotars.com/docs/guides/building/gambits/trigger.md): Start a flow from an external event, with the payload available as variables.
- [Live Chat gambit](https://hellotars.com/docs/guides/building/gambits/live-chat.md): Escalate the conversation to a human agent, and branch on what happens next.
- [Use variables](https://hellotars.com/docs/guides/building/variables.md): Type @ in any builder field to insert captured values that resolve when the conversation runs.
- [Flow control and branching](https://hellotars.com/docs/guides/building/flow-control-and-branching.md): Route conversations down different branches with conditions, edge labels, and AI Agent exit routes.
- [Build a multi-language agent](https://hellotars.com/docs/guides/building/languages.md): Add languages in Configure, translate the flow per gambit, and override system messages per language.
- [Test your agent](https://hellotars.com/docs/guides/building/testing-your-agent.md): Run your flow in Test Mode, override variables mid-run, read the Event Log, fix validation problems, and set debug visibility.
- [Drafts and publishing](https://hellotars.com/docs/guides/building/drafts-and-publishing.md): How drafts, publishing, version history, rollback, and version pinning keep edits away from live conversations.
- [Guardrails and safety](https://hellotars.com/docs/guides/building/guardrails-and-safety.md): The safety layers around every AI Agent gambit, and where you add your own guardrail instructions.
- [Built-in AI capabilities](https://hellotars.com/docs/guides/building/built-in-ai-capabilities.md): Where to enable web search, code execution, file generation, data extraction, file reading, and interface components for an AI Agent gambit.
- [Set up agent email notifications](https://hellotars.com/docs/guides/building/agent-email-notifications.md): Email a fixed list of addresses when one agent gets a new conversation, an assignment, or an achieved goal.
- [Create a knowledge base](https://hellotars.com/docs/guides/knowledge/create-a-knowledge-base.md): Create a knowledge base and add its first sources from a website import or uploaded files.
- [Import a website](https://hellotars.com/docs/guides/knowledge/import-a-website.md): Import selected website pages into a knowledge base, choose fetch settings, and keep the content fresh on a schedule.
- [Manage documents](https://hellotars.com/docs/guides/knowledge/manage-documents.md): Preview, edit, and delete the documents and media in a knowledge base, then apply the changes with a reindex.
- [Retrievers explained](https://hellotars.com/docs/guides/knowledge/retrievers-explained.md): How retrievers search a knowledge base, from meaning and keyword strategies to query transforms, parent context, and re-ranking.
- [Configure a retriever](https://hellotars.com/docs/guides/knowledge/configure-a-retriever.md): Create, test, and promote a retriever on a knowledge base.
- [Attach knowledge to an agent](https://hellotars.com/docs/guides/knowledge/attach-knowledge-to-an-agent.md): Connect a Knowledge Retrieval gambit to an AI Agent gambit so the agent answers from your knowledge bases.
- [Connect a toolkit](https://hellotars.com/docs/guides/tools/connect-a-toolkit.md): Connect a third-party toolkit with OAuth or an API key, then monitor and repair its connection health.
- [Enable and use actions](https://hellotars.com/docs/guides/tools/enable-and-use-actions.md): Enable toolkit actions on the toolkit detail page, then call them from a tool gambit in the builder in agent mode or Workflow Mode.
- [CodeKit overview](https://hellotars.com/docs/guides/tools/codekit-overview.md): What CodeKit is and how custom actions become tools that every agent in your organization can call.
- [Write a custom action](https://hellotars.com/docs/guides/tools/write-a-custom-action.md): Create a CodeKit toolkit, write and deploy a TypeScript action, and give it to an AI Agent gambit as a tool.
- [Deployments explained](https://hellotars.com/docs/guides/deploy/deployments-explained.md): What a deployment is, which surfaces the Distribute page offers, and how those surfaces relate to the published version and to channels.
- [Share your agent link](https://hellotars.com/docs/guides/deploy/share-your-agent-link.md): Copy the link to your published agent, share it, download its QR code, and serve the same full-page agent from your own subdomain.
- [Embed the widget](https://hellotars.com/docs/guides/deploy/embed-the-widget.md): Copy the embed snippet from the Widget Embed view, paste it into your website, and confirm the launcher appears.
- [Design the widget](https://hellotars.com/docs/guides/deploy/design-the-widget.md): Style the conversation window on the Agent tab, style the launcher on the Launcher tab, and save both from one page.
- [Add your agent to a mobile app](https://hellotars.com/docs/guides/deploy/mobile-apps.md): Turn on the mobile bridge, hand the platform snippet to your mobile developer, and set bridge events on gambits.
- [Channels overview](https://hellotars.com/docs/guides/channels/channels-overview.md): What a channel is in Tars, where WhatsApp numbers live in the dashboard, and how a connected number becomes part of an agent's deployment.
- [Connect WhatsApp](https://hellotars.com/docs/guides/channels/connect-whatsapp.md): Connect WhatsApp numbers through Meta or 360dialog, bring them into Tars, and assign each number to an agent.
- [Manage WhatsApp templates](https://hellotars.com/docs/guides/channels/whatsapp-templates.md): Create, submit, edit, and delete WhatsApp message templates, and read their Meta approval status in the Templates tab.
- [Watch conversations](https://hellotars.com/docs/guides/activity/watch-conversations.md): Open an agent's Activity tab to watch conversations as they happen and read every message, event, tool call, and captured variable.
- [Export conversations](https://hellotars.com/docs/guides/activity/export-conversations.md): Export an agent's conversations to CSV or JSON from the Export data dialog, then download the file from the Tasks panel.
- [What end users see](https://hellotars.com/docs/guides/activity/end-user-experience.md): How a conversation looks and behaves for the end user in the web widget, the full-page agent link, and WhatsApp.
- [Live-chat overview and seats](https://hellotars.com/docs/guides/live-chat/overview-and-seats.md): How a Live Chat gambit hands a conversation to a human agent, what the Conversations area contains, and who needs a seat to reply.
- [Work the inbox](https://hellotars.com/docs/guides/live-chat/work-the-inbox.md): Find the conversations that need you with views, tabs, filters, and search, then pick them up and act on them one at a time or in bulk.
- [Use the Agent Workspace](https://hellotars.com/docs/guides/live-chat/agent-workspace.md): Reply from the composer, add private notes and mentions, insert canned responses, set your send hotkey and signature, and share transcripts.
- [Set up inboxes](https://hellotars.com/docs/guides/live-chat/set-up-inboxes.md): Configure an inbox's identity, members, routing, working hours, and what end users see, plus the settings every inbox shares.
- [Assignment and availability](https://hellotars.com/docs/guides/live-chat/assignment-and-availability.md): Set your availability, understand how conversations reach human agents, handle the unassigned queue, and reassign work when needed.
- [Live chat notifications](https://hellotars.com/docs/guides/live-chat/notifications.md): Read your notification inbox, enable browser push, tune sound alerts, and pick email or push per event.
- [Collect CSAT ratings](https://hellotars.com/docs/guides/live-chat/csat.md): Turn on the CSAT survey for an inbox, learn what end users see, and find the ratings in the inbox and in analytics.
- [Use Copilot](https://hellotars.com/docs/guides/live-chat/copilot.md): Rewrite drafts in the composer, ask the Copilot panel about the conversation, and insert a suggested reply.
- [End user profiles](https://hellotars.com/docs/guides/end-users/profiles.md): How Tars keeps one persistent, organization-wide profile for each end user across conversations, channels, and campaigns.
- [Verify end user identity](https://hellotars.com/docs/guides/end-users/verify-identity.md): Configure signed identity with an organization signing key, use the OTP fallback, and understand how profiles merge.
- [Organize and moderate end users](https://hellotars.com/docs/guides/end-users/organize-and-moderate.md): Apply tags, labels, notes, and custom fields to profiles, and block end users when moderation is needed.
- [Import and export end users](https://hellotars.com/docs/guides/end-users/import-and-export.md): Add a profile from the Add user modal, import a CSV through upload, mapping, and confirm, and export the directory.
- [Build end user segments](https://hellotars.com/docs/guides/end-users/segments.md): Group end users into dynamic or static segments, preview the match before saving, and reuse segments in campaigns.
- [End user consent](https://hellotars.com/docs/guides/end-users/consent.md): How Tars records consent per channel, updates it from STOP and START replies, and enforces it before campaigns send.
- [Campaigns overview](https://hellotars.com/docs/guides/campaigns/campaigns-overview.md): What Tars campaigns are, the two campaign modes, and what your organization needs before it can send.
- [Create a campaign](https://hellotars.com/docs/guides/campaigns/create-a-campaign.md): Build a WhatsApp campaign, review its audience and cost, then send it now or schedule it.
- [Handle campaign replies](https://hellotars.com/docs/guides/campaigns/handle-replies.md): Route campaign replies into an agent flow, use campaign data in the conversation, and work inside the reply window.
- [Run webhook campaigns](https://hellotars.com/docs/guides/campaigns/webhook-campaigns.md): Set up a standing API-triggered campaign, validate its contract, and manage its lifecycle and keys.
- [Read campaign reports](https://hellotars.com/docs/guides/campaigns/campaign-reports.md): Follow a campaign's funnel, daily trends, recipient-level results, exports, and reply attribution.
- [Fund your campaign wallet](https://hellotars.com/docs/guides/campaigns/campaign-wallet.md): Add campaign funds, understand the reserve, settle, and refund lifecycle, and read wallet statement entries.
- [Analytics overview](https://hellotars.com/docs/guides/analytics/analytics-overview.md): What the Analytics section covers, how the scope bar and tabs fit together, and how every number leads back to real conversations.
- [Read the Overview tab](https://hellotars.com/docs/guides/analytics/overview-tab.md): Read every card on the analytics Overview tab, from the Trend card to the Channel performance table, and know what each number means.
- [Define and track goals](https://hellotars.com/docs/guides/analytics/goals.md): Create goals in the agent's Configure screen, pick a primary goal per deployment, and read goal conversion on the Goals tab.
- [Find issues with Improve](https://hellotars.com/docs/guides/analytics/improve.md): Read the ranked issues on the Improve tab, open the detailed diagnostics, and trace each issue to its conversations.
- [Review team performance](https://hellotars.com/docs/guides/analytics/team-performance.md): Read the Team tab to measure pickup latency, AI reply latency, per-agent workload, and CSAT for your live chat team.
- [Build reports in Explore](https://hellotars.com/docs/guides/analytics/explore.md): Combine a measure with a breakdown in the Explore builder, drill into any point, and save the view for your team.
- [Roles and permissions](https://hellotars.com/docs/guides/billing/roles-and-permissions.md): The five organization roles, the capability matrix on the Roles & access page, and how a live-chat seat differs from a role.
- [Upgrade your plan](https://hellotars.com/docs/guides/billing/plans-and-upgrading.md): Move from Free to Premium from Settings > Billing, choose a conversation volume and billing period, and complete checkout.
- [Conversation usage](https://hellotars.com/docs/guides/billing/conversation-usage.md): What counts as a billable conversation, how the Billing page shows your allowance and credits, and what happens when the allowance runs out.
- [Manage live-chat seats](https://hellotars.com/docs/guides/billing/live-chat-seats.md): Buy live-chat seats from the billing page and assign them to members from the Livechat seats tab.
- [Resolve invoices and payment issues](https://hellotars.com/docs/guides/billing/invoices-and-payment-issues.md): Read your billing history, update the card on file, recover from a failed payment, and reach your account manager.
- [Organization lifecycle](https://hellotars.com/docs/guides/billing/organization-lifecycle.md): How an organization is created, handed to another admin, and deleted, and what happens to agents, conversations, and billing during the grace period.
- [Search and export the audit log](https://hellotars.com/docs/guides/security/audit-log.md): Filter audit events, read the event drawer, export CSV or JSON, and verify the tamper-evident chain.
- [Stream audit events to your SIEM](https://hellotars.com/docs/guides/security/siem-streaming.md): Connect Splunk HEC, Amazon S3, or a signed HTTPS webhook from the SIEM streaming tab, then monitor, replay, and rewind delivery.
- [Bring your own model key](https://hellotars.com/docs/guides/security/bring-your-own-model-key.md): Add, replace, or revoke an OpenRouter key on the Model Provider tab so your agents' model calls run through your own OpenRouter account.
- [Data retention](https://hellotars.com/docs/guides/security/data-retention.md): How long Tars keeps Activity timelines, traces, and audit events on each plan, where the dashboard shows the window, and what happens after it ends.
- [Erasure and legal holds](https://hellotars.com/docs/guides/security/erasure-and-legal-holds.md): How Tars support erases an end user's personal data on request, what a legal hold protects, and how both appear in your audit log.
- [How Tars support accesses your organization](https://hellotars.com/docs/guides/security/how-tars-support-accesses-your-org.md): Support access is a time-limited, audited membership grant that shows in your members list and your audit log.
- [How Tars protects files, data, and identity](https://hellotars.com/docs/guides/security/data-protection.md): Signed download links, redaction of tool logs, encrypted secrets, signed identity, and sanitized chat content, as a member sees them in the dashboard.
- [Personal data protection](https://hellotars.com/docs/guides/security/personal-data-protection.md): How the Privacy settings detect personal data in end user conversations, what Redact and Mask store, and who can see the original values.
- [Developer overview](https://hellotars.com/docs/developer/index.md): APIs, webhook triggers, embeds, and the mobile bridge for developers building on Tars.
- [API authentication](https://hellotars.com/docs/developer/authentication.md): Create, scope, and revoke API keys, and authenticate Tars API requests with Bearer tokens.
- [Start conversations API](https://hellotars.com/docs/developer/api/start-conversations.md): Start an agent conversation at a trigger gambit with the POST /api/triggers endpoint.
- [Send channel messages API](https://hellotars.com/docs/developer/api/send-channel-messages.md): Send an outbound message on a connected channel with the POST /api/channels/send endpoint.
- [End users API](https://hellotars.com/docs/developer/api/end-users.md): Manage end-user records over the /api/endusers endpoints, from single reads and writes to batch import.
- [List end users](https://hellotars.com/docs/developer/api/end-users/list.md): Page through the end-user records in your organization with cursor pagination and filters.
- [Create an end user](https://hellotars.com/docs/developer/api/end-users/create.md): Create a single end-user record. Duplicate emails or phones return 409 DUPLICATE_ENDUSER.
- [Batch-create end users](https://hellotars.com/docs/developer/api/end-users/batch.md): Create up to 50 end-user records in one request and get per-row results with skipped duplicates.
- [Get an end user](https://hellotars.com/docs/developer/api/end-users/get.md): Fetch a single end-user record by its ID, or a 404 NOT_FOUND when no record matches.
- [Update an end user](https://hellotars.com/docs/developer/api/end-users/update.md): Patch name, email, phone, tags, or channel identifiers on one end-user record.
- [Delete an end user](https://hellotars.com/docs/developer/api/end-users/delete.md): Soft-delete an end-user record by ID, cascading to its related data as an audited event.
- [Webhook campaigns API](https://hellotars.com/docs/developer/api/webhook-campaigns.md): Overview of the webhook campaign send surface, with dedicated keys, contract locking, lifecycle rules, and the full error catalog.
- [Send a campaign message](https://hellotars.com/docs/developer/api/webhook-campaigns/send.md): Send one webhook campaign message to a recipient, charged per call against the campaign wallet.
- [Validate a campaign call](https://hellotars.com/docs/developer/api/webhook-campaigns/validate.md): Dry-run a webhook campaign send with full checks and a pricing quote, without delivery or charge.
- [Embed script and TarsConfig](https://hellotars.com/docs/developer/embed/script-and-config.md): The embed.js script tag, the window.TarsConfig object, locale resolution, and page-context passing.
- [Widget JS API](https://hellotars.com/docs/developer/embed/widget-js-api.md): The window.TarsWidget methods for opening, closing, badging, and identifying from the host page.
- [Host page events](https://hellotars.com/docs/developer/embed/host-page-events.md): The tars:bridge CustomEvent, widget-driven host navigation, and the out-of-iframe image lightbox.
- [Iframe embed method](https://hellotars.com/docs/developer/embed/iframe-method.md): Embed the agent as a direct iframe, and what the iframe method cannot do compared to embed.js.
- [Identity signing](https://hellotars.com/docs/developer/embed/identity-signing.md): Sign end-user identity server-side with HMAC-SHA256 so the widget can trust who is chatting.
- [The WebView bridge](https://hellotars.com/docs/developer/mobile/webview-bridge.md): How native mobile apps embed a Tars agent through a WebView and a postMessage protocol.
- [React Native integration](https://hellotars.com/docs/developer/mobile/react-native.md): Embed a Tars agent in a React Native app with react-native-webview and the bridge protocol.
- [Swift integration](https://hellotars.com/docs/developer/mobile/swift.md): Embed a Tars agent in an iOS app with WKWebView and a WKScriptMessageHandler named tarsbridge.
- [Kotlin integration](https://hellotars.com/docs/developer/mobile/kotlin.md): Embed a Tars agent in an Android app with WebView and a JavascriptInterface named AndroidBridge.
- [Bridge events reference](https://hellotars.com/docs/developer/mobile/bridge-events.md): Every message in the mobile bridge protocol, per-gambit bridge events, interpolation, and chrome control.
- [Changelog](https://hellotars.com/docs/changelog/index.md): Product updates and improvements across the Tars platform.

## OpenAPI Specs

- [openapi](/docs/api-reference/openapi.json)