plazbot/README.md

Official Plazbot SDK for creating AI agents for WhatsApp, portals, and developers.

# Plazbot SDK

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

## Installation

```bash
npm install plazbot
```

## Quick Start

```ts
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:

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

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

---

## Agent

### Create Agent

```ts
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

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

### List / Get / Copy / Delete

```ts
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

```ts
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)

```ts
// 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

```ts
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

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

### AI Utilities

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

---

## Portal

### Create Portal

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

### Update / Get / Delete

```ts
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

```ts
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

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

### Send Template

```ts
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

```ts
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

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

---

## Template

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

---

## Contact

```ts
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("user@example.com");

const newContact = await bot.contact.createContact({
  name: "John Doe",
  cellphone: "5491123456789",
  email: "john@example.com"
});

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:

```ts
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:

```ts
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:

```ts
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