Developer Overview

What are plugins?

Plugins let you add new capabilities to the WhatsApp agent. A plugin can connect the agent to your CRM, order system, delivery service, booking system, accounting workflow, support desk, or internal business API.

When a plugin is installed and granted to a WhatsApp number instance, its tools become available to that WhatsApp number's agent. A WhatsApp number instance is one connected WhatsApp number plus its bot settings, prompt, knowledge base, integrations, and permissions.

Example: a law firm might have one WhatsApp number instance called "Legal Consultations" and another called "Billing Support." A legal research plugin can be granted only to "Legal Consultations" so the billing bot never receives that tool.

The agent can then call the granted plugin tools during a customer conversation when the tool description matches what the customer needs.

Examples:

• Look up a customer record.
• Create a support ticket.
• Check delivery availability.
• Book an appointment.
• Fetch warranty details.
• Push a paid order into a fulfillment system.
• Create a lead in a CRM.

Plugin building blocks

Every plugin has four parts:

The agent only receives tools from plugins that are active and granted to the active WhatsApp number instance.

Lifecycle

1. Author

You write a manifest that describes:

• Plugin name and slug.
• Version.
• Public base URL.
• Authentication mode.
• Tools and input schemas.
• Optional output schemas.
• Optional configuration fields.

2. Host

Host the manifest and the tool endpoint at stable HTTPS URLs. The endpoint should accept requests, verify the platform token, run the requested operation, and return a JSON result.

3. Install in sandbox

Install the plugin in sandbox mode from the developer area. Sandbox mode lets your organization test the plugin before publishing or sharing it.

4. Configure

If your manifest declares configuration fields, the installing organization fills them in during setup. Examples include workspace ID, region, API key, default queue, or default branch.

5. Grant to instances

After installation, grant the plugin to the WhatsApp number instances that should use it. A plugin installed for the organization is not automatically available to every WhatsApp number.

6. Test with real conversations

Send WhatsApp messages that should trigger the tool. Review plugin logs and agent behavior. Improve tool descriptions until the agent calls the right tool at the right time.

7. Publish or keep private

You can keep a plugin private to your organization or submit it for review if it should become available more broadly.

How the agent chooses plugin tools

The agent reads each tool's name, description, and input schema. It decides whether to call a tool based on:

• The customer's message.
• The WhatsApp number instance system prompt.
• The available tool descriptions.
• The current conversation context.
• Which toolkits and plugins are granted to the WhatsApp number instance.

Tool descriptions matter. Write them as operating instructions, not labels.

Good:

Look up a delivery by order number. Use this when a customer asks where their order is, asks for delivery ETA, or gives an order reference.

Weak:

Delivery lookup.

Permissions and plugins

Plugins participate in the same access model as toolkits.

The platform controls whether the agent can call the plugin. Your plugin should still enforce its own business rules for sensitive external actions.

Example: KasiLabs can decide whether the support WhatsApp number is allowed to call create_support_ticket. Your support plugin must still decide whether the ticket payload is valid and whether it should actually create the ticket in your external support system.

For example, a plugin that creates a delivery job should verify that the request contains a paid order reference. A plugin that updates an accounting system should reject unsupported changes. A plugin that books appointments should validate availability before confirming.

Plugins should not be used to bypass Payments, E-Commerce, escalation, or employee permissions. If a workflow touches money, fulfillment, customer support, or service access, design the plugin so it respects those boundaries.

Requesting plugin permissions

Declare the permissions your plugin needs in the manifest. These permissions explain the plugin's authority to admins during installation and review.

{
  "permissions": [
    {
      "key": "delivery:jobs:create",
      "label": "Create delivery jobs",
      "description": "Allows the agent to create delivery jobs in the connected delivery system after payment is confirmed."
    },
    {
      "key": "delivery:jobs:read",
      "label": "Read delivery status",
      "description": "Allows the agent to look up delivery status for customer orders.",
      "default": true
    }
  ]
}

Use namespaced keys that belong to your plugin or external system. Do not claim platform toolkit permissions as if your plugin owns them. For example, your delivery plugin can request delivery:jobs:create, but it should not claim toolkit:PAYMENTS:refund_manage.

If your workflow needs a platform toolkit, document that dependency clearly and require the merchant to grant the toolkit to the same WhatsApp number instance.

The agent can coordinate multiple tools in one flow only if all required toolkits and plugins are granted to that WhatsApp number instance.

Cross-toolkit workflows

Plugins often work together with toolkits.

The important rule:

Let each system own its own decision.

Payments owns payment confirmation. E-Commerce owns order and fulfillment state. Escalations own human handoff. Your plugin owns the external action it performs.

Dedicated platform bridges

Most plugin workflows should be agent-mediated: the agent calls your plugin, then the platform-owned systems handle payment, order state, scheduling, receipts, and escalation through their own controls.

Sometimes a plugin needs to ask KasiLabs for a deterministic platform action directly. For those cases, use a platform bridge. A bridge is a signed, permission-gated endpoint for one narrow platform action.

Current bridge families:

Bridge calls are recorded with idempotency keys so retries do not create duplicate orders, duplicate payment requests, or duplicate messages.

Use bridges when the plugin owns business context but KasiLabs owns the platform action. For example, Gas OS may know which gas order should be paid, but the Payments toolkit owns payment initiation and confirmation. Gas OS may know a delivery is overdue, but KasiLabs owns WhatsApp sending, scheduling, and escalation routing.

See Plugin Permissions for the permission model and Platform Bridges for endpoint payloads and the full Gas OS conversation example.

What data your plugin receives

A tool call includes:

• Tool name.
• Tool input selected by the agent.
• Organization identifier.
• WhatsApp number instance identifier.
• A privacy-preserving customer identifier.
• A short-lived current-chat bridge token when the tool call is happening inside a customer conversation.
• Installation configuration.
• Optional user authorization details if the plugin uses delegated account access.

The customer phone number is not sent as a raw identifier by default. Use the provided customer identifier for per-customer records unless your plugin explicitly collects customer contact details through a legitimate business flow.

What your plugin should return

Return compact JSON that helps the agent respond accurately.

Good response:

{
  "status": "found",
  "orderNumber": "MAT-2026-0510-0041",
  "deliveryStatus": "out_for_delivery",
  "eta": "Today between 3:00 PM and 5:00 PM"
}

Avoid returning long raw payloads, internal stack traces, secrets, or unrelated fields. The agent will use your response in a customer conversation, so return data that is safe and useful.

Design checklist

Before testing a plugin, confirm:

• The manifest has a clear name, slug, version, and description.
• Every tool has a specific description.
• Every tool has a strict input schema.
• Sensitive tools validate business rules server-side.
• The endpoint verifies platform tokens.
• Errors are clear and safe to show or summarize.
• The plugin is installed only where needed.
• The plugin is granted only to the right instances.
• The plugin does not expose secrets, raw customer identifiers, or internal implementation details.

Next steps

• Plugin Quick Start - Build and install a first plugin
• Manifest Reference - Define tools, configuration, and auth
• Plugin Permissions - Request and grant plugin authority safely
• Platform Bridges - Use deterministic bridge endpoints
• Authentication - Verify platform requests and delegated access
• Testing & Debugging - Test plugins safely
• Permissions & RBAC - Understand toolkit and plugin permissions