Functions cheatsheet

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.

Quickstart

# 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

Always return JSON for API responses
Handle errors gracefully with try/catch
Validate input before processing
Use appropriate status codes (200, 400, 404, 500)
Keep functions focused on a single task
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');
}

Overview

Functions

Function Secrets

App Accounts Proxy

Quickstart

Writing Functions

Platform Options

Cloudflare Workers Example

Supabase Functions Example

Available APIs

Cloudflare Workers APIs

Supabase Functions APIs

Environment Secrets

Cloudflare Workers Secrets

Supabase Functions Secrets

KV Storage

Example: WhatsApp Message Webhook

CLI Commands

`kapso functions push <file.js>`

`kapso functions list`

`kapso functions pull <name>`

Using Functions in Agents

Best Practices

Common Patterns

WhatsApp CRM Integration with Session Tracking

Overview

Functions

Function Secrets

App Accounts Proxy

​Quickstart

​Writing Functions

​Platform Options

​Cloudflare Workers Example

​Supabase Functions Example

​Available APIs

​Cloudflare Workers APIs

​Supabase Functions APIs

​Environment Secrets

​Cloudflare Workers Secrets

​Supabase Functions Secrets

​KV Storage

​Example: WhatsApp Message Webhook

​CLI Commands

​kapso functions push <file.js>

​kapso functions list

​kapso functions pull <name>

​Using Functions in Agents

​Best Practices

​Common Patterns

​WhatsApp CRM Integration with Session Tracking

Quickstart

Writing Functions

Platform Options

Cloudflare Workers Example

Supabase Functions Example

Available APIs

Cloudflare Workers APIs

Supabase Functions APIs

Environment Secrets

Cloudflare Workers Secrets

Supabase Functions Secrets

KV Storage

Example: WhatsApp Message Webhook

CLI Commands

`kapso functions push <file.js>`

`kapso functions list`

`kapso functions pull <name>`

Using Functions in Agents

Best Practices

Common Patterns

WhatsApp CRM Integration with Session Tracking