Skip to main content

Chatbot Workflow Example

This example demonstrates how to build a complete chatbot workflow that receives user messages, processes them with AI, and returns responses via PubSub.

Overview​

A typical chatbot workflow follows this pattern:

Event (Chat Message) → Prompt (AI Response) → Action (Publish to PubSub)

Step 1: Create the Event Entity​

The Event entity is the entry point that filters incoming messages to only process chat messages.

Entity Configuration:

  • Name: "Start of Chat"
  • Type: Event
  • Condition Mode: Single Path (all matching messages follow one path)

Condition Configuration:

{
  "type": "group",
  "operator": "AND",
  "conditions": [
    {
      "type": "rule",
      "field": "message.type",
      "comparison": "equals",
      "value": "chat"
    }
  ]
}

This condition ensures only messages with message.type === "chat" trigger the workflow.

Step 2: Create the Prompt Entity​

The Prompt entity calls an AI model to generate a response based on the user's message.

Entity Configuration:

  • Name: "Generate Chat Response"
  • Type: Prompt
  • Model: Select your configured AI model (e.g., GPT-4, Claude)

Prompt Template (using Handlebars):

You are a helpful assistant. Respond to the following user message:

User: {{message.content}}

Provide a helpful, concise response.

The {{message.content}} template variable is replaced with the actual user message at runtime.

Step 3: Create the Action Entity​

The Action entity publishes the AI response back to the client via Redis PubSub.

Entity Configuration:

  • Name: "Return Chat Response via PubSub"
  • Type: Action

Script:

// Get the AI response from the prompt
const aiResponse = await latestPromptResponse();

if (aiResponse) {
  // Build the response payload
  const responsePayload = {
    type: 'chat-response',
    content: aiResponse,
    correlationId: message.correlationId,
    timestamp: new Date().toISOString()
  };

  // Publish to the chat channel using the correlation ID
  // The channel format must match what the client is subscribed to
  const channel = "chat:" + message.correlationId;
  
  // pubsubPublish expects string arguments
  await pubsubPublish(channel, JSON.stringify(responsePayload));
  
  print('Published response to channel:', channel);
} else {
  print('No AI response available to publish');
}

Key Points:

  • latestPromptResponse() retrieves the most recent AI response from the workflow
  • pubsubPublish(channel, message) publishes to Redis - both arguments must be strings
  • The channel name must match what the client subscribes to (typically chat:{correlationId})
  • Use JSON.stringify() to convert objects to strings before publishing

Complete Workflow Data Structure​

Here's the complete workflowData JSON that connects these entities:

{
  "nodes": {
    "n1": {
      "entityId": "your-event-entity-uuid",
      "name": "Start of Chat",
      "entityType": "event",
      "tfCondition": "Single Path",
      "presentation": {
        "type": "circle",
        "position": { "x": 100, "y": 200 }
      }
    },
    "n2": {
      "entityId": "your-prompt-entity-uuid",
      "name": "Generate Chat Response",
      "entityType": "prompt",
      "presentation": {
        "type": "brain",
        "position": { "x": 350, "y": 200 }
      }
    },
    "n3": {
      "entityId": "your-action-entity-uuid",
      "name": "Return Chat Response via PubSub",
      "entityType": "action",
      "presentation": {
        "type": "star",
        "position": { "x": 600, "y": 200 }
      }
    }
  },
  "connectors": {
    "c1": {
      "source": "n1",
      "target": "n2",
      "sourcePort": "out",
      "targetPort": "in"
    },
    "c2": {
      "source": "n2",
      "target": "n3",
      "sourcePort": "out",
      "targetPort": "in"
    }
  },
  "workflow": {
    "ref": "n1",
    "children": [
      {
        "ref": "n2",
        "children": [
          {
            "ref": "n3",
            "children": []
          }
        ]
      }
    ]
  },
  "presentation": {
    "viewport": { "x": 0, "y": 0, "zoom": 100 }
  }
}

Message Format​

The incoming message from the chat API should have this structure:

{
  "type": "chat",
  "content": "What is the weather today?",
  "correlationId": "uuid-for-this-chat-session",
  "organizationId": "your-org-id",
  "environmentId": "your-env-id",
  "timestamp": "2025-01-08T12:00:00.000Z"
}

Workflow Outcomes​

When the workflow completes, the outcome is determined automatically:

OutcomeCondition
SuccessAll entities execute without errors
ErrorA script throws an error or times out
IgnoreEvent condition doesn't match

Testing the Workflow​

  1. Create all entities in the Admin Console under your organization/environment
  2. Create the workflow and drag entities onto the canvas
  3. Connect the nodes by dragging from output ports to input ports
  4. Save and activate the workflow
  5. Send a test message via the Chat API or directly to Kinesis

Common Issues​

"pubsubPublish is not defined"​

Ensure you're using pubsubPublish (not publishToPubSub). Check the script function reference.

"A non-transferable value was passed"​

The pubsubPublish function requires string arguments. Use JSON.stringify() for objects.

Chat response not received​

  1. Verify the channel name matches: chat:{correlationId}
  2. Check that the client is subscribed before the message is published
  3. Verify Redis connectivity in both admin and consumer services