Triggers

Documentation Index

Fetch the complete documentation index at: https://docs.heyy.io/llms.txt

Use this file to discover all available pages before exploring further.

​

New & reopened chat

Runs whenever a chat is opened, whether it’s the first time a contact messages you or they’re reopening a previously closed conversation. Use this when you want one automation to handle both new and returning contacts without distinguishing between them.

​

Fields

• Channel (required): Select the channel where this trigger will run.
• When to trigger (optional): Add a condition to narrow the audience based on specific conditions.
• Save text reply to (optional): Save the contact’s text reply to an automation variable.
• Save file reply to (optional): Save the contact’s file reply to an automation variable.

​

Use cases

• Single welcome flow for all opens: Send one greeting and qualification flow whether the contact is new or returning, without maintaining two separate automations.
• Unified triage: Route or assign every opened chat the same way (e.g. AI first, then handoff) regardless of first-time vs. reopened.
• Always capture the first message: Use “Save text reply to” so you can store what the contact said when they opened the chat and use it in later steps.

---

​

New incoming chat

Runs only when a contact messages you for the first time and a new chat is created. It does not run when an existing chat is reopened. Use this for welcome flows, onboarding, or any logic that should run exclusively for first-time conversations.

​

Fields

• Channel (required): Select the channel where this trigger will run.
• When to trigger (optional): Add a condition group to narrow the audience based on specific conditions.
• Save text reply to (optional): Save the contact’s text reply to an automation variable.
• Save file reply to (optional): Save the contact’s file reply to an automation variable.

​

Use cases

• First-time welcome and onboarding: Send a welcome message, collect basic info, or run a qualification flow only when someone messages you for the first time.
• New-lead handling: Trigger lead scoring, CRM creation, or assignment rules only for brand-new conversations, not when an existing chat is reopened.
• Channel-specific first contact: Use “When to trigger” to run different first-time flows by channel (e.g. WhatsApp vs. Live Chat) or by attribute.

---

​

Reopened chat

Runs when a contact sends a message in a chat that had been closed. Use this when you want different behavior for returning customers, for example, a “welcome back” message or to reassign the chat without triggering the same flow as brand new chats.

​

Fields

• Channel (required): Select the channel where this trigger will run.
• When to trigger (optional): Add a condition group to narrow the audience based on specific conditions.
• Save text reply to (optional): Save the contact’s text reply to an automation variable.
• Save file reply to (optional): Save the contact’s file reply to an automation variable.

​

Use cases

• Welcome-back message: Send a “We’re here to help again” or “Your case is still open” message when a contact reopens a closed chat.
• Reassign without full welcome: Route or assign returning chats to the right team or agent without repeating the first-time welcome flow.
• Returning-customer logic: Run different flows (e.g. loyalty, win-back) only when someone comes back after a closed conversation.

---

​

Chat closed

Runs as soon as a conversation is closed by an agent or by the system. Use this for post-conversation steps such as sending a satisfaction survey, logging outcomes, or triggering follow-up campaigns after a defined delay.

​

Fields

• Channel (required): Select the channel where this trigger will run.
• When to trigger (optional): Add a condition group to narrow the audience based on specific conditions.

​

Use cases

• Post-conversation survey: Send a satisfaction or NPS survey (e.g. via email or another channel) as soon as the chat is closed.
• Delayed follow-up campaign: Start a delay, then add the contact to a campaign or send a follow-up message after the conversation has ended.
• Logging and reporting: Trigger an API call or internal notification when a chat is closed to update your CRM or analytics.

---

​

Chat assigned

Runs when a chat is assigned to one or more team members you select. Use this to run automations only when certain users receive the chat, for example, notifying a specialist, updating internal tools, or applying role-specific workflows.

​

Fields

• Channel (required): Select the channel where this trigger will run.
• Users (required): Select the users for whom to fire this trigger.

​

Use cases

• Notify the assigned agent: Send an email or internal notification to the user who received the chat so they know a new conversation was assigned to them.
• Role-specific workflows: Run different automations when a chat is assigned to support vs. sales (e.g. different templates or next steps).
• Update external systems: When a specialist is assigned, call an API to update your ticketing system or CRM with the assignee.

---

​

Chat moved

Runs when a chat is moved into one or more of the inboxes you select. Use this to react to routing changes, for example, triggering different handling when a chat lands in a sales vs. support inbox or notifying the right team when a chat is moved to their queue.

​

Fields

• Channel (required): Select the channel where this trigger will run.
• Inboxes (required): Select the inboxes for whom to fire this trigger.

​

Use cases

• Inbox-specific handling: When a chat is moved to Sales, send a sales-focused message or assign to a sales rep; when moved to Support, run a support triage flow.
• Notify the team whose inbox received the chat: Send an internal alert or assign a default agent when a chat lands in a specific team’s inbox.
• Sync with routing rules: Trigger an API or update attributes when a chat is moved so your external routing or reporting stays in sync.

---

​

New incoming message

Runs on every new message from a contact in an existing conversation. Use this when you want to react to each message—for example, to run keyword-based logic, save replies to variables, or trigger AI or routing only when new content arrives.

​

Fields

• Channel (required): Select the channel where this trigger will run.
• When to trigger (optional): Add a condition group to narrow the audience based on specific conditions.
• Save text reply to (optional): Save the contact’s text reply to an automation variable.
• Save file reply to (optional): Save the contact’s file reply to an automation variable.

​

Use cases

• Keyword-based routing: Run only when the message contains specific words (e.g. “refund”, “cancel”) and then route, assign, or reply accordingly.
• Save and reuse the reply: Use “Save text reply to” or “Save file reply to” so the next steps (e.g. AI Transform, Condition, or a template) can use what the contact just said.
• Per-message AI or logic: Trigger an AI employee or intention recognition on every new message so you can respond or branch based on the latest content.

---

​

New Instagram comment

Runs when someone comments on your Instagram content. You can scope it to all posts and reels or to specific media. Use this to auto-reply to comments, route commenters into DMs, or run contests and engagement flows tied to particular posts or reels.

​

Fields

• Channel (required): Select the channel where this trigger will run.
• When someone comments on (required): Select between “All posts & reels” or “Specific posts/reels” and then select the posts/reels.
• When to trigger (optional): Add a condition group to narrow the audience based on specific conditions.

​

Use cases

• Campaign-specific comment reply: Use “Specific posts/reels” to auto-reply to comments on a single post or reel (e.g. contest, product launch) and optionally invite commenters into DMs.
• General comment-to-DM flow: Use “All posts & reels” to reply to comments across your account and invite people into a DM conversation with a consistent message.
• Conditional handling: Use “When to trigger” to reply only when the comment contains certain words or to route high-intent commenters differently.

---

​

Contact created

Runs when a new contact is created in Heyy. Use this to enrich or route contacts as soon as they enter your system—before any chat exists.

​

Fields

• When to trigger (optional): Add a condition group to narrow which contacts should start this automation (e.g. only contacts from a specific source or with certain attributes).

​

Use cases

• Enrichment on create: Call an API to enrich the contact (company, location, lead score) and store results in attributes.
• Auto-label new contacts: Add labels such as “new”, “lead”, or “needs_enrichment” immediately after creation.
• Kick off lifecycle: Subscribe the contact to a journey or campaign the moment they’re created.

---

​

Contact attribute updated

Runs when one or more selected contact attributes change. Use this to react to changes in profile data (e.g. lead status, plan, region) and trigger follow-ups or routing when the data becomes available.

​

Fields

• Attributes (required): Select which contact attributes should trigger this automation when they’re updated.
• When to trigger (optional): Add a condition group to narrow which updates should start the automation (e.g. only when status becomes “qualified”).

​

Use cases

• React to qualification: When lead_status becomes “qualified”, notify sales or start a sales outreach flow.
• Keep systems in sync: When key attributes change, call an API to update your CRM or data warehouse.
• Progression-based automation: When onboarding_step changes, send the next message or subscribe the contact to the next journey stage.

---

​

Label added

Runs when one or more selected labels are added to a contact. Use this to trigger workflows based on segmentation and tagging.

​

Fields

• Labels (required): Select the labels that should trigger this automation when added.
• When to trigger (optional): Add a condition group to narrow which labeled contacts should start the automation.

​

Use cases

• Start segmented flows: When “VIP” is added, start a priority handling automation or notify a manager.
• Ops handoff: When “needs_follow_up” is added, assign a task, send a reminder, or add the contact to a follow-up campaign.
• Qualification tags: When “high_intent” is added, start an AI or routing flow to get them to the right team faster.

---

​

Label removed

Runs when one or more selected labels are removed from a contact. Use this when removing a tag should end, change, or reverse part of a workflow.

​

Fields

• Labels (required): Select the labels that should trigger this automation when removed.
• When to trigger (optional): Add a condition group to narrow which contacts should start the automation.

​

Use cases

• End a lifecycle: When “trial” is removed, subscribe to a post-trial journey or update the contact’s status in external systems.
• Reverse segmentation: When a label is removed (e.g. “needs_follow_up”), clear reminders, stop related automations, or update CRM flags.
• Clean up attributes: When a temporary label is removed, clear temporary automation variables or attributes tied to that segment.

---

​

Webhook received

Runs when Heyy receives a webhook event from one of your webhook endpoints. Use this to start automations from external systems (e.g. Stripe, Shopify, internal tools), map payload data into attributes/variables, and optionally identify which contact the webhook belongs to.

​

Fields

• Webhook endpoint (required): Choose the webhook endpoint that should trigger this automation.
• Search contact by (optional): Configure how Heyy should find the contact in the webhook payload (e.g. by contact ID, email, or phone number).
• Data mapping (optional): Map values from the webhook JSON payload into contact attributes or automation variables.

​

Use cases

• External events → messaging: When a payment succeeds or an order ships, start an automation that sends an update to the customer.
• Sync enrichment data: When your backend posts enrichment results, map fields into contact attributes and branch based on them.
• Unified automation entry point: Trigger the same automation from multiple systems by posting to the endpoint and mapping fields into variables.

---

​

Manual trigger

Runs only when started by you or by another automation—from the Inbox, a campaign, an API call, or a Start Other Automation action. Use this for flows that should not start from customer activity, such as scheduled follow-ups, bulk actions, or sub-flows called by other automations.

​

Fields

• Channel (required): Select the channel where this trigger will run.

​

Use cases

• Reusable sub-flows: Build one automation (e.g. send survey, add to campaign) and start it from multiple places—other automations, campaigns, or the Inbox—using the Start Other Automation action and variable mapping.
• API- or campaign-driven flows: Start the automation via API or when a contact enters a campaign, so the flow runs only when you or an external system decides, not on every new message.
• Scheduled or bulk actions: Use manual trigger for flows that run on a schedule, from a bulk action, or when an agent clicks “Run automation” in the Inbox.