Payload Reference

Every webhook in Chattlebot starts with a default payload template — a JSON structure that includes all available data about the lead, bot, conversation, and context. This template is shared by all platform templates (Zapier, n8n, Make, and Custom). The default payload is organized into six sections: a top-level 'event' field (always 'lead_captured'), a 'timestamp' field, and five nested objects — 'lead' (visitor information), 'bot' (chatbot details), 'conversation' (chat data like message count, duration, and summary), 'context' (referrer, UTM parameters, and browser info), and 'session' (session and visitor IDs). You can customize this template to include only the fields your API needs, rearrange the structure, or add static values. The template uses {{variable}} syntax for dynamic data — these placeholders are replaced with real values when the webhook fires.

Lead variables contain all the information the visitor provided during the conversation. {{lead.email}} is the lead's email address. {{lead.name}} is the lead's full name. {{lead.phone}} is the lead's phone number. {{lead.category}} is the automatically detected or manually set lead category (e.g., 'pricing', 'support', 'demo'). {{lead.urgency}} is the urgency level — 'low', 'medium', or 'high' — determined by AI analysis of the conversation. {{lead.sentiment}} is the detected sentiment — 'positive', 'neutral', or 'negative'. Bot variables identify which chatbot generated the lead. {{bot.id}} is the unique bot identifier. {{bot.name}} is the display name of the bot. {{bot.url}} is the URL where the bot is embedded.

Conversation variables provide data about the chat session itself. {{conversation.transcript}} contains the full conversation as an array of messages, each with a role (user or assistant) and content. {{conversation.message_count}} is the total number of messages exchanged. {{conversation.duration_seconds}} is how long the conversation lasted in seconds. {{conversation.started_at}} and {{conversation.ended_at}} are ISO 8601 timestamps for when the chat began and ended. {{conversation.summary}} is an AI-generated short summary of the conversation. Context variables capture the visitor's browsing environment. {{context.referrer}} is the page URL the visitor came from. {{context.user_agent}} is the browser's user agent string. {{context.language}} is the browser's language setting (e.g., 'en-US'). {{context.utm_source}} and {{context.utm_campaign}} capture UTM tracking parameters from the page URL — useful for attributing leads to specific marketing campaigns.

Session variables identify the specific chat session. {{session.id}} is the unique chat session identifier — useful for correlating webhook data with conversation logs. {{session.visitorId}} is the visitor's persistent identifier across sessions — the same visitor returning later will have the same visitor ID but a new session ID. Timestamp variables provide the exact time the webhook fires. {{timestamp}} gives the current time in ISO 8601 format (e.g., '2025-01-15T10:34:05Z'). {{timestamp_unix}} gives the same time as a Unix timestamp (seconds since epoch) — useful for APIs that expect numeric timestamps. In total, there are 23 variables available across all categories. All variables can be used in the URL, headers, and payload template.

Variable substitution is like fill-in-the-blanks. When a webhook fires, Chattlebot takes your payload template and replaces every {{variable}} placeholder with the actual value from the conversation. For example, {{lead.email}} becomes 'jane@acme.com' and {{lead.urgency}} becomes 'high'. Variables work everywhere — in the URL (useful for REST APIs like /api/contacts/{{lead.email}}), in custom headers (e.g., X-Bot: {{bot.name}}), and in the payload body. If a variable has no value (for instance, the visitor didn't provide a phone number), it resolves to an empty string. This means your JSON will contain an empty value rather than the {{variable}} placeholder — your API should handle empty strings gracefully. You can also use variables inside static text: 'Lead from {{bot.name}} on {{timestamp}}' becomes Lead from Sales Assistant on 2025-01-15T10:34:05Z'.