Skip to main content

Available event types: A detailed guide

Updated over 3 weeks ago

Summary

This article explains the different event types available for REST API actions in Wati. You will learn when each event is triggered, what data it can send, and how to use them correctly - especially when collecting feedback, form data, or lead information.

Instructions

Event-based REST API actions run automatically when a specific event occurs in a conversation. Each event type behaves differently, especially in terms of what data (parameters) can be sent.

Understanding these differences helps you choose the right event and avoid configuration issues.

1. Thumbs up / thumbs down events

When it triggers

This event is triggered when a user clicks the feedback button (👍 or 👎) in the chat interface.

Parameter behavior

  • Only static (fixed) parameters are supported

  • Dynamic user data cannot be passed

This means all values in the API request must be predefined.

Common use cases

  • Track user satisfaction metrics

  • Send Slack notifications when negative feedback is received

  • Log feedback events to an analytics platform

⚠️ Important: Thumbs up and thumbs down events cannot send dynamic user information such as email addresses, names, or conversation content on their own.

Combining thumbs up/down with a feedback form

If you need detailed feedback or user information, you can combine this event with the Form is submitted event.

How it works

  1. Create a Feedback type Custom Form

  2. When the user clicks 👍 or 👎, the feedback form automatically appears

  3. The user fills out the form (for example, reason for feedback or email)

  4. Both events can trigger at the same time:

    • Thumbs up/down event → sends static data

    • Form is submitted event → sends dynamic form data

Example scenario

💡 Tip: To collect emails, reasons, or comments, always use a Custom Form and create a separate REST API action for the Form is submitted event.

2. Form is submitted event

When it triggers

This event is triggered when a user completes and submits a Custom Form in the chat interface.

Parameter behavior

  • Supports dynamic parameters from form fields

  • Form field names must exactly match the placeholders used in your REST API configuration

How to set it up

Step 1: Create a Custom Form

Create a Custom Form with clearly defined field names.

Example:

Form field name

Field type

Description

email

Email

User’s email address

first_name

Text

User’s first name

company

Text

Company name

message

Text

User’s message

Step 2: Configure the REST API action

Use placeholders in your API request where the suffix matches the form field name.

Placeholders can include prefixes like contact., agent., or action., but matching is based only on the suffix (the part after the last .).

Examples:

  • Form field email → {{email}} or {{contact.email}}

  • Form field first_name → {{first_name}} or {{contact.first_name}}

  • Form field company → {{company}} or {{contact.company}}

Parameter matching rules

Form field

Placeholder

Match

Reason

email

{{email}}

✅ Yes

Direct match

email

{{contact.email}}

✅ Yes

Suffix email matches

first_name

{{contact.first_name}}

✅ Yes

Suffix first_name matches

first_name

{{agent.first_name}}

✅ Yes

Suffix first_name matches

firstName

{{contact.first_name}}

❌ No

Suffix mismatch (case sensitive)

user_email

{{contact.email}}

❌ No

Suffix mismatch

( user_email ≠ email)

⚠️ Important: The placeholder suffix must exactly match the form field name, including case. The prefix does not affect matching.

Example flow

3. Lead captured event

When it triggers

This event is automatically triggered 10 minutes after the conversation ends, if the AI agent has collected lead information during the chat.

Parameter behavior

  • Uses a fixed request body structure

  • You cannot customize or modify the fields sent

Fixed request body structure

When this event runs, Wati automatically sends the following payload:

{
  "agent_id": "agent_id",
  "data": {
    "conversation_id": "conversation_id",
    "details": "Lead details",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "lead_level": "Hot",
    "lead_score": 100,
    "lead_summary": "Lead summary",
    "max_score": 100
  },
  "event": "lead_captured"
}

Field descriptions

Field

Description

agent_id

ID of the AI agent

conversation_id

Unique conversation identifier

details

Lead information collected

email

User’s email (if available)

first_name

User’s first name

last_name

User’s last name

lead_level

Lead quality (Hot, Warm, Cold)

lead_score

Numeric lead score

lead_summary

AI-generated lead summary

max_score

Maximum possible score

Note: You do not need to define a request_body for Lead captured events. Any custom request body configuration will be ignored.

Common use cases

  • Automatically create leads in Salesforce or HubSpot

  • Send lead data to marketing automation tools

  • Trigger follow-up workflows in your CRM

Quick Reference: Event Type Comparison

Feature

Thumbs Up/Down

Form Submitted

Lead Captured

Dynamic parameters

❌ No

✅ Yes

❌ Fixed structure

Custom request body

✅ Yes (static only)

✅ Yes

❌ No

Requires form setup

❌ No

✅ Yes

❌ No

Trigger timing

Immediate

Immediate

10 min after chat ends

User action required

Click feedback

Submit form

None (automatic)

Choosing the right event type

  • Use Thumbs up / down for simple feedback tracking

  • Use Form is submitted when you need dynamic user input

  • Use Lead captured for automated lead handoff after conversations

Selecting the right event ensures your REST API actions run reliably and send the data you expect.

Related Articles
Introducing the actions library in Astra
What is a REST API action?
How to set up a REST API action
How to troubleshoot REST API actions
Did this answer your question?