Kontato Workflow Engine Documentation

Table of Contents

1. Introduction
2. Core Concepts
3. Workflow API Reference
4. Integration with Kontato System
5. Example Workflows
6. Developer Guide
7. Best Practices

Introduction

The Kontato Workflow Engine is a powerful system that allows businesses to create customizable, event-driven workflows to automate customer interactions and business processes. This engine enables Kontato customers to define their own triggers, actions, and decision paths without requiring code changes to the core platform.

Key Benefits

• Flexibility: Create custom workflows tailored to your specific business needs
• No-code configuration: Define workflows through API calls (with visual designer planned for future)
• Context preservation: Store relevant data for AI Agent conversations
• Integration: Seamlessly works with existing Kontato features like WhatsApp messaging and AI Agents

Core Concepts

What is a Workflow?

A workflow is a defined sequence of steps that are executed in response to a trigger event. In the Kontato system, workflows allow you to automate processes like sending messages, storing data, making decisions, and more.

Each workflow consists of:

• Workflow Definition: The overall structure and metadata of the workflow
• Trigger: The event that initiates the workflow
• Steps: Individual actions or operations that make up the workflow
• Context Variables: Data that is stored and passed between steps

Workflow Definition

A workflow definition contains all the information needed to execute a workflow:

{
            "name": "Doban Lead First Contact v1",
            "description": "Stores lead data and sends a WhatsApp template message for Doban leads",
            "trigger": {
                "type": "webhook",
                "eventType": "lead_first_contact"
            },
            "steps": [
                {
                "id": "step1",
                "name": "Store Lead Basic Data",
                "type": "store_context_data",
                "config": {
                    "data": {
                    "leadSource": "{{trigger.eventType}}",
                    "leadTimestamp": "{{trigger.timestamp}}",
                    "customerName": "{{trigger.fullName}}",
                    "customer_message": "{{trigger.customer_message}}"
                    }
                },
                "outputVar": "leadData"
                },
      {
        "id": "step2",
        "name": "Store Companies Data",
        "type": "store_context_data",
        "config": {
          "data": {
            "companies": "{{trigger.companies}}"
          }
        },
        "outputVar": "companiesData"
      },

    // Store in conversation state for AI agents
    {
      "id": "step4",
      "name": "Store in Conversation State",
      "type": "store_conversation_state",
      "config": {
        "phoneNumber": "{{trigger.customerWhatsApp}}",
        "data": {
          "companies": "{{trigger.companies}}",
          "leadSource": "{{trigger.eventType}}",
          "initialIssue": "{{trigger.issue}}",
          "leadTimestamp": "{{trigger.timestamp}}"
        }
      }
    },

                {
                "id": "step4",
                "name": "Send WhatsApp Template",
                "type": "send_whatsapp_template",
                "config": {
                    "templateId": "lead_first_contact",
                    "languageCode": "pt_BR",
                    "phoneNumber": "{{trigger.customerWhatsApp}}",
                    "variables": {
                    "first_name": "{{trigger.firstName}}",
                    "attendent_name": "{{trigger.attendent_name}}",
                    "company_name": "{{trigger.company_name}}",
                    "lead_interest": "{{trigger.lead_interest}}",
                    "customer_message": "{{trigger.customer_message}}"
                    }
                }
                }
            ],
            "contextVariables": ["leadData"]
}

Triggers

A trigger is an event that initiates a workflow. In Kontato, triggers can be:

• Webhook events: External systems sending data to Kontato
• Customer messages: New messages from customers
• Time-based events: Scheduled triggers at specific times
• Manual execution: Workflows triggered by admin users

Each trigger type has specific properties that define when the workflow should run.

Steps

A step is a single action or operation within a workflow. Steps are executed in sequence, and each step can:

• Perform an action (send a message, store data, etc.)
• Make decisions based on conditions
• Execute custom code
• Call external services

Each step has:

• Type: The kind of action to perform
• Configuration: Parameters specific to the step type
• Output Variable (optional): Where to store the result of the step

Step Types

The Kontato Workflow Engine supports various step types:

Step Type	Description
send_whatsapp_template	Sends a WhatsApp template message
send_whatsapp_message	Sends a custom WhatsApp message
send_email	Sends an email
make_phone_call	Initiates a phone call
store_context_data	Stores data in the workflow context
conditional	Executes different steps based on conditions
delay	Waits for a specified time before continuing
webhook	Calls an external webhook
custom_code	Executes custom JavaScript code

Context and State

The workflow engine maintains a context object throughout the execution of a workflow. This context includes:

• Trigger Data: Information from the event that triggered the workflow
• State: Data that persists between steps
• Variables: Named outputs from previous steps

This context allows steps to share data and build on each other's results.

Variable Resolution

The workflow engine supports variable resolution in step configurations using the

json{{variable}}

syntax. For example:

{
  "type": "send_whatsapp_template",
  "config": {
    "templateId": "first_contact_charge_workflow",
    "phoneNumber": "{{trigger.phoneNumber}}",
    "variables": {
      "first_name": "{{trigger.fullName.split(' ')[0]}}"
    }
  }
}

Variables can reference:
- Trigger data: `{{trigger.fieldName}}`
- State data: `{{state.fieldName}}`
- Step outputs: `{{variables.stepOutputName}}`

Workflow API Reference

The Kontato Workflow API provides endpoints for managing workflows:

List Workflows

// Get all workflows for a store
const getWorkflows = async (storeId, token) => {
  const response = await fetch(`https://api.kontato.com/api/workflows`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${token}`,
      'StoreId': storeId
    }
  });
  return await response.json();
};

Get Workflow

// Get a specific workflow
const getWorkflow = async (workflowId, storeId, token) => {
  const response = await fetch(`https://api.kontato.com/api/workflows/${workflowId}`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${token}`,
      'StoreId': storeId
    }
  });
  return await response.json();
};

Create Workflow

// Create a new workflow
const createWorkflow = async (workflowData, storeId, token) => {
  const response = await fetch(`https://api.kontato.com/api/workflows`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'StoreId': storeId,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(workflowData)
  });
  return await response.json();
};

// Example workflow data
const workflowData = {
  "name": "Lead Follow-up Workflow",
  "description": "Sends a WhatsApp template message to new leads",
  "trigger": {
    "type": "webhook",
    "eventType": "Lead_Workflow_phase_1"
  },
  "steps": [
    {
      "id": "step1",
      "name": "Store Lead Data",
      "type": "store_context_data",
      "config": {
        "data": {
          "leadSource": "{{trigger.eventType}}",
          "leadTimestamp": "{{trigger.timestamp}}"
        }
      },
      "outputVar": "leadData"
    },
    {
      "id": "step2",
      "name": "Send WhatsApp Template",
      "type": "send_whatsapp_template",
      "config": {
        "templateId": "first_contact_charge_workflow",
        "languageCode": "pt_BR",
        "phoneNumber": "{{trigger.phoneNumber}}",
        "fullName": "{{trigger.fullName}}",
        "email": "{{trigger.email}}",
        "variables": {
          "first_name": "{{trigger.fullName.split(' ')[0]}}",
          "attendent_name": "Atendente da Kontato",
          "issue": "{{trigger.issue}}"
        }
      }
    }
  ],
  "contextVariables": ["leadData"]
};

Update Workflow

// Update an existing workflow
const updateWorkflow = async (workflowId, workflowData, storeId, token) => {
  const response = await fetch(`https://api.kontato.com/api/workflows/${workflowId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'StoreId': storeId,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(workflowData)
  });
  return await response.json();
};

Delete Workflow

// Delete a workflow
const deleteWorkflow = async (workflowId, storeId, token) => {
  const response = await fetch(`https://api.kontato.com/api/workflows/${workflowId}`, {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${token}`,
      'StoreId': storeId
    }
  });
  return await response.json();
};

Execute Workflow Manually

// Execute a workflow manually
const executeWorkflow = async (workflowId, triggerData, storeId, token) => {
  const response = await fetch(`https://api.kontato.com/api/workflows/${workflowId}/execute`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'StoreId': storeId,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(triggerData)
  });
  return await response.json();
};

// Example trigger data
const triggerData = {
  "phoneNumber": "5511999999999",
  "fullName": "John Doe",
  "email": "[email protected]",
  "issue": "Interested in your product",
  "eventType": "Lead_Workflow_phase_1"
};

Integration with Kontato System

The Workflow Engine is deeply integrated with the Kontato system:

Webhook Integration

Integration with Kontato AI

The Workflow Engine can store context data that is available to Kontato AI Agents during conversations. This enables AI Agents to have awareness of previous workflow steps and data when interacting with customers.

Example Workflows

Lead Follow-up Workflow

This workflow sends a WhatsApp template message to new leads and stores their information:

{
  "name": "Lead Follow-up Workflow",
  "description": "Sends a WhatsApp template message to new leads",
  "trigger": {
    "type": "webhook",
    "eventType": "Lead_Workflow_phase_1"
  },
  "steps": [
    {
      "id": "step1",
      "name": "Store Lead Data",
      "type": "store_context_data",
      "config": {
        "data": {
          "leadSource": "{{trigger.eventType}}",
          "leadTimestamp": "{{trigger.timestamp}}"
        }
      },
      "outputVar": "leadData"
    },
    {
      "id": "step2",
      "name": "Send WhatsApp Template",
      "type": "send_whatsapp_template",
      "config": {
        "templateId": "first_contact_charge_workflow",
        "languageCode": "pt_BR",
        "phoneNumber": "{{trigger.phoneNumber}}",
        "fullName": "{{trigger.fullName}}",
        "email": "{{trigger.email}}",
        "variables": {
          "first_name": "{{trigger.fullName.split(' ')[0]}}",
          "attendent_name": "Atendente da {{store.name}}",
          "issue": "{{trigger.issue}}"
        }
      }
    },
    {
      "id": "step3",
      "name": "Check Companies Data",
      "type": "conditional",
      "config": {
        "condition": "context.trigger.companies && context.trigger.companies.length > 0",
        "then": {
          "id": "step3a",
          "name": "Store Companies Data",
          "type": "store_context_data",
          "config": {
            "data": {
              "companies": "{{trigger.companies}}"
            }
          },
          "outputVar": "companiesData"
        }
      }
    }
  ],
  "contextVariables": [
    "leadData",
    "companiesData"
  ]
}

Abandoned Cart Recovery Workflow

This workflow sends a reminder to customers who abandoned their shopping cart:

{
  "name": "Abandoned Cart Recovery",
  "description": "Sends a reminder to customers who abandoned their cart",
  "trigger": {
    "type": "webhook",
    "eventType": "cart_abandoned"
  },
  "steps": [
    {
      "id": "step1",
      "name": "Store Cart Data",
      "type": "store_context_data",
      "config": {
        "data": {
          "cartId": "{{trigger.cartId}}",
          "cartValue": "{{trigger.cartValue}}",
          "productCount": "{{trigger.items.length}}",
          "abandonedAt": "{{trigger.timestamp}}"
        }
      },
      "outputVar": "cartData"
    },
    {
      "id": "step2",
      "name": "Wait 1 Hour",
      "type": "delay",
      "config": {
        "delayMinutes": 60
      }
    },
    {
      "id": "step3",
      "name": "Send Cart Recovery Message",
      "type": "send_whatsapp_template",
      "config": {
        "templateId": "cart_recovery",
        "languageCode": "pt_BR",
        "phoneNumber": "{{trigger.phoneNumber}}",
        "variables": {
          "first_name": "{{trigger.customerName.split(' ')[0]}}",
          "cart_value": "R$ {{trigger.cartValue}}",
          "recovery_link": "{{trigger.recoveryUrl}}"
        }
      }
    }
  ],
  "contextVariables": ["cartData"]
}

Customer Onboarding Workflow

This workflow guides new customers through an onboarding process:

{
  "name": "Customer Onboarding",
  "description": "Guides new customers through onboarding steps",
  "trigger": {
    "type": "webhook",
    "eventType": "new_customer"
  },
  "steps": [
    {
      "id": "step1",
      "name": "Send Welcome Message",
      "type": "send_whatsapp_template",
      "config": {
        "templateId": "welcome_message",
        "languageCode": "pt_BR",
        "phoneNumber": "{{trigger.phoneNumber}}",
        "variables": {
          "customer_name": "{{trigger.fullName.split(' ')[0]}}",
          "company_name": "{{store.name}}"
        }
      }
    },
    {
      "id": "step2",
      "name": "Wait 1 Day",
      "type": "delay",
      "config": {
        "delayMinutes": 1440
      }
    },
    {
      "id": "step3",
      "name": "Send Product Guide",
      "type": "send_email",
      "config": {
        "to": "{{trigger.email}}",
        "subject": "Your Guide to Getting Started",
        "template": "product_guide",
        "variables": {
          "customer_name": "{{trigger.fullName}}",
          "product_link": "https://example.com/guide"
        }
      }
    },
    {
      "id": "step4",
      "name": "Wait 3 Days",
      "type": "delay",
      "config": {
        "delayMinutes": 4320
      }
    },
    {
      "id": "step5",
      "name": "Send Follow-up Message",
      "type": "send_whatsapp_message",
      "config": {
        "phoneNumber": "{{trigger.phoneNumber}}",
        "message": "Hi {{trigger.fullName.split(' ')[0]}}, how are you finding our product so far? Do you have any questions I can help with?"
      }
    }
  ],
  "contextVariables": []
}

Best Practices

Workflow Design

1. Keep workflows focused: Each workflow should have a clear purpose
2. Use descriptive names: Name workflows and steps clearly
3. Store context data: Use store_context_data steps to preserve important information
4. Handle errors: Add error handlers to critical steps
5. Test thoroughly: Test workflows with various inputs before deploying

Performance Considerations

1. Limit workflow complexity: Avoid creating workflows with too many steps
2. Be careful with custom code: Custom code steps can impact performance
3. Use conditional steps: Skip unnecessary steps based on conditions
4. Consider delay impact: Be aware that delay steps will pause workflow execution

Security Considerations

1. Validate input data: Don't trust trigger data without validation
2. Limit custom code: Custom code steps can introduce security risks
3. Use appropriate permissions: Ensure workflows only have access to necessary resources
4. Audit workflow execution: Monitor workflow execution for unexpected behavior

---

This documentation provides a comprehensive overview of the Kontato Workflow Engine, its concepts, API, integration points, and best practices.