HostWebhook Help Center

Build a chatbot with a Chat Trigger

Set up a Chat Trigger and an AI node, test the chatbot, then share it as a link, embed it on your site or call its webhook.

Time about 10 minutesYou need a HostWebhook account and an AI provider API keyUpdated September 29, 2026
VisitorTypes in the chat
POST →
Chat Trigger nodeIngest webhook
/chat-triggers/in/:chatId/message
payload →
AI nodeOpenAI, Anthropic, Gemini…
{{payload.message}}
SSE →
VisitorSees the reply stream in

The same Chat Trigger can power a shared link, a website widget, an npm component and direct API calls at the same time.

Open the Chat Trigger in Flows

Sign in to hostwebhook.com and click Flows in the left sidebar. A Chat Trigger always comes with an AI node already connected, and both start paused. Click the Chat Trigger node to open its settings.

  1. The Chat Trigger receives each visitor message through its webhook.
  2. The AI node writes the reply. You configure it in step 6.
Flows page showing a Chat Trigger node connected to an AI node

Starting from scratch? Add a Chat Trigger from the canvas (Nodes → build on the canvas). It arrives already connected to an AI node, just like this one.

Name and style the chat

The Set up your Chat Trigger window has three tabs. On Configuration, set what visitors see at the top of the chat. Changes save automatically; look for Saved in the top-right corner.

  1. Configuration, Advanced and Share & Activity hold every setting.
  2. Title and Subtitle appear in the chat header. This example uses “Support Assistant”.
  3. Don't click Activate yet. Turn it on after the AI node is ready (step 8).
Chat Trigger configuration tab with title and subtitle filled in

Add a greeting and a persona

Scroll down the same tab. Set your brand color, add a greeting with + Add under Initial messages, and optionally give this chat its own persona.

  1. Primary color and Mode (dark, light or auto) style the widget.
  2. The greeting shows before the visitor types. It is display-only and is never sent to the AI.
  3. System prompt override replaces the AI node's system prompt for this chat only. Use it to run several bots with different personalities from one AI node.
Theme, initial message and system prompt override fields

Seeing “Not saved”?

An empty greeting row blocks saving. Type the greeting text, or click Remove on the empty row.

Set session and rate limits

Open the Advanced tab. Every message a visitor sends is a paid AI call, so these limits control your costs.

  1. The Advanced tab. Leave Session ID strategy on auto when you use the hosted link or widget.
  2. Messages per minute defaults to 60 (range 1–600). For a public chat, a lower value such as 10–20 limits abuse.
  3. Per session is the recommended throttle bucket. Visitors behind the same office network don't share a limit.
Advanced tab with session ID strategy and rate limit

Usage caps (further down) add hard daily and monthly limits on messages, tokens and dollars, and can email you at 75%, 90% and 100% of the monthly caps.

Choose who can use the chat

Scroll to the bottom of Advanced.

  1. Allowed origins lists the sites that may embed the chat, one per line, such as https://yoursite.com. Leave it empty on a public chat to allow any site.
  2. Public lets anyone with the link chat. HMAC signed only accepts requests signed by your own backend. Use it for logged-in users or paid tools.
Allowed origins and authentication settings

Using HMAC signed?

  • Allowed origins becomes required. If you also want the shared chat link to work, include the origin shown in your Share URL (step 10) along with your own site. Otherwise the link fails with a 403 error.
  • Every request must be signed. Send an Authorization: Bearer <sig>:<ts> header, where sig is HMAC-SHA256 of sessionId:ts using the trigger's secret. The signature is valid for 5 minutes.
  • Keep the secret on your server and never put it in the browser. The widget gets signatures from a small signing endpoint you host. See the HostWebhook docs for examples in Node, Python and PHP.

Choose the AI provider

Click Done, then click the AI node in Flows (“Answers the chat …”) to open Set up your AI.

  1. Optional: Go to checklist adds guardrails (off-topic, PII, jailbreak rules). Recommended for public chats.
  2. Pick a provider: Anthropic, OpenAI, Google, Groq, OpenRouter or a self-hosted Ollama. This guide uses OpenAI.
AI node configuration with provider options

Connect your API key and the visitor's message

Under Credential, click + Add OpenAI API Key (the button is named after your provider) and paste your key. Then fill in User message with {{payload.message}}, which is the text the visitor typed.

  1. A green Credential box means the key is connected. The key itself stays hidden.
  2. {{payload.message}} sends the visitor's text to the AI.
Connected OpenAI credential and user message chip
  1. The System prompt sets the bot's default behaviour.
  2. Once you click away, {{payload.message}} shows as a Message chip.
System prompt and user message fields

Where to get a key: OpenAI at platform.openai.com/api-keys, Anthropic at console.anthropic.com/settings/keys, Groq (free tier) at console.groq.com/keys. The provider account needs billing or credits set up, or replies will fail.

Activate both nodes

Click Activate at the top of the AI node, then reopen the Chat Trigger node and click Activate there too. Both badges should change from Paused to Active. A paused node ignores incoming messages.

  1. AI node: Active.
  2. Credential connected.
AI node showing Active status
  1. Chat Trigger: Active.
  2. Preview widget opens a test chat (next step).
Chat Trigger showing Active status

Test it in the preview

On the Chat Trigger's Configuration tab, click Preview widget. The real widget opens on the right. Send a message and watch the reply stream in.

  1. The live chat widget, using your title, subtitle and theme.
  2. Your greeting message.
Preview widget open with greeting
  1. Your test message.
  2. The AI's reply, streamed back from the webhook.
Preview widget showing a test message and AI reply

A working preview doesn't prove the shared link works.

The dashboard preview skips the origin check. Always test the shared link too (next step), especially in HMAC signed mode.

Share the link or embed it on your site

Open the Share & Activity tab. It lists everything you need to put the chat in front of people.

  1. The Share & Activity tab.
  2. Chat ID and Ingest endpoint: the webhook the widget posts to (step 11).
  3. Share URL: a ready-made chat page.
Share and Activity tab with Chat ID, ingest endpoint and share URL
  1. Copy or Open the hosted link.
  2. The embed code for your website.
Share URL and website embed code

Option A: shared link. Paste the Share URL anywhere: an email, Slack, a QR code. No code needed.

  1. Your title and subtitle.
  2. A real AI answer on the public link.
  3. Where visitors type.
Hosted chat page answering a visitor

Option B: website widget. Copy the snippet from Embed on your site and paste it just before </body>. It adds a floating chat button in the corner.

HTML
<script src="https://www.hostwebhook.com/widget.js"
data-chat-id="YOUR_CHAT_ID"
data-position="right"
data-primary="#7c3aed"
data-label="Support Assistant"
defer></script>

Option C: React / Next.js.

Terminal + TSX
npm install @hostwebhook/chat-widget

import { HwChat } from '@hostwebhook/chat-widget/react';

<div style={{ height: 540 }}>
<HwChat chatId="YOUR_CHAT_ID" />
</div>

After embedding, add your site to Allowed origins (step 5) if you want only your own domain to use the chat.

Build your own customized chat UI

Optional · Advanced

Most people can stop at step 10. This step is only for developers who want their own chat interface, a mobile app or a backend integration instead of the ready-made widget.

Show how to call the webhook directly

Post to the Ingest endpoint from step 10. Send the visitor's message and a session ID you choose. Reuse the same session ID to continue a conversation.

curl · public trigger
curl -N -X POST \
https://api.hostwebhook.com/api/chat-triggers/in/YOUR_CHAT_ID/message \
-H "Content-Type: application/json" \
-d '{"message": "What are your opening hours?", "sessionId": "visitor-123"}'

The reply streams back as Server-Sent Events:

Response (SSE)
event: session
data: {"sessionId":"visitor-123","hwsSessionId":"visitor-123"}

event: token
data: {"text":"We're open"}

event: token
data: {"text":" 9am to 5pm."}

event: done
data: {"response":"We're open 9am to 5pm.","conversationId":"…"}

Signed trigger? Add the Authorization header described in step 5.

Troubleshooting

What you seeCauseFix
No reply at allA node is paused, or the AI node has no credential.Check that both nodes show Active and that the Credential box is green (steps 7–8).
“Not saved”An empty greeting row.Fill it in or click Remove.
429 Too many messagesThe rate limit was reached.Wait for the Retry-After time, or raise Messages per minute (step 4).
401 Invalid or missing signatureSigned trigger without a valid HMAC.Sign sessionId:ts with the trigger secret; sign the session ID you send.
403 on the shared linkSigned mode with an empty or incomplete Allowed origins list.Add your site and the Share URL's origin to Allowed origins (step 5).
Chat stops for a visitorA usage cap was reached.Raise or clear the cap under Usage caps. Daily caps reset at UTC midnight.