Plugin Quick Start

What you will build

In this guide you will create a simple support plugin with one tool: create_support_ticket. When a customer needs human follow-up, the WhatsApp agent can call the plugin, receive a ticket reference, and continue the conversation with that reference.

In KasiLabs, a WhatsApp number instance means one connected WhatsApp number and its bot settings. For example, a business might have one WhatsApp number instance for sales and another for support. A plugin must be granted to the specific WhatsApp number instance where the agent should use it.

This example is intentionally business-oriented. The same pattern works for CRM, delivery, bookings, inventory, accounting, and internal workflow plugins.

Step 1: Create the manifest

Create a public manifest file:

{
  "slug": "SUPPORT_DESK",
  "version": "1.0.0",
  "name": "Support Desk",
  "description": "Creates and looks up customer support tickets.",
  "baseUrl": "https://plugins.example.com/support-desk",
  "auth": {
    "type": "secret"
  },
  "permissions": [
    {
      "key": "support:tickets:create",
      "label": "Create support tickets",
      "description": "Allows the agent to create customer support tickets in the connected support desk.",
      "default": true
    },
    {
      "key": "support:tickets:read",
      "label": "Read support ticket status",
      "description": "Allows the agent to look up existing support ticket status."
    }
  ],
  "configurationSchema": {
    "type": "object",
    "properties": {
      "defaultQueue": {
        "type": "string",
        "description": "Default support queue for new tickets."
      }
    },
    "required": ["defaultQueue"]
  },
  "tools": [
    {
      "name": "create_support_ticket",
      "description": "Create a support ticket when a customer needs human follow-up, reports a problem, asks for a complaint reference, or needs a case tracked outside the WhatsApp conversation.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "customerName": {
            "type": "string",
            "description": "Customer name if available."
          },
          "summary": {
            "type": "string",
            "description": "Short summary of the issue."
          },
          "priority": {
            "type": "string",
            "enum": ["low", "normal", "high"],
            "description": "Ticket priority."
          }
        },
        "required": ["summary"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "ticketId": { "type": "string" },
          "status": { "type": "string" },
          "message": { "type": "string" }
        }
      }
    }
  ]
}

Host it at a stable HTTPS URL such as:

https://plugins.example.com/support-desk/manifest.json

Step 2: Build the tool endpoint

Your plugin endpoint receives tool calls at the path defined in the manifest. If no custom path is defined, the default path is /execute.

A tool call is the moment the AI agent asks your plugin to do one specific job. In this example, the customer says their order arrived damaged, the agent decides a tracked support case is needed, and then the agent calls create_support_ticket with a short summary of the issue.

Expected request shape:

{
  "tool": "create_support_ticket",
  "input": {
    "customerName": "Amina Wanjiru",
    "summary": "Customer says their delivered item arrived damaged.",
    "priority": "normal"
  },
  "context": {
    "organizationId": "org_123",
    "instanceId": "inst_456",
    "user": {
      "id": "customer_hash",
      "hashVersion": 1
    },
    "config": {
      "defaultQueue": "customer-care"
    }
  }
}

Your endpoint should:

1. Verify the platform token.
2. Check the tool name.
3. Validate the input.
4. Perform the business action.
5. Return a compact JSON response.

Example response:

{
  "ticketId": "SUP-10421",
  "status": "created",
  "message": "Ticket SUP-10421 was created in the customer-care queue."
}

Step 3: Install in sandbox mode

1. Open the developer area in the dashboard.
2. Choose Install Sandbox Plugin.
3. Paste the manifest URL.
4. Review the plugin details and tools.
5. Fill any configuration fields.
6. Save the generated sandbox secret securely.

Sandbox plugins are private to your organization and can be tested with real conversations before publishing.

Step 4: Review requested permissions

During installation, review the plugin permissions declared in the manifest.

For this support plugin:

These two permissions are plugin-owned permissions. They describe what the Support Desk plugin can do in the external support system. By themselves, they do not install or grant platform toolkits such as Payments, Scheduling, or E-Commerce.

This is an important distinction:

So support:tickets:create is mainly a transparent declaration unless your plugin or a future policy layer enforces it. It tells the merchant, "This plugin can create support tickets in the connected support system." By contrast, plugin:payments:initiate:current_chat is enforced by KasiLabs because it asks the platform to perform a platform-owned action.

If your plugin workflow needs a platform capability, prefer a platform bridge instead of exposing raw toolkit tools to the AI. Payments, M-Pesa, and E-Commerce can be dependency-only: installed/configured for the organization, callable through signed bridge permissions, but hidden from the agent tool list.

Examples:

When your plugin owns the customer-facing business flow, make your plugin tools agent-facing and keep platform capabilities dependency-only. For example, Gas OS exposes gas-specific tools to the agent, while E-Commerce persists the durable order and M-Pesa/Payments collects money through the bridge.

For a current-chat payment, your plugin does not send a customer phone number to the bridge. It sends the amount, order reference, items, and exact order details; KasiLabs resolves the payer from the WhatsApp customer currently chatting with the WhatsApp number instance. If the customer says Beth House, Kasarani, House 16, pass that full delivery address through unchanged so the order, receipt, and fulfillment dashboard all show the same precise location.

After payment succeeds, the platform sends one WhatsApp document message: the PDF receipt is attached, and the receipt text summary is used as the message caption. Your plugin should not send a second receipt message unless it has a separate business reason.

Step 5: Grant the plugin to a WhatsApp number instance

Installing a plugin does not automatically give every WhatsApp number instance access.

1. Open the target WhatsApp number instance, such as "Support WhatsApp" or "Sales WhatsApp".
2. Go to Integrations.
3. Find the plugin under granted services or installable plugins.
4. Grant it to that WhatsApp number instance.
5. Confirm the grant is active.

Only that WhatsApp number instance's agent can now use the plugin tools. If the business has a second WhatsApp number for sales, the sales agent will not see this support plugin until the plugin is also granted there.

Step 6: Add prompt guidance

In the WhatsApp number instance system prompt, tell the agent when to use the tool.

Example:

If a customer reports a damaged item, delayed delivery, missing receipt, or any issue that needs human follow-up, create a support ticket using the Support Desk plugin. Give the customer the ticket ID and explain that our team will follow up.

Prompt guidance is not a substitute for permissions, but it helps the agent choose the right tool.

Step 7: Test from WhatsApp

Send a message like:

My order arrived damaged. I need someone to help.

Expected flow:

1. Agent recognizes that a tracked support case is needed.
2. Agent calls create_support_ticket.
3. Plugin returns a ticket ID.
4. Agent gives the ticket ID to the customer.
5. You confirm the call in plugin logs.

Step 8: Tighten behavior

If the agent calls the tool too often, make the description more specific.

If the agent does not call it when expected, update:

• Tool description.
• Input field descriptions.
• Instance system prompt.
• Plugin output response.

Importing an existing API

If you already have an API description, you can generate a starter manifest from it in the developer area. Review the generated tools before installing:

• Keep only tools that are safe for the agent to use.
• Rewrite tool descriptions in customer-support language.
• Remove broad admin operations.
• Add strict input schemas.
• Treat destructive operations as sensitive.

Next steps

• Manifest Reference - Learn all manifest fields
• Plugin Permissions - Learn how plugin and bridge permissions are granted
• Platform Bridges - Request deterministic platform actions from plugins
• Authentication - Secure plugin calls
• Testing & Debugging - Inspect logs and fix behavior
• Permissions & RBAC - Understand WhatsApp number instance grants and sensitive actions