←back to manuals

Trigger Integration

Trigger Integration Execution

Trigger integrations run a bot workflow whenever an external event is received or a trigger schedule fires. This workflow coordinates session reuse, optional contact creation, conversation execution, and execution tracking so each trigger run can be processed safely and reviewed later.

Execution Lifecycle

Each trigger execution follows a predictable lifecycle:

  1. Initialization: The system validates that the trigger integration exists, confirms a bot is configured, checks account conversation limits, and atomically marks the integration as running. If another execution has already claimed the integration, the duplicate request is skipped.

  2. Session Resolution: The workflow resolves a session key using the explicit session option when provided, then falls back to the contact email or phone number. If none are available, it generates a random session identifier. This determines whether a previous conversation is resumed or a new one is created.

  3. Contact and Conversation Setup: When contact details are included, the platform creates or reuses an untrusted contact record before opening the conversation. New conversations inherit the trigger integration name, description, bot configuration, and metadata so the bot has the correct execution context.

  4. Context Injection: On a new or empty conversation, the workflow adds an instruction message plus a structured activity payload containing the current trigger integration details and the last execution summary, if one exists from a different conversation.

  5. Incoming Event Capture: If the trigger was invoked with a body payload, that raw event body is injected into the conversation as an activity message. This gives the bot direct access to the event contents that caused the trigger to run.

  6. Bot Processing: The conversation engine runs in single-step chunks so long-running work can continue safely across queue iterations. The bot may request a bounded delay using the internal _delay function when it needs to wait for an external process before continuing.

  7. Completion and Summary: When execution finishes, the platform extracts a structured name, description, and detailed summary from the most recent conversation messages, stores them on the execution record, and returns the integration to the idle state.

Session Persistence

Trigger integrations can preserve conversation state between executions:

  • Session Duration: Controlled by sessionDuration in milliseconds. When the resolved duration is at least 60 seconds, the conversation ID is cached in Redis and may be reused by later executions with the same session key.

  • Session Reuse: Reused sessions allow follow-up events for the same user, contact, or explicit session to continue the existing conversation instead of starting from scratch.

  • New Sessions: When no cached conversation exists, when the conversation no longer exists, or when a different session key is used, a new conversation is created and initialized with trigger-specific context.

Event and Contact Context

Trigger executions can carry external context into the conversation:

  • Incoming Body: The optional body field contains the raw trigger event payload. This is useful for webhook-style integrations where the bot needs to parse or react to external JSON, form data, or text payloads.

  • Contact Identification: The optional contact object can include a name, email, and phone number. Email or phone can anchor session reuse, and the platform can create an untrusted contact record for downstream use.

  • Previous Execution Summary: When available, the bot receives context from the most recent prior execution on a different conversation. This helps with incremental processing, follow-up actions, and recovery from previous failures.

Execution Outcomes

Each trigger execution ends in one of these outcomes:

  • Success: The bot completed its work, a summary was extracted, and both the execution record and trigger integration are marked successful.

  • Failure: An error occurred during workflow setup, conversation execution, or summary extraction. The failure is recorded and the trigger integration is returned to idle so it can run again later.

  • Skipped: If the trigger integration is already running when another execution request arrives, the duplicate request is ignored to avoid overlapping work.

Limits, Scheduling, and Concurrency

Trigger execution is guarded by both per-trigger and platform-wide limits:

  • Single Active Execution: Only one execution can actively own a trigger integration at a time. An atomic status update prevents competing workers from processing the same trigger simultaneously.

  • Iteration and Time Limits: Each run respects configured maxIterations and maxTime settings, with platform minimums and hard caps applied. If a limit is reached, the workflow records a limit-exceeded status and finalizes the execution cleanly.

  • Deduplication Window: Trigger executions are deduplicated within a one-minute window using a queue deduplication key. This reduces accidental duplicate runs caused by rapid repeated invocations.

  • Scheduled Re-entry: When triggerSchedule is configured, the workflow calculates the next scheduled execution time after completion or failure so recurring automations continue to run.

Automatic Summary Generation

After a successful run, the platform generates a detailed execution summary from recent conversation history. The summary is designed to capture:

  • Key steps taken and actions performed
  • Important outcomes and generated results
  • Any external data received from the trigger event
  • Decisions made during the workflow
  • Issues encountered and how they were handled
  • Context that will help the next execution continue intelligently

Best Practices

To build reliable trigger-driven workflows:

  • Use Stable Session Keys: Pass a deterministic session value or a contact email or phone number when you want related events to share memory.

  • Keep Event Bodies Structured: Send well-formed payloads in body so the bot can reliably extract fields and make decisions.

  • Design for Replays: External systems may retry webhook deliveries or resubmit events. Trigger workflows should tolerate duplicate or repeated events without causing inconsistent side effects.

  • Review Execution History: Inspect trigger execution records and summaries to debug failures, verify expected automation behavior, and refine prompt or integration configuration over time.