Flow nodes

Building blocks for WhatsApp workflows

Node types

StartNode

Entry point of the flow.

from kapso.builder.flows.nodes import StartNode

node = StartNode(id="start_1234")

SendTextNode

Send WhatsApp text messages.

from kapso.builder.flows.nodes import SendTextNode
from kapso.builder.ai.field import AIField

# Static message
node = SendTextNode(
    id="send_text_1234",
    message="Hello! How can I help you today?"
)

# AI-generated message
node = SendTextNode(
    id="send_text_5678",
    message=AIField("Personalize greeting based on customer history"),
    provider_model_name="claude-sonnet-4-20250514"
)

WaitForResponseNode

Wait for user input.

from kapso.builder.flows.nodes import WaitForResponseNode

node = WaitForResponseNode(
    id="wait_1234"
)

DecideNode

Route flows with AI or custom logic.

from kapso.builder.flows.nodes import DecideNode
from kapso.builder.flows.nodes.decide import Condition

# AI-powered: AI interprets user intent
node = DecideNode(
    id="decide_1234",
    decision_type="ai",  # Default, can be omitted
    provider_model_name="claude-sonnet-4-20250514",
    conditions=[
        Condition(label="urgent", description="Customer issue is urgent"),
        Condition(label="general", description="General inquiry or question"),
        Condition(label="billing", description="Billing or payment related")
    ],
    llm_temperature=0.0,
    llm_max_tokens=100
)

# Function: Run your routing logic
node = DecideNode(
    id="decide_5678",
    decision_type="function",
    function_id="7c9e6679-7425-40de-944b-e07fc1f90ae7",  # UUID of deployed function
    conditions=[
        Condition(label="premium", description="Premium tier route"),
        Condition(label="standard", description="Standard tier route"),
        Condition(label="trial", description="Trial user route")
    ]
    # No AI parameters needed for function mode
)

Configuration:

• AI mode: Requires provider_model_name, optional llm_temperature and llm_max_tokens
• Function mode: Requires function_id (UUID), AI parameters are ignored

Your function receives execution_context, flow_events, and available_edges[]. Run any logic you want (business rules, data checks, API calls) and return { next_edge: "label", vars: {...} }.

AgentNode

Embedded AI agent with tools.

from kapso.builder.flows.nodes import AgentNode
from kapso.builder.flows.nodes.agent import FlowAgentWebhook, FlowAgentMcpServer

webhooks = [
    FlowAgentWebhook(
        name="check_order",
        url="https://api.store.com/orders/{{order_id}}",
        description="Get order status by ID",
        http_method="GET"
    )
]

mcp_servers = [
    FlowAgentMcpServer(
        name="Context Server",
        url="https://mcp.context7.ai/v1",
        description="Documentation and knowledge access",
        headers={"Authorization": "Bearer token123"}
    )
]  # HTTP streamable transport only

node = AgentNode(
    id="agent_1234",
    system_prompt="You are a customer service agent. Help with orders.",
    provider_model_name="claude-sonnet-4-20250514",
    temperature=0.1,
    max_iterations=10,
    max_tokens=2000,
    reasoning_effort="medium",
    webhooks=webhooks,
    mcp_servers=mcp_servers
)

# POST webhook example with request schema
import json

create_ticket = FlowAgentWebhook(
    name="create_support_ticket",
    url="https://api.support.com/tickets",
    http_method="POST",
    description="Create a support ticket with subject and body",
    headers={"Content-Type": "application/json"},
    body={
        "subject": "{{vars.issue_subject}}",
        "body": "{{last_user_input}}",
        "priority": "high",
    },
    body_schema=json.dumps(
        {
            "type": "object",
            "properties": {
                "subject": {"type": "string"},
                "body": {"type": "string"},
                "priority": {"type": "string", "enum": ["low", "medium", "high"]},
            },
            "required": ["subject", "body"],
        }
    ),
    jmespath_query="data.ticket_id",
)

AgentNode(
    id="support_agent",
    system_prompt="Log tickets for users and share the ticket ID.",
    provider_model_name="claude-sonnet-4-20250514",
    webhooks=[create_ticket]
)

Use body_schema to describe the payload you want the LLM to fill. Supply body only when you have fixed values or stored variables you want to send verbatim. Typically you use one or the other—avoid setting both unless you’re intentionally seeding a constant field alongside a schema-generated payload.

SendTemplateNode

WhatsApp template messages.

from kapso.builder.flows.nodes import SendTemplateNode
from kapso.builder.ai.field import AIField

node = SendTemplateNode(
    id="template_1234",
    template_id="order_confirmation",
    parameters={
        "1": "{{customer_name}}",
        "2": AIField("Extract order number from conversation")
    },
    provider_model_name="claude-sonnet-4-20250514"  # Required for AIField
)

SendInteractiveNode

Interactive lists and buttons.

from kapso.builder.flows.nodes import SendInteractiveNode
from kapso.builder.flows.nodes.send_interactive import (
    InteractiveButton,
    ListRow,
    ListSection,
)
from kapso.builder.ai.field import AIField

# Button message with helper buttons
node = SendInteractiveNode(
    id="interactive_1234",
    interactive_type="button",
    body_text="How can we help you today?",
    header_type="text",
    header_text="Support Menu",
    buttons=[
        InteractiveButton(id="support", title="Support"),
        InteractiveButton(id="sales", title="Sales"),
    ],
)

# List message with AI content
node = SendInteractiveNode(
    id="interactive_5678",
    interactive_type="list",
    body_text=AIField("Create personalized menu options"),
    list_button_text="View options",
    list_sections=[
        ListSection(
            title="Assistance",
            rows=[
                ListRow(id="tech", title="Technical Support"),
                ListRow(id="billing", title="Billing", description="Invoices and payments"),
            ],
        )
    ],
    provider_model_name="claude-sonnet-4-20250514",
)

FunctionNode

Call serverless functions.

from kapso.builder.flows.nodes import FunctionNode

node = FunctionNode(
    id="function_1234",
    function_id="func_calculate_shipping_789",
    save_response_to="shipping_cost"
)

HandoffNode

Transfer to human agent.

from kapso.builder.flows.nodes import HandoffNode

node = HandoffNode(
    id="handoff_1234"
)

AIField support

These nodes support AIField for dynamic content:

• SendTextNode: message parameter
• SendTemplateNode: parameters values
• SendInteractiveNode: body_text, header_text, footer_text

When using AIField, always provide provider_model_name.