Plazbot SDK

Official SDK to interact with Plazbot AI Agents, Portals, WhatsApp messaging, and more. TypeScript-first with full type definitions.

Installation

npm install plazbot

Quick Start

import { Plazbot } from "plazbot";

const bot = new Plazbot({
  apiKey: "YOUR_API_KEY",
  workspaceId: "YOUR_WORKSPACE_ID",
  zone: "LA" // "LA" or "EU"
});

// Create an agent
const result = await bot.agent.addAgent({
  name: "Support Agent",
  prompt: "You are a helpful assistant.",
  zone: "LA",
  buffer: 5,
  color: "blue"
});

// Chat with the agent
const response = await bot.agent.onMessage({
  agentId: result.agentId,
  question: "Hello!",
  sessionId: "session-123"
});

console.log(response.answer);

You can also import classes individually:

import { Agent, Portal, Message } from "plazbot";

const agent = new Agent({
  apiKey: "YOUR_API_KEY",
  workspaceId: "YOUR_WORKSPACE_ID",
  zone: "LA"
});

Agent

Create Agent

const result = await bot.agent.addAgent({
  name: "Sales Bot",
  prompt: "You are a sales assistant.",
  zone: "LA",
  buffer: 5,
  color: "blue",
  useToolCalling: true,
  instructions: {
    tone: "friendly",
    style: "conversational",
    language: "Espanol",
    emojis: true,
    greeting: "Hola! En que puedo ayudarte?"
  },
  person: {
    name: "Ana",
    role: "Sales advisor",
    speaksInFirstPerson: true
  },
  fallbacks: {
    noAnswer: "I don't have that info.",
    serviceError: "Service is down.",
    doNotUnderstand: "Could you rephrase?"
  }
});

console.log(result.agentId);

Update Agent

await bot.agent.updateAgent("AGENT_ID", {
  name: "Updated Bot",
  useToolCalling: false
});

List / Get / Copy / Delete

const agents = await bot.agent.getAgents();
const agent = await bot.agent.getAgentById({ id: "AGENT_ID" });
const copy = await bot.agent.copyAgent({ id: "AGENT_ID" });
await bot.agent.deleteAgent({ id: "AGENT_ID" });

Chat

const response = await bot.agent.onMessage({
  agentId: "AGENT_ID",
  question: "What products do you offer?",
  sessionId: "session-uuid"
});

console.log(response.answer);
console.log(response.sources);         // Knowledge base sources
console.log(response.actionsExecuted); // Tool Calling actions executed

Knowledge Base (Files)

// Add file
const file = await bot.agent.addFile({
  fileUrl: "https://example.com/document.pdf",
  reference: "Product catalog",
  agentId: "AGENT_ID"
});

// Check processing status
const status = await bot.agent.validateFile({ fileId: "FILE_ID" });

// Remove file
await bot.agent.deleteFile({ fileId: "FILE_ID", agentId: "AGENT_ID" });

Quick Configuration

await bot.agent.setGreeting("AGENT_ID", "Welcome!");
await bot.agent.setInstructions("AGENT_ID", { tone: "professional", emojis: false });
await bot.agent.setPersona("AGENT_ID", { name: "Carlos", role: "Support" });
await bot.agent.setFallbacks("AGENT_ID", { noAnswer: "I can't help with that." });
await bot.agent.setRules("AGENT_ID", { doNotMentionPrices: true });
await bot.agent.setTags("AGENT_ID", ["support", "premium"]);

Widget

const widget = await bot.agent.enableWidget({ id: "AGENT_ID", enable: true });
console.log(widget.script); // Embed script

AI Utilities

const improved = await bot.agent.improvePrompt("help users buy stuff");
console.log(improved.result);

Portal

Create Portal

const portal = await bot.portal.addPortal({
  name: "Support Portal",
  zone: "LA",
  theme: "dark",
  access: "direct"
});
console.log(portal.id, portal.url);

Update / Get / Delete

await bot.portal.updatePortal({ id: "PORTAL_ID", name: "New Name", theme: "light" });
const portal = await bot.portal.getPortal("PORTAL_ID");
await bot.portal.deletePortal("PORTAL_ID");

Links & Agents

await bot.portal.addAgentToPortal({ portalId: "PORTAL_ID", id: "AGENT_ID" });
await bot.portal.removeAgentFromPortal({ portalId: "PORTAL_ID", id: "AGENT_ID" });
await bot.portal.addLinkToPortal({ portalId: "PORTAL_ID", value: "FAQ", url: "/faq" });
await bot.portal.clearLinks("PORTAL_ID");

Message (WhatsApp)

Send Direct Message

await bot.message.onWhatsappMessage({
  to: "5491123456789",
  message: "Hello from Plazbot!"
});

Send Template

await bot.message.onConversation({
  to: "5491123456789",
  template: "welcome_template",
  variablesBody: [{ variable: "1", value: "John" }],
  variablesHeader: [{ variable: "1", value: "Acme Inc" }],
  file: { fileUrl: "https://example.com/file.pdf", fileName: "catalog.pdf" }
});

Message History

const messages = await bot.message.getMessages({ contactId: "CONTACT_ID" });
const history = await bot.message.getConversationHistory({ contactId: "CONTACT_ID" });
const results = await bot.message.searchMessages({ query: "invoice" });

Webhooks

await bot.message.registerWebhook({ number: "5491123456789", webhookUrl: "https://myapp.com/webhook" });
await bot.message.deleteWebhook({ number: "5491123456789" });

Template

const templates = await bot.template.getTemplates();
const active = await bot.template.getActiveTemplates();
const template = await bot.template.getTemplate("TEMPLATE_ID");

Contact

const contacts = await bot.contact.getContacts();
const contact = await bot.contact.getContact("CONTACT_ID");
const found = await bot.contact.searchByPhone("5491123456789");
const byEmail = await bot.contact.searchByEmail("[email protected]");

const newContact = await bot.contact.createContact({
  name: "John Doe",
  cellphone: "5491123456789",
  email: "[email protected]"
});

await bot.contact.updateContact({ id: "CONTACT_ID", name: "Jane Doe" });
await bot.contact.deleteContacts(["CONTACT_ID_1", "CONTACT_ID_2"]);

Tool Calling Configuration

Configure agents to execute actions automatically via the agent config:

await bot.agent.addAgent({
  name: "Clinic Bot",
  prompt: "You help patients schedule appointments.",
  zone: "LA",
  buffer: 5,
  useToolCalling: true,
  services: [{
    intent: "check_availability",
    reference: "availability, schedule, free slots",
    method: "GET",
    endpoint: "https://api.clinic.com/availability",
    requiredFields: [
      { name: "date", type: "date", description: "Appointment date" }
    ],
    responseMessage: "Here are the available slots:"
  }],
  actions: [{
    intent: "schedule_appointment",
    reference: "schedule, book, appointment",
    enabled: true,
    action: [{ type: "action.event.add", value: "" }],
    requiredFields: [
      { name: "date", type: "datetime", description: "Date and time" },
      { name: "patient", type: "string", description: "Patient name" }
    ],
    responseMessage: "Your appointment has been scheduled."
  }]
});

Available Action Types

| Type | Description | |------|-------------| | action.event.add | Schedule event | | action.event.update | Reschedule event | | action.event.delete | Cancel event | | action.event.list | List events | | action.tag | Add tag to contact | | action.stage | Change contact stage | | action.agentShutDown | Transfer to human agent | | action.solved | Mark as resolved | | action.asign | Assign to agent | | action.segmentation | Apply segmentation |

TypeScript Types

All types are exported for full type safety:

import type {
  AgentConfig,
  AgentData,
  AgentResponse,
  AgentSource,
  AIProvider,
  AgentInstructions,
  AgentPerson,
  AgentFallbacks,
  AgentService,
  AgentAction,
  PortalConfig,
  SendTemplateParams,
  ContactData,
  WhatsAppTemplate,
  PlazbotOptions,
} from "plazbot";

Development Flag

All classes accept a customUrl option for local development:

const bot = new Plazbot({
  apiKey: "YOUR_API_KEY",
  workspaceId: "YOUR_WORKSPACE_ID",
  zone: "LA",
  customUrl: "http://localhost:5090"
});

Scripts

• npm run build - Compile TypeScript
• npm run clean - Remove dist folder
• npm run release - Bump version and publish

License

MIT