聊天组件集成文档
从基础安装到外观配置，了解如何把 TalkTG 在线聊天接入你的网站。
目录
快速开始
只需粘贴一行代码，几分钟内即可完成接入。
注册并添加网站
创建账号后进入“网站”，点击“添加网站”，填写你的网站域名。
绑定 Telegram 机器人
通过 @BotFather 创建机器人，复制 Bot Token，在网站详情页完成绑定，然后向机器人发送 /start。
粘贴组件代码
从网站详情页复制嵌入代码，粘贴到 HTML 的 </body> 结束标签前。
准备工作
- 1一个 TalkTG 账号
- 2一个可以编辑 HTML 源码的网站
- 3一个通过 @BotFather 创建的 Telegram Bot Token
安装方法
将下方脚本中的 YOUR_SITE_ID 替换为控制台显示的网站 ID。
<script src="https://talktg.com/widget.js"
data-site-id="YOUR_SITE_ID" async></script>普通 HTML
把脚本放在页面的 </body> 结束标签前。
Next.js / React
在根布局中使用 Next.js Script 组件，并设置 strategy="lazyOnload"。
Vue / Nuxt
将脚本加入 nuxt.config.ts 的 app.head.script 配置。
WordPress
在 footer.php 的 </body> 前加入脚本，或使用页眉页脚代码插件。
Shopify
在 theme.liquid 的 </body> 前加入脚本。
Wix
在自定义代码中添加脚本，位置选择 Body 末尾并应用到所有页面。
组件配置
进入“网站 → 你的网站 → 组件设置”，即可调整组件外观和行为。
| 选项 | 默认值 | 说明 |
|---|---|---|
| 主色 | #6366F1 | 聊天按钮、标题栏和访客消息的主题色。 |
| 位置 | bottom-right | 按钮显示在右下角或左下角。 |
| 欢迎语 | Hi there! | 首次访问时显示的欢迎内容。 |
| 客服名称 | Support | 聊天标题栏中显示的名称。 |
| 自动弹出 | false | 是否自动向新访客显示欢迎气泡。 |
| 提示音 | true | 收到客服消息时是否播放提示音。 |
API 参考
以下公共接口由聊天组件内部调用，普通接入通常不需要手动请求。
/api/widget/config/{siteId}获取组件配置。
/api/sites/{siteId}/status检查 Telegram 机器人状态。
/api/chat/send发送访客消息。
/api/chat/history加载会话历史。
/api/chat/poll轮询新消息。
工作原理
组件异步加载，并通过 Shadow DOM 隔离样式。
访客消息经 TalkTG 转发到你绑定的 Telegram。
你在 Telegram 中的回复会显示在网页聊天窗口中。
访客身份保存在浏览器中，返回网站后可以继续原会话。
常见问题与排查
网站没有显示聊天组件
确认脚本位于 </body> 前、Site ID 正确，并检查浏览器控制台。
Telegram 收不到消息
确认绑定后已向机器人发送 /start，且控制台显示为已绑定。
可以在多个域名使用吗？
每个网站对应一个域名；多个域名请分别创建网站。
组件会拖慢网站吗？
不会。组件使用 async 异步加载，不阻塞页面渲染。
准备好开始了吗？
几分钟即可完成配置，无需信用卡。