Triggers

Triggers are the entry points into your agent's flows. They serve as the initial contact point between external systems and your agent, handling incoming events and initializing conversations with appropriate context and memory.

Trigger Types

MindedJS supports three types of triggers:

1. Manual Triggers

  • Invocation: Triggered directly by calling the agent.invoke() method in your code

  • Use Case: Perfect for testing or programmatic agent invocation

  • Setup: No platform configuration required - simply call the method with your parameters

// Manual trigger example
const result = await agent.invoke({
  triggerName: 'manual-trigger',
  triggerBody: { message: 'Hello agent' },
  sessionId: 'user-session-123',
});

2. App Triggers

  • Invocation: Triggered by specific applications and external integrations (e.g., Slack, Zendesk)

  • Setup: Configured through the Minded platform interface

  • Identification: Each app trigger is identified by a unique appTriggerId

  • Data Handling: Supports automatic message conversion for certain apps (e.g., Slack messages)

3. Webhook Triggers

  • Invocation: Triggered by HTTP requests to specific endpoints in the Minded platform

  • Setup: Configured through the Minded platform interface

  • Agent Specific: Each webhook trigger belongs to a specific agent and cannot be shared between agents

  • Use Case: Ideal for receiving data from external systems, APIs, or third-party services that can send HTTP requests

Note: Both app triggers and webhook triggers are configured and managed through the Minded platform. All triggers are agent-specific and cannot be shared between different agents.

Trigger Invocation History

When a trigger is invoked, it creates a comprehensive record of the event that is:

  1. Added to the flow history for tracking and debugging

  2. Preserved throughout the flow's execution as a history step

This history allows tools and handlers to:

  • Access the original trigger context

  • Make decisions based on the triggering event

  • Maintain conversation continuity

  • Debug flow execution

  • Track the agent's execution path through different nodes

Each history step contains the following information:

  • step: Sequential step number in the agent's execution flow

  • type: Type of the step (TRIGGER_NODE, APP_TRIGGER_NODE, TOOL_NODE, etc.)

  • nodeId: ID of the node that was executed

  • nodeDisplayName: Human-readable name of the node

  • raw: Raw data associated with the step (e.g., trigger input, tool output)

  • messageIds: IDs of messages associated with this step

Example:

const tool: Tool = {
  name: 'myTool',
  execute: async ({ input, state }) => {
    // Access trigger information from history
    const triggerStep = state.history.find((step) => step.type === 'TRIGGER_NODE' || step.type === 'APP_TRIGGER_NODE');

    if (triggerStep) {
      console.log(`Processing request from node: ${triggerStep.nodeDisplayName}`);

      // Handle different trigger types based on history
      if (triggerStep.nodeDisplayName === 'manual-trigger') {
        // Handle manual trigger
        console.log('Manual trigger data:', triggerStep.raw);
      } else if (triggerStep.type === 'APP_TRIGGER_NODE' && triggerStep.appName === 'Slack') {
        // Handle app trigger from Slack
        console.log('Slack trigger data:', triggerStep.raw);
      }
    }

    return { result: 'Success' };
  },
};

Default Message Behavior

MindedJS provides intelligent message handling for a few app triggers through the triggerTypeToDefaultMessage mapping. This system:

  • Automatically converts trigger data into appropriate message formats

  • Maintains conversation context without manual intervention

  • Supports different message types for different applications

  • Can be overridden using the onTriggerEvent handler

Currently supported default messages:

  • App Triggers (Slack): For "New Direct Message (Instant)" triggers, the message text is automatically converted to a human message

  • Manual Triggers: No automatic message conversion - you control the flow entirely

  • Webhook Triggers: Flexible message handling based on the HTTP payload structure

Example:

// Manual trigger - full control over the flow
const manualResult = await agent.invoke({
  triggerName: 'manual-trigger',
  triggerBody: { customData: 'Hello manually' },
  sessionId: 'manual-session-123',
});

// App trigger (Slack) - automatic message conversion
const slackResult = await agent.invoke({
  triggerName: 'New Direct Message (Instant)',
  triggerBody: { text: 'Hello from Slack' },
  appName: 'Slack',
});

// Webhook trigger - handled based on HTTP payload
const webhookResult = await agent.invoke({
  triggerName: 'webhook-endpoint-name',
  triggerBody: { payload: 'Hello from webhook' },
  appName: 'Webhook',
});

Validate Trigger Input

// ✅ Good - Input validation
agent.on(AgentEvents.TRIGGER_EVENT, async ({ triggerName, triggerBody, sessionId }) => {
  if (!triggerBody.customerId || !triggerBody.message) {
    return { isQualified: false }; // Disqualify invalid triggers
  }
  // Process valid trigger
  return { isQualified: true };
});

// ❌ Avoid - No validation
agent.on(AgentEvents.TRIGGER_EVENT, async ({ triggerBody, sessionId }) => {
  // Process without validation
  return { isQualified: true };
});

Session ID in Trigger Events

The sessionId parameter in TRIGGER_EVENT is automatically provided by the platform in different environments:

  • Sandbox Playground: The platform automatically generates and provides a default sessionId for each trigger execution. It's important to pass it forward in sandbox environment.

  • Production Applications: Users are expected to provide their own sessionId if they wish to suppport resuming sessions.

  • Session Continuity: When a sessionId is provided that matches an existing session, the agent will resume from the previous state instead of starting fresh

Webhook Headers

When handling webhook triggers, request headers are available through triggerBody.headers. This allows you to access important metadata about the incoming request.

Accessing Headers

agent.on(AgentEvents.TRIGGER_EVENT, async ({ triggerBody }) => {
  // Access webhook sender's IP address
  const senderIP = triggerBody.headers?.['x-forwarded-for'];

  // Access other headers
  const contentType = triggerBody.headers?.['content-type'];
  const userAgent = triggerBody.headers?.['user-agent'];

  return { isQualified: true };
});

Common headers available:

  • x-forwarded-for - Original sender's IP address

  • content-type - Request content type

  • user-agent - Client user agent string

  • Custom headers sent by the webhook sender

PreviousToolsNextPlaybooks

Last updated