Triggers

Triggers are custom actions you configure for your agent. When a user says something that matches a trigger, the agent executes it — either rendering a template response or calling an external API.

Trigger types

Type	What it does	Example
Static	Returns a pre-defined templated response (no API call)	Welcome message, store hours, return policy
API Call	Calls your external API and returns the result	List orders, check appointment, get balance

Creating a trigger

1. Go to your agent’s Triggers page.

2. Click New Trigger.

3. Fill in the Information panel:

   • Name — Display name (e.g., “List Orders”)
   • Description — Tell the AI when to use this trigger (e.g., “Use when the user asks about orders, purchases, or order status”)
   • Keywords — Words and phrases that help match this trigger (e.g., “orders”, “pedidos”, “meus pedidos”)

4. Fill in the Settings panel:

   • For Static: Write your success and error response templates.
   • For API Call: Configure the HTTP request (method, URL, headers), success criteria, and response templates.

5. Click Save.

Keywords (routing hints)

Keywords help the agent quickly identify which trigger matches a user’s message. Tips:

• Include both singular and plural forms (e.g., “order” and “orders”)
• Include translations if your users speak multiple languages (e.g., “pedido”, “pedidos”)
• Include common phrases (e.g., “meus pedidos”, “status do pedido”)
• Up to 20 keywords per trigger

Input parameters

Define parameters the agent should extract from the conversation before calling the trigger:

Field	Description
Key	Parameter name (e.g., orderId)
Type	Data type: string, number, integer, boolean, or array
Description	Tells the AI what this parameter represents
Required	Whether the agent must have this before executing

The agent automatically extracts these from the conversation context.

API Call configuration

For API Call triggers, configure:

Field	Description
Method	HTTP method (GET, POST, PUT, PATCH, DELETE)
URL	Your API endpoint. Use {{inputs.paramName}} for dynamic values.
Headers	Request headers (e.g., Accept: application/json)
Body	Request body parameters (for POST/PUT)
Success status	HTTP status codes that indicate success (e.g., 200)
Extract JSON Path	Optional JSONPath to extract specific data from the response (e.g., $.orders)

Response templates

Write templates using Handlebars syntax:

Template	When it’s used
Ask (optional)	Shown before executing — for confirmation prompts
Success	Shown when the trigger succeeds
Error	Shown when the trigger fails

Available variables

Variable	Description
{{inputs.paramName}}	Extracted input parameters
{{data}}	API response data (API Call triggers only)

Template helpers

Format data in your responses:

{{currency price "USD"}}          → $49.99
{{formatDate date "MMM dd, yyyy"}} → Apr 20, 2026
{{uppercase text}}                 → HELLO
{{join items ", "}}                → item1, item2, item3
{{default value "N/A"}}            → fallback if empty

Channel scope

Control which channels can use each trigger:

Option	Meaning
All Channels	Available on WebChat, WhatsApp, and Instagram
WebChat Only	Only available on your website chat widget
Messaging	Only available on WhatsApp and Instagram
WhatsApp Only	Only available on WhatsApp
Instagram Only	Only available on Instagram

Tip

Use channel scope when your trigger uses different authentication methods per channel. For example, a “List Orders” trigger might use a login token on WebChat but a document ID on WhatsApp.

Authentication

Triggers can require user authentication before executing. This is useful for actions that access private data (orders, account info, payments).

To require authentication:

1. Set Auth type to “User Session” in the trigger’s settings.
2. Make sure the User Authentication extension is enabled and configured.

When a user invokes an authenticated trigger:

• On WebChat: A login form appears. After login, the trigger executes with the user’s token.
• On WhatsApp/Instagram: The agent asks for identification (e.g., CPF). After verification, the trigger executes with the user’s identity.

See User Authentication for full setup guide.

Testing triggers

Use the Test button in the trigger editor to test your API Call triggers without sending a real user message. Enter sample input values and see the raw API response.

Best practices

• Write clear descriptions — The AI uses the description to decide when to call your trigger. Be specific about the user intent.
• Use relevant keywords — Include common variations in multiple languages your users speak.
• Set appropriate channel scope — Don’t expose WebChat-only triggers to messaging users.
• Handle errors gracefully — Write helpful error templates that guide the user.
• Keep URLs secure — Never put secrets directly in trigger URLs. Use the authentication extension for protected APIs.