Chat Agents

Chat Agents are embeddable AI assistants you build once and drop onto any website with a single script tag. Each agent has its own knowledge base, its own tools, its own look, and its own public address — so a visitor can ask it questions, and it can answer using your content and even take actions on your systems.

Agent playground

Configure and test the real visitor experience

Open in TIA

Choose the Playground and configuration tab

Open the agent’s Playground, then use Overview, Display, Voice, and Actions to configure the experience.

Test the visitor experience

Use the live widget preview to check the same conversation experience your visitors will receive.

Overview

A chat agent is a self-contained assistant scoped to your organization. You give it a name and a system prompt, train it on your website and documents, optionally give it HTTP tools to call your APIs, and then embed it. Visitors chat with it in a floating widget; the agent answers from its knowledge base, calls tools when it needs to, and — if you allow it — can hand the conversation to a human or switch to voice.

Everything is managed from Chat Agents in the main navigation. The agent list describes the product directly: "Build AI chat widgets that you embed on any website. Each agent has its own knowledge base, tools, and look."

Why use it

• Answer from your own content — train the agent on your site and docs, and it answers grounded in that material instead of guessing.
• Take real actions — give it HTTP tools so it can look up an order, book a meeting, or query your CRM mid-conversation.
• Embed anywhere — one <script> tag adds the widget to any page; no framework or build step required.
• Escalate to humans — turn on human handoff and the agent transfers tricky conversations to your team's Inbox.
• Talk, don't just type — turn on voice and visitors get a microphone button to speak with the agent in real time.
• Answer the phone — point a phone number from your own Twilio account at the agent and it takes the call.

Core Concepts

Getting Started

Step 1 — Create an agent

1. Open Chat Agents from the main navigation.
2. Click New Agent.
3. Give it a Name (e.g. "Acme Support Bot") and, optionally, a System prompt describing its role.
4. Click Create Agent.

You're taken straight to the agent's editor. Everything you set here — sources, tools, theme, and embed settings — can be changed later. If you leave the system prompt blank, the agent uses a sensible built-in default that answers from its knowledge base and avoids making things up.

Step 2 — Train it on your content

Open the Sources tab and add at least one knowledge source (see Knowledge sources). The agent answers best when it has your real content to draw from.

Step 3 — Configure and publish

Open the Settings tab to set the welcome message and appearance, then enable public embed and add your site's origin (see Settings and Embedding).

Step 4 — Embed it

Copy the embed snippet from Settings and paste it into your site. Done.

The agent editor

Each agent opens to a tabbed editor with a Try now button in the top-right (it's enabled once the agent is public). The tabs are:

Knowledge sources

The Sources tab is the agent's knowledge base. Sources are crawled, chunked, and embedded so the agent can retrieve the most relevant passages when answering. Four source types are available:

• Website URL — fetches the page, strips navigation and boilerplate, and discovers the rest of the site. See below.
• Document / file — PDF, DOCX, TXT, Markdown, CSV and HTML uploads.
• Plain text — paste content directly (policies, FAQs, product details).
• Q&A pairs — hand-written answers for questions that must be word-perfect.

To add one, click Add source, choose the type, give it a Name, and provide the URL, file, or text.

How a website source finds the rest of your site

Pointing at one page usually pulls in the whole site. Discovery runs in this order:

1. Sitemap — robots.txt Sitemap: declarations first, then the conventional paths (/sitemap.xml, /sitemap_index.xml, and their .gz variants). Sitemap indexes and nested sitemaps are followed.
2. Link following — if no usable sitemap exists, we crawl links from the page you gave us, staying on the same origin.

robots.txt is respected throughout: Disallow rules are honoured, and a Crawl-delay makes the crawl serial at the interval you asked for. The one page you pasted is always fetched, since that is a direct instruction rather than speculative crawling.

Crawl options

Under Crawl options in the add-source dialog:

Paths match as prefixes and support * as a wildcard, so /blog covers /blog/post-1, and /*/draft matches a draft under any section.

Full content indexing vs live pages

This is the one choice worth understanding, because it trades storage against precision.

Off (default). Each discovered page is stored as a small record carrying its title, meta description, and URL. When a question matches one, the page is fetched live at answer time. Costs almost nothing against your plan's training-content allowance, and answers are never stale — if you edit a page, the next answer reflects it. Right for large catalogs.

On. Every discovered page is fetched, chunked, and embedded up front. More precise, and it keeps working if the page is temporarily down — but each page consumes your training-content allowance. Right for a few hundred documentation or policy pages, where accuracy matters more than breadth.

You can mix both: one source for your docs with full indexing on, another for your catalog with it off.

Source status

Each source card shows what it points at, its status, and live document/chunk counts. The panel refreshes automatically while anything is still ingesting.

Deleting a source removes it along with all of its chunks.

Note: URLs that point directly at a PDF are not ingested as website sources — upload the file instead.

Tools

The Tools tab lets the agent do things, not just answer. A tool is an HTTP endpoint you define; the AI reads each tool's description to decide when to call it — "Tools let the AI take action — book meetings, look up orders, query your CRM, etc."

Click New tool to open the editor. A tool has:

You can enable/disable each tool with a switch and Dry-run a saved tool from the editor to see the resolved request and a sample response before the AI ever uses it.

How values are filled in

• {{params.x}} is replaced with the argument the AI provides for parameter x. Required parameters (per your input schema) must be present.
• {{secret:NAME}} is replaced at execution time with the decrypted value of the matching secret — the secret value itself is never exposed to the AI or the browser.

Safety

Tool calls are hardened against abuse: only http/https URLs are allowed, requests to private/internal/metadata IP addresses are blocked, redirects are limited and re-validated, responses are size-capped, and each tool is restricted to its allowed domains. Within a single reply the agent can chain a limited number of tool calls before it must answer.

Secrets

The Secrets tab holds credentials your tools need — most often API keys. Secrets are org-scoped (shared across all your agents and tools) and encrypted with org-derived keys; plaintext is only ever available at the moment a tool executes.

To add one, click New secret, give it an UPPER_SNAKE_CASE name (e.g. STRIPE_API_KEY) and a value. The value "will be encrypted immediately and never shown again" — only a masked preview is displayed afterward.

Reference a secret in any tool template as {{secret:NAME}}. Deleting a secret that a tool still uses will cause that tool to fail, so update your tools first.

Settings

The Settings tab controls behavior, conversation copy, and how the agent is published.

Agent

• Name — internal label.
• System prompt — the agent's instructions, role, and tone.
• Welcome message — the first message a visitor sees (default: "Hi! How can I help you today?").
• Input placeholder — the chat input's placeholder text (default: "Type your message...").

Human handoff — toggle to let the agent transfer a conversation to your team via the request_human_handoff tool. See Live Handoff & Inbox.

Voice — toggle to add a microphone button so visitors can talk to the agent in real time. See Voice Assistant.

Embedding — the public-access toggle, allowed origins, and the embed snippet (covered next).

Embedding the widget

Once you're happy with the agent, publish it from the Embedding card in Settings:

1. Turn on Enable public embed.
2. Add your site's origin(s) under Allowed origins — comma-separated and exact-match (e.g. https://example.com, https://www.example.com).
3. Copy the embed snippet and paste it into your site's HTML.

The snippet looks like this:

<script
  async
  src="https://tia.tdccommerce.com/embed/v1/widget.js"
  data-agent="YOUR_PUBLIC_SLUG"
></script>

The widget mounts a floating chat bubble in a shadow DOM, so its styles never clash with your site's CSS. It shows your welcome message, your placeholder, and — if enabled — voice and handoff.

Script options

All options are set as data-* attributes on the <script> tag; there's no JavaScript API to call.

To force dark mode:

<script
  async
  src="https://tia.tdccommerce.com/embed/v1/widget.js"
  data-agent="YOUR_PUBLIC_SLUG"
  data-theme="dark"
></script>

Important: Allowed origins must list every site the widget runs on. Leaving allowed origins empty disables the public embed even if the toggle is on. The * wildcard is available on paid plans only.

Testing with Try now

While editing an agent, click Try now to mount the real widget right in the dashboard and chat with it as a visitor would. The button is disabled until the agent is public — enable public access in Settings first (the button's tooltip reminds you of this).

Models

Every agent runs on a model. New agents use Standard — fast, accurate responses with strong tool calling — which is the right choice for most assistants. A Pro tier is also available for more complex conversations. The model is set programmatically via the Agents API (modelType); the dashboard shows each agent's current model on its card.

Billing

Chat is credit-based: each reply deducts credits based on the model used and the length of the conversation. If your organization runs out of credits, the agent replies "This assistant is currently unavailable. Please try again later." instead of answering — so top up before that happens. See Credits & Billing.

Best Practices

• Write a focused system prompt. State the agent's role, what it should and shouldn't do, and the tone. Specific beats generic.
• Train it before publishing. Add your key pages and FAQs as sources so answers are grounded in your content.
• Describe tools precisely. The AI decides when to call a tool entirely from its description — vague descriptions lead to missed or wrong calls.
• Dry-run every tool. Use the editor's dry-run to confirm the request and response mapping before going live.
• Lock down origins. List only the sites that should host the widget; avoid * unless you truly need it.
• Test with Try now. Chat through your common questions in the dashboard before embedding.

Troubleshooting

Next Steps

• Voice Assistant — let visitors talk to your agent.

When a visitor says goodbye and nothing is outstanding, the agent closes the conversation itself, so your Conversations list reflects who is actually still on the site. It will not close a conversation a teammate has taken over.

• Phone Calls — let the same agent answer your phone number.
• Live Handoff & Inbox — hand conversations to your team.
• Agents API — manage agents and embed chat programmatically.
• Credits & Billing — understand usage and costs.