Testing & Debugging

Sandbox mode

Every plugin starts in sandbox mode. This lets you test it with real conversations without publishing it to other organizations.

Installing in sandbox mode

1. Go to the Plugin Dev Portal in the dashboard
2. Click Install Sandbox Plugin
3. Enter the URL to your manifest file
4. Optionally provide configuration values if your manifest has a configurationSchema
5. Click Install

The platform will:

• Fetch and validate your manifest
• Create the plugin in sandbox mode
• Generate a sandbox secret — save this, it's only shown once
• Send a confirmation email with the secret

Sandbox vs. Live

In sandbox mode, your plugin works exactly like a live plugin — the only difference is that only your organization can see and use it.

Testing your tools

Once your sandbox plugin is installed and granted to an instance:

1. Send a WhatsApp message to your connected number that should trigger your tool
2. Watch your server logs to confirm the request was received
3. Check the response in the WhatsApp conversation

Checking if the AI is using your tool

If the AI agent doesn't call your tool when you expect it to:

• Check the tool description — The AI reads the description field to decide when to call a tool. Make it specific and clear about when the tool should be used.
• Be explicit in your message — Instead of "check my order," try "look up the shipping status for tracking number ABC123." The more specific the message matches your tool's description, the more likely the agent will use it.
• Check that the plugin is granted — Make sure the plugin is granted to the specific instance you're testing on.

Viewing execution logs

The Plugin Dev Portal shows execution logs for your plugin. Each log entry includes:

• Timestamp — When the tool was called
• Tool name — Which tool was invoked
• Status — Whether the call succeeded or failed
• Request — The input data sent to your endpoint
• Response — What your endpoint returned

Use these logs to debug issues with your tool's behavior.

Common issues

"Tool not found" errors

• Verify the tool name in your manifest matches exactly
• Re-fetch your manifest by re-installing the plugin if you've updated the tool list

Request not reaching your server

• Check that your baseUrl is correct and publicly accessible
• Verify HTTPS is working (the platform requires HTTPS for production use)
• Check your server logs for incoming requests
• Make sure your server is running and listening on the correct port

Incorrect request format

Your endpoint receives requests in this format:

{
  "tool": "tool_name",
  "input": { ... },
  "context": { ... }
}

Make sure you're reading req.body.tool and req.body.input, not looking for the data elsewhere.

Token verification failing

• Double-check that you're using the correct secret (sandbox secret for sandbox installs)
• Make sure you're splitting the token on . and comparing HMAC-SHA256 signatures
• Check that the token hasn't expired (5-minute window)

OAuth not working

• Verify the authorization URL and token URL are correct in your manifest
• Check that the Client ID and Client Secret are configured correctly in the platform
• Make sure your OAuth provider's redirect URL is set to the platform's callback URL
• Check the scopes requested match what your provider expects

Updating your plugin

When you make changes to your manifest or endpoint:

1. Update the manifest file at its hosted URL
2. In the Plugin Dev Portal, re-fetch or re-install the plugin
3. Test again with a WhatsApp message

For endpoint changes (code updates), just deploy your new code — the platform will call the same URL.

Submitting for review

When your plugin is tested and ready:

1. Go to the Plugin Dev Portal
2. Find your plugin
3. Click Request Review

The review process checks that your manifest is valid, your endpoint is responsive, and your plugin follows platform guidelines.

Once approved, your plugin's status changes from "sandbox" to "live" and it becomes available for other organizations to install.

Deleting a plugin

If you need to remove a plugin:

1. Go to the Plugin Dev Portal
2. Find the plugin you want to remove
3. Click Delete

This removes the manifest from the catalog. If it was installed by other organizations, those installations will stop working.