Kapso Functions are serverless JavaScript functions that deploy instantly and scale automatically. Choose between Cloudflare Workers or Supabase Functions platforms. Perfect for webhooks, API integrations, and custom business logic.

​
Quick Start

# Set your API key (no project setup needed!)
export KAPSO_API_KEY=your-api-key

# Create a function
echo 'async function handler(request) {
  return new Response("Hello World");
}' > hello.js

# Deploy to Cloudflare Workers (default)
kapso functions push hello.js

# Deploy to Supabase Functions (requires Supabase integration)
kapso functions push hello.js --platform supabase

# List your functions
kapso functions list

​
Writing Functions

​
Platform Options

Cloudflare Workers (default): High-performance edge computing with global distribution Supabase Functions: Deno-based functions with direct database access and built-in authentication Both platforms support modern JavaScript syntax:

​
Cloudflare Workers Example

async function handler(request, env) {
  // Parse JSON body
  const body = await request.json();
  
  // Use KV storage for persistence
  await env.KV.put('last-visitor', body.name);
  const lastVisitor = await env.KV.get('last-visitor');
  
  // Process the data
  const result = {
    message: `Hello ${body.name}!`,
    lastVisitor: lastVisitor,
    timestamp: new Date().toISOString()
  };
  
  // Return JSON response
  return new Response(JSON.stringify(result), {
    headers: { 'Content-Type': 'application/json' }
  });
}

​
Supabase Functions Example

Deno.serve(async (req) => {
  // Initialize Supabase client with auth context
  const supabaseClient = createClient(
    Deno.env.get('SUPABASE_URL'),
    Deno.env.get('SUPABASE_ANON_KEY'),
    {
      global: {
        headers: { Authorization: req.headers.get('Authorization') || '' },
      },
    }
  )

  // Parse request body
  const body = await req.json().catch(() => ({}))
  
  // Direct database access
  const { data, error } = await supabaseClient
    .from('visitors')
    .insert({
      ip: req.headers.get('x-forwarded-for') || 'unknown',
      user_agent: req.headers.get('user-agent') || 'unknown',
      visited_at: new Date().toISOString(),
      data: body
    })
    .select()
    .single()

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 400,
      headers: { 'Content-Type': 'application/json' }
    })
  }

  return new Response(JSON.stringify({
    message: "Hello from Supabase Function!",
    timestamp: new Date().toISOString(),
    visitor: data
  }), {
    headers: { 'Content-Type': 'application/json' }
  })
})

​
Available APIs

​
Cloudflare Workers APIs

Functions run on Cloudflare Workers with access to:
  • fetch() - Make HTTP requests
  • Request/Response - Handle HTTP
  • URL/URLSearchParams - Parse URLs
  • crypto.randomUUID() - Generate IDs
  • TextEncoder/TextDecoder - Text encoding
  • env.KV - Persistent key-value storage
  • env.YOUR_SECRET - Access encrypted secrets (set in web app)
  • Standard JavaScript APIs

​
Supabase Functions APIs

Functions run on Deno with access to:
  • All Deno standard library modules
  • Deno.env.get() - Environment variables and secrets
  • createClient() - Supabase client with auth context
  • Direct PostgreSQL database access via Supabase client
  • Built-in user authentication and RLS
  • fetch() and standard Web APIs

​
Environment Secrets

Functions can access encrypted environment variables for API keys and sensitive configuration. Secrets are set in the web app on the function’s page (Secrets tab):

​
Cloudflare Workers Secrets

async function handler(request, env) {
  // Access your secrets via env parameter
  const apiKey = env.API_KEY;
  const dbUrl = env.DATABASE_URL;
  const webhookSecret = env.WEBHOOK_SECRET;
  
  // Use them in your function
  const response = await fetch('https://api.example.com/data', {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  
  return new Response('Success');
}

​
Supabase Functions Secrets

Deno.serve(async (req) => {
  // Access your secrets via Deno.env.get()
  const apiKey = Deno.env.get('API_KEY');
  const dbUrl = Deno.env.get('DATABASE_URL');
  const webhookSecret = Deno.env.get('WEBHOOK_SECRET');
  
  // Use them in your function
  const response = await fetch('https://api.example.com/data', {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  
  return new Response('Success');
})
Important:
  • Secrets must be set in the Kapso web app (function page → Secrets tab)
  • Secret names should use UPPERCASE_WITH_UNDERSCORES
  • Values are encrypted and never exposed after creation
  • Functions must be deployed before adding secrets

​
KV Storage

Each project has its own KV namespace for persistent data storage: 
// Store data (with optional expiration)
await env.KV.put('user:123', JSON.stringify(userData));
await env.KV.put('session', token, { expirationTtl: 3600 }); // 1 hour

// Retrieve data
const user = await env.KV.get('user:123', { type: 'json' });
const session = await env.KV.get('session');

// Delete data
await env.KV.delete('user:123');

// List keys with prefix
const list = await env.KV.list({ prefix: 'user:' });

​
Example: WhatsApp Message Webhook

async function handler(request, env) {
  try {
    // Verify webhook signature for security
    const signature = request.headers.get('X-Webhook-Signature');
    const secret = env.WEBHOOK_SECRET; // Set in Secrets tab in web app
    
    // Parse the webhook payload
    const webhook = await request.json();
    
    // Handle different WhatsApp events
    const eventType = request.headers.get('X-Webhook-Event');
    
    switch (eventType) {
      case 'whatsapp.message.received':
        // Process incoming WhatsApp message
        const { message, conversation, whatsapp_config } = webhook;
        
        console.log(`New message from ${message.phone_number}: ${message.content}`);
        
        // Store conversation history in KV
        const history = await env.KV.get(`conversation:${conversation.id}`, { type: 'json' }) || [];
        history.push({
          timestamp: new Date().toISOString(),
          phone: message.phone_number,
          content: message.content
        });
        await env.KV.put(`conversation:${conversation.id}`, JSON.stringify(history));
        
        // Send to your CRM or ticketing system
        await fetch('https://api.yourcrm.com/messages', {
          method: 'POST',
          headers: { 
            'Authorization': `Bearer ${env.CRM_API_KEY}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            phone: message.phone_number,
            message: message.content,
            whatsapp_message_id: message.whatsapp_message_id,
            conversation_id: conversation.id,
            message_count: history.length
          })
        });
        break;
      
      case 'whatsapp.conversation.created':
        // New conversation started
        console.log(`New conversation with ${webhook.conversation.phone_number}`);
        break;
        
      case 'whatsapp.message.failed':
        // Handle failed message delivery
        console.error(`Message failed: ${webhook.message.id}`);
        break;
    }
    
    // Always return 200 to acknowledge receipt
    return new Response('OK', { status: 200 });
    
  } catch (error) {
    console.error('Webhook processing error:', error);
    // Return 200 even on error to prevent retries for bad data
    return new Response('Error logged', { status: 200 });
  }
}

​
CLI Commands

​
kapso functions push <file.js>

Upload or update a function. The function name is derived from the filename. 
# Create or update function (Cloudflare Workers - default)
kapso functions push process-order.js

# Deploy to Supabase Functions
kapso functions push process-order.js --platform supabase

# Use custom name
kapso functions push utils/helper.js --name my-helper --platform cloudflare

​
kapso functions list

List all functions with their status and invoke URLs. 
kapso functions list

# Output:
# NAME              PLATFORM     STATUS     UPDATED      INVOKE URL
# process-order     Cloudflare   deployed   2 min ago    https://app.kapso.ai/api/v1/functions/abc123/invoke
# send-email        Supabase     deployed   1 hour ago   https://app.kapso.ai/api/v1/functions/def456/invoke

​
kapso functions pull <name>

Download a function from Kapso. 
# Download to functions directory
kapso functions pull process-order

# Download to specific location
kapso functions pull process-order -o my-function.js

​
Using Functions in Agents

Call functions from your agents using SubagentNode with WebhookTool: 
from kapso.builder.nodes import SubagentNode
from kapso.builder.nodes.subagent import WebhookTool

# Create a SubagentNode
assistant = SubagentNode(
    name="assistant",
    prompt="Help users with their inquiries"
)

# Add your function as a webhook tool
assistant.add_tool(WebhookTool(
    name="process_whatsapp_webhook",
    url="https://app.kapso.ai/api/v1/functions/abc123/invoke",
    http_method="POST",
    description="Process WhatsApp message webhooks",
    headers={"X-API-Key": "#{KAPSO_API_KEY}"},
    body_schema={
        "type": "object",
        "properties": {
            "message": {
                "type": "object",
                "properties": {
                    "content": {"type": "string"},
                    "phone_number": {"type": "string"},
                    "message_type": {"type": "string"}
                }
            },
            "conversation": {
                "type": "object",
                "properties": {
                    "id": {"type": "string"},
                    "status": {"type": "string"}
                }
            }
        },
        "required": ["message", "conversation"]
    }
))

​
Best Practices

  1. Always return JSON for API responses
  2. Handle errors gracefully with try/catch
  3. Validate input before processing
  4. Use appropriate status codes (200, 400, 404, 500)
  5. Keep functions focused on a single task
  6. Log important events with console.log()

​
Common Patterns

​
WhatsApp CRM Integration with Session Tracking

async function handler(request, env) {
  const webhook = await request.json();
  
  // Only process message received events
  if (request.headers.get('X-Webhook-Event') !== 'whatsapp.message.received') {
    return new Response('OK');
  }
  
  // Extract customer info
  const { message, conversation } = webhook;
  const customerPhone = message.phone_number;
  
  // Track customer session in KV
  const sessionKey = `session:${customerPhone}`;
  const session = await env.KV.get(sessionKey, { type: 'json' }) || {
    firstContact: new Date().toISOString(),
    messageCount: 0
  };
  
  session.lastMessage = message.content;
  session.lastContact = new Date().toISOString();
  session.messageCount++;
  
  // Store session with 24-hour expiration
  await env.KV.put(sessionKey, JSON.stringify(session), {
    expirationTtl: 86400 // 24 hours
  });
  
  // Create or update CRM contact with session data
  await fetch('https://api.hubspot.com/contacts/v1/contact', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${env.HUBSPOT_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      properties: [
        { property: 'phone', value: customerPhone },
        { property: 'last_whatsapp_message', value: message.content },
        { property: 'whatsapp_conversation_id', value: conversation.id },
        { property: 'total_messages', value: session.messageCount },
        { property: 'first_contact_date', value: session.firstContact }
      ]
    })
  });
  
  return new Response('OK');
}