{"id":28715186,"url":"https://github.com/plazbot/plazbot-sdk-examples","last_synced_at":"2026-05-15T13:35:39.917Z","repository":{"id":292912651,"uuid":"982256552","full_name":"plazbot/plazbot-sdk-examples","owner":"plazbot","description":"Agent IA As a Services","archived":false,"fork":false,"pushed_at":"2026-02-18T09:08:45.000Z","size":22527,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-18T13:53:18.375Z","etag":null,"topics":["agent","chatbot","chatbots","ia","whatsapp","whatsapp-bot"],"latest_commit_sha":null,"homepage":"https://www.plazbot.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/plazbot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-12T15:51:56.000Z","updated_at":"2026-02-18T09:08:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"97840883-05e3-4a3a-afe1-53b8fe31d7df","html_url":"https://github.com/plazbot/plazbot-sdk-examples","commit_stats":null,"previous_names":["plazbot/plazbot-sdk-examples"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/plazbot/plazbot-sdk-examples","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plazbot%2Fplazbot-sdk-examples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plazbot%2Fplazbot-sdk-examples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plazbot%2Fplazbot-sdk-examples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plazbot%2Fplazbot-sdk-examples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plazbot","download_url":"https://codeload.github.com/plazbot/plazbot-sdk-examples/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plazbot%2Fplazbot-sdk-examples/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33068721,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","chatbot","chatbots","ia","whatsapp","whatsapp-bot"],"created_at":"2025-06-15T02:01:03.273Z","updated_at":"2026-05-15T13:35:39.910Z","avatar_url":"https://github.com/plazbot.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://storage-files-plz-latam.s3.sa-east-1.amazonaws.com/master/logo-plazbot.png\" alt=\"Plazbot\" width=\"200\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ePlazbot SDK Examples\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAI Agents and WhatsApp for Developers.\u003c/strong\u003e\u003cbr/\u003e\n  Build, deploy, and manage AI agents in minutes.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/plazbot\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/plazbot?style=flat-square\u0026color=blue\" alt=\"npm\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://docs.plazbot.com\"\u003e\u003cimg src=\"https://img.shields.io/badge/docs-plazbot.com-blue?style=flat-square\" alt=\"docs\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://discord.gg/SgyAtrwzp7\"\u003e\u003cimg src=\"https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square\u0026logo=discord\u0026logoColor=white\" alt=\"discord\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://twitter.com/plazbotia\"\u003e\u003cimg src=\"https://img.shields.io/badge/Twitter-Follow-1DA1F2?style=flat-square\u0026logo=twitter\u0026logoColor=white\" alt=\"twitter\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What is Plazbot?\n\nPlazbot is a platform that lets developers create **AI agents** and deploy them across multiple channels:\n\n- **AI Search Portals** - ChatGPT-like search experience for your website\n- **WhatsApp** - Automated AI conversations via the WhatsApp Business API\n- **Web Widgets** - Embeddable chat widgets for any website\n- **Your own software** - Full API access for custom integrations\n\nThis repository contains **working examples** for every feature in the [Plazbot SDK](https://www.npmjs.com/package/plazbot).\n\n---\n\n## Installation\n\n```bash\nnpm install plazbot\n```\n\n---\n\n## Quick Start\n\n```ts\nimport { Plazbot } from 'plazbot';\n\nconst plazbot = new Plazbot({\n  workspaceId: \"YOUR_WORKSPACE_ID\",\n  apiKey: \"YOUR_API_KEY\",\n  zone: \"LA\" // \"EU\" for Europe\n});\n\n// Create an agent\nconst agent = await plazbot.agent.addAgent({\n  name: \"My Agent\",\n  prompt: \"You are a helpful assistant.\",\n  zone: \"LA\",\n  buffer: 5\n});\n\n// Chat with the agent\nconst response = await plazbot.agent.onMessage({\n  agentId: agent.agentId,\n  question: \"What can you do?\",\n  sessionId: crypto.randomUUID()\n});\n\nconsole.log(response.answer);\n```\n\nYou can also import classes individually:\n\n```ts\nimport { Agent, Portal, Message, Template, Contact } from 'plazbot';\n\nconst bot = new Agent({\n  workspaceId: \"YOUR_WORKSPACE_ID\",\n  apiKey: \"YOUR_API_KEY\",\n  zone: \"LA\"\n});\n```\n\n---\n\n## Credentials\n\nGet your **API Key** and **Workspace ID** from the [Plazbot Dashboard](https://www.plazbot.com):\n\n1. Log in to your account\n2. Go to **Settings** \u003e **API KEY**\n3. Copy your `API Key` and `Workspace ID`\n\nGuides:\n- [Create an Account](https://docs.plazbot.com/guides/primeros-pasos/creacion-cuenta)\n- [Developer Documentation](https://docs.plazbot.com/sdk/introduccion)\n\n---\n\n## Examples\n\n### Project Structure\n\n```\nplazbot-sdk-examples/\n  index.ts                   # All examples in one file\n  agent.basic.config.json    # Minimal agent configuration\n  agent.config.json          # Full agent config (services, actions, channels)\n  prompt.txt                 # Example prompt text\n```\n\n### Running the Examples\n\n```bash\ngit clone https://github.com/plazbot/plazbot-sdk-examples.git\ncd plazbot-sdk-examples\nnpm install\n```\n\nEdit `index.ts` and replace `[YOUR_WORKSPACE_ID]` and `[YOUR_API_KEY]` with your credentials. Then:\n\n```bash\nnpm start\n```\n\nUncomment the example functions you want to run in the `main()` function at the bottom of `index.ts`.\n\n---\n\n## Agent\n\n### Create Agent\n\nCreate an agent from a JSON config file or inline:\n\n```ts\n// From config file\nconst config = JSON.parse(await fs.readFile('agent.basic.config.json', 'utf-8'));\nconfig.prompt = \"Your custom prompt here\";\n\nconst agent = await plazbot.agent.addAgent(config);\nconsole.log(agent.agentId);\n```\n\n```ts\n// Inline\nconst agent = await plazbot.agent.addAgent({\n  name: \"Sales Agent\",\n  prompt: \"You are a sales assistant for our company.\",\n  zone: \"LA\",\n  buffer: 5,\n  color: \"blue\",\n  question: \"How can I help you?\",\n  enable: true,\n  examples: [\n    { value: \"What are your prices?\", color: \"blue\" },\n    { value: \"Schedule a demo\", color: \"orange\" }\n  ]\n});\n```\n\n### Update Agent\n\n```ts\nawait plazbot.agent.updateAgent(agentId, {\n  name: \"Sales Agent Updated\",\n  buffer: 8\n});\n```\n\n### Get Agents\n\n```ts\nconst agents = await plazbot.agent.getAgents();\nconst agent = await plazbot.agent.getAgentById({ id: agentId });\n```\n\n### Copy Agent\n\n```ts\nconst copy = await plazbot.agent.copyAgent({ id: agentId });\n```\n\n### Delete Agent\n\n```ts\nawait plazbot.agent.deleteAgent({ id: agentId });\n```\n\n### Chat with Agent (onMessage)\n\n```ts\nconst response = await plazbot.agent.onMessage({\n  agentId: agentId,\n  question: \"What features does Plazbot have?\",\n  sessionId: \"unique-session-id\",\n  file: \"https://example.com/document.pdf\",   // optional - OCR\n  multipleAnswers: true                         // optional\n});\n\nconsole.log(response.answer);\n```\n\n**onMessage Parameters:**\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `agentId` | `string` | Yes | Agent identifier |\n| `question` | `string` | Yes | User's message |\n| `sessionId` | `string` | Yes | Unique session ID for conversation context |\n| `file` | `string` | No | Public URL to a file (PDF, PNG, JPG) for OCR |\n| `multipleAnswers` | `boolean` | No | Return response as multiple blocks |\n\n**Supported file types for OCR:**\n\n| Type | Supported |\n|------|-----------|\n| `.jpg`, `.png`, `.bmp`, `.gif`, `.tiff` | Yes |\n| `.pdf` | Yes (embedded text or scanned images) |\n| `.docx`, `.xlsx` | No |\n\n### Streaming SSE (Server-Sent Events)\n\nSend `stream: true` to receive the response as a real-time stream of tokens instead of waiting for the complete response. Requires the agent to have `useToolCalling: true` (enabled by default for new agents).\n\n```ts\nconst response = await fetch('https://api.plazbot.com/api/agent/on-message', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    'Authorization': 'Bearer YOUR_API_KEY',\n    'x-workspace-id': 'YOUR_WORKSPACE_ID'\n  },\n  body: JSON.stringify({\n    agentId: agentId,\n    question: \"What features does Plazbot have?\",\n    sessionId: \"unique-session-id\",\n    stream: true\n  })\n});\n\nconst reader = response.body.getReader();\nconst decoder = new TextDecoder();\nlet buffer = '';\n\nwhile (true) {\n  const { done, value } = await reader.read();\n  if (done) break;\n\n  buffer += decoder.decode(value, { stream: true });\n  const lines = buffer.split('\\n');\n  buffer = lines.pop() || '';\n\n  for (const line of lines) {\n    if (!line.startsWith('data: ')) continue;\n    const chunk = JSON.parse(line.substring(6));\n\n    if (chunk.type === 'text') {\n      process.stdout.write(chunk.content); // Print tokens as they arrive\n    } else if (chunk.type === 'tool_call') {\n      console.log(`\\nExecuting: ${chunk.tool_name}...`);\n    } else if (chunk.type === 'done') {\n      console.log(`\\nTokens: ${chunk.input_tokens} in / ${chunk.output_tokens} out`);\n    }\n  }\n}\n```\n\n**SSE Chunk Types:**\n\n| Type | Description |\n|------|-------------|\n| `text` | Partial text token (`content` field) |\n| `tool_call` | Agent is executing a tool (`tool_name` field) |\n| `tool_result` | Tool execution completed |\n| `done` | Stream finished (`input_tokens`, `output_tokens`, `estimated_cost`) |\n| `error` | Error occurred (`error` field) |\n\n**Supported providers:** OpenAI, Claude (Anthropic), Gemini (Google)\n\n\u003e **Note:** The `stream` parameter is optional and defaults to `false`. Existing clients are not affected.\n\n### Widget\n\nEnable the embeddable web widget for an agent:\n\n```ts\nconst result = await plazbot.agent.enableWidget({ id: agentId, enable: true });\nconsole.log(result.script); // HTML script to embed\n```\n\nWidget configuration is set in the agent config:\n\n```json\n{\n  \"enableWidget\": true,\n  \"darkWidget\": false,\n  \"nameWidget\": \"My Assistant\",\n  \"initialShowWidget\": false,\n  \"iconWidget\": \"robot\"\n}\n```\n\n### Quick Config Methods\n\nUpdate specific sections of an agent without sending the full config:\n\n```ts\nawait plazbot.agent.setInstructions(agentId, {\n  tone: \"professional\",\n  style: \"short answers\",\n  language: \"es-419\",\n  emojis: false,\n  maxWords: 100\n});\n\nawait plazbot.agent.setPersona(agentId, {\n  name: \"Maximo\",\n  role: \"Virtual assistant\",\n  speaksInFirstPerson: true,\n  isHuman: false\n});\n\nawait plazbot.agent.setFallbacks(agentId, {\n  noAnswer: \"Sorry, I don't have information on that topic.\",\n  serviceError: \"There was a problem. Please try again later.\",\n  doNotUnderstand: \"Could you rephrase that?\"\n});\n\nawait plazbot.agent.setRules(agentId, {\n  doNotMentionPrices: false,\n  doNotDiagnose: true,\n  doNotRespondOutsideHours: \"Monday to Friday 9am to 6pm.\"\n});\n\nawait plazbot.agent.setTags(agentId, [\"sales\", \"ai\"]);\n```\n\n### AI Utilities\n\nImprove a prompt using AI:\n\n```ts\nconst result = await plazbot.agent.improvePrompt(\"you are a bot that helps people\");\nconsole.log(result.result);\n```\n\n### Knowledge Base (Files)\n\nUpload documents so the agent can use RAG to answer questions:\n\n```ts\n// Upload file\nconst file = await plazbot.agent.addFile({\n  fileUrl: \"https://example.com/docs/pricing.pdf\",\n  reference: \"Product pricing and plan details for 2025.\",\n  tags: [\"pricing\", \"plans\"],\n  agentId: agentId\n});\n\n// Check processing status\nconst status = await plazbot.agent.validateFile({ fileId: file.fileId });\n\n// Remove file\nawait plazbot.agent.deleteFile({ fileId: file.fileId, agentId: agentId });\n```\n\n**Supported formats:** `.pdf`, `.doc`, `.docx`\n\n---\n\n## Agent Configuration Reference\n\nThe agent config JSON follows a strict schema. See `agent.config.json` for a full example. Here are the key fields:\n\n### Core Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | `string` | Agent name |\n| `prompt` | `string` | Custom instructions that define agent behavior |\n| `zone` | `\"LA\" \\| \"EU\"` | Must match account zone |\n| `buffer` | `number` | Message context window (3-10) |\n| `color` | `string` | `blue`, `orange`, `green`, `gray`, `white` |\n| `question` | `string` | Main question shown in portals/widgets |\n| `enable` | `boolean` | Active/inactive |\n| `timezone` | `string` | [TZ database format](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) |\n| `examples` | `array` | Quick reply suggestions (max 5) |\n| `tags` | `string[]` | Classification tags |\n\n### Instructions\n\n| Field | Description |\n|-------|-------------|\n| `instructions.tone` | `professional`, `friendly`, `serious`, etc. |\n| `instructions.style` | `short answers`, `detailed`, `bulleted`, etc. |\n| `instructions.personality` | `friendly`, `formal`, `curious`, etc. |\n| `instructions.language` | Language code: `es-419`, `en-US`, `pt-BR`, etc. |\n| `instructions.emojis` | `true` / `false` |\n| `instructions.maxWords` | Max words per response |\n| `instructions.avoidTopics` | Topics the agent should avoid |\n| `instructions.respondOnlyIfKnows` | Only answer when confident |\n| `instructions.greeting` | Initial greeting message |\n\n### Persona\n\n| Field | Description |\n|-------|-------------|\n| `person.name` | Agent's display name |\n| `person.role` | Role description |\n| `person.speaksInFirstPerson` | Uses \"I\" in responses |\n| `person.isHuman` | Identifies as AI or human |\n\n### Fallbacks\n\n| Field | Description |\n|-------|-------------|\n| `fallbacks.noAnswer` | Response when agent has no information |\n| `fallbacks.serviceError` | Response on external service failure |\n| `fallbacks.doNotUnderstand` | Response when agent can't understand |\n\n### Rules\n\n| Field | Description |\n|-------|-------------|\n| `rules.doNotMentionPrices` | Prevents price discussion |\n| `rules.doNotDiagnose` | Disables medical/technical diagnosis |\n| `rules.doNotRespondOutsideHours` | Business hours text (works with `timezone`) |\n\n---\n\n## Tool Calling (Services + Actions)\n\nAgents can call external APIs and execute internal actions based on user intent.\n\n### Services (External API Calls)\n\n```json\n{\n  \"services\": [\n    {\n      \"intent\": \"schedule_date\",\n      \"reference\": \"Service to schedule medical appointments\",\n      \"enabled\": true,\n      \"method\": \"POST\",\n      \"endpoint\": \"https://api.clinic.com/v1/date/schedule\",\n      \"requiredFields\": [\n        { \"name\": \"nombre\", \"type\": \"string\", \"promptHint\": \"What's your name?\" },\n        { \"name\": \"email\", \"type\": \"email\", \"promptHint\": \"What's your email?\" },\n        { \"name\": \"fecha\", \"type\": \"date\", \"promptHint\": \"When would you like to schedule?\" },\n        {\n          \"name\": \"numeros_a_portar\",\n          \"type\": \"arrayObject\",\n          \"description\": \"List of phone numbers to port\",\n          \"promptHint\": \"Which numbers do you want to port? I need: plan type, carrier, and number.\",\n          \"properties\": [\n            { \"name\": \"plan_type\", \"type\": \"string\" },\n            { \"name\": \"carrier\", \"type\": \"string\" },\n            { \"name\": \"number\", \"type\": \"string\" }\n          ]\n        }\n      ],\n      \"headers\": {\n        \"Authorization\": \"Bearer {{apiKey}}\",\n        \"Content-Type\": \"application/json\"\n      },\n      \"bodyTemplate\": {\n        \"nombre\": \"{{nombre}}\",\n        \"email\": \"{{email}}\",\n        \"fecha\": \"{{fecha}}\"\n      },\n      \"responseMessage\": \"Your appointment is confirmed for {{date}}\",\n      \"responseConditions\": [\n        { \"condition\": \"$.response.status == 'success'\", \"message\": \"Confirmed for {{date}}!\" },\n        { \"condition\": \"$.response.status == 'conflict'\", \"message\": \"That slot is taken.\" }\n      ]\n    }\n  ]\n}\n```\n\n| Field | Description |\n|-------|-------------|\n| `intent` | Unique identifier for the service |\n| `reference` | Short description to help AI detect when to trigger |\n| `method` | `GET` or `POST` |\n| `endpoint` | External API URL |\n| `requiredFields` | Fields the agent must collect from the user |\n| `requiredFields[].properties` | Sub-properties for `arrayObject` type fields |\n| `bodyTemplate` | Request body with `{{field}}` interpolation |\n| `responseMapping` | Extract data from API response (JSONPath) |\n| `responseConditions` | Conditional responses based on API result |\n\n### Required Field Types\n\n| Type | Description | Example Value |\n|------|-------------|---------------|\n| `string` | Free text | `\"John Doe\"` |\n| `email` | Valid email address | `\"user@email.com\"` |\n| `phone` | Phone number | `\"+51987654321\"` |\n| `date` | Date (AI-normalized) | `\"2024-03-15\"` |\n| `datetime` | Date and time | `\"2024-03-15 14:30\"` |\n| `number` | Decimal number | `99.99` |\n| `integer` | Whole number | `42` |\n| `boolean` | True or false | `true` |\n| `array` | Array of strings | `[\"value1\", \"value2\"]` |\n| `arrayObject` | Array of objects | `[{\"field\": \"value\"}]` |\n\n#### `arrayObject` - Array of Objects\n\nUse `arrayObject` when you need the user to provide a **list of items with multiple attributes**. Define sub-properties with `name` and `type`:\n\n```json\n{\n  \"name\": \"items_to_order\",\n  \"type\": \"arrayObject\",\n  \"description\": \"List of items the customer wants to order\",\n  \"promptHint\": \"What items do you want to order? I need product name, quantity, and size.\",\n  \"properties\": [\n    { \"name\": \"product\", \"type\": \"string\" },\n    { \"name\": \"quantity\", \"type\": \"integer\" },\n    { \"name\": \"size\", \"type\": \"string\" }\n  ]\n}\n```\n\nThe AI will collect data and produce:\n```json\n[\n  { \"product\": \"T-Shirt\", \"quantity\": 2, \"size\": \"M\" },\n  { \"product\": \"Hoodie\", \"quantity\": 1, \"size\": \"L\" }\n]\n```\n\n**Supported sub-property types:** `string`, `number`, `integer`, `boolean`\n\n### Actions (Internal Operations)\n\n```json\n{\n  \"actions\": [\n    {\n      \"intent\": \"transfer_to_human\",\n      \"reference\": \"Transfer conversation to human agent\",\n      \"enabled\": true,\n      \"responseMessage\": \"Transferring you to a specialist.\",\n      \"action\": [\n        { \"type\": \"action.asign\", \"value\": \"human-agent-id\" },\n        { \"type\": \"action.tag\", \"value\": \"needs-human-support\" }\n      ]\n    }\n  ]\n}\n```\n\n**Available action types:**\n\n| Type | Description |\n|------|-------------|\n| `action.asign` | Assign conversation to a user |\n| `action.tag` | Add a tag to the conversation |\n| `action.stage` | Move conversation to a stage |\n| `action.solved` | Mark conversation as resolved |\n| `action.agentShutDown` | Deactivate AI agent for this conversation |\n| `action.segmentation` | Add segmentation to the contact |\n| `action.event.add` | Create a calendar event |\n| `action.event.update` | Update a calendar event |\n| `action.event.delete` | Delete a calendar event |\n| `action.event.list` | List calendar events |\n\n### Custom AI Provider\n\nUse your own OpenAI, Claude, or Gemini API key:\n\n```ts\nconst agent = await plazbot.agent.addAgent({\n  name: \"Custom AI Agent\",\n  prompt: \"You are a helpful assistant.\",\n  zone: \"LA\",\n  buffer: 5,\n  useToolCalling: true,\n  customAIConfig: true,\n  aiProviders: [\n    {\n      provider: \"openai\",      // \"openai\" | \"claude\" | \"gemini\"\n      model: \"gpt-4o\",\n      apiToken: \"sk-your-key\",\n      temperature: 0.7,\n      maxTokens: 1000,\n      isDefault: true\n    }\n  ]\n});\n```\n\n---\n\n## Portal\n\nPortals are AI-powered search pages with a ChatGPT-like experience.\n\n\u003e A portal must have at least one associated agent to work.\n\n### Create Portal\n\n```ts\nconst portal = await plazbot.portal.addPortal({\n  name: \"Company Portal\",\n  zone: \"LA\",\n  title: \"AI Search Portal\",\n  subtitle: \"Ask anything about our products\",\n  logo: \"https://example.com/logo.png\",\n  logodark: \"https://example.com/logo-dark.png\",\n  access: \"direct\",\n  theme: \"light\",\n  disabled: false,\n  brandOff: false,\n});\n\nconsole.log(portal.url); // Public URL\n```\n\n| Field | Description |\n|-------|-------------|\n| `name` | Portal name |\n| `title` | Heading shown at the top |\n| `subtitle` | Description text |\n| `logo` / `logodark` | Logo URLs (PNG/JPG) |\n| `access` | `\"direct\"` or `\"form\"` |\n| `theme` | `\"light\"` or `\"dark\"` |\n| `disabled` | Activate/deactivate |\n| `brandOff` | Hide Plazbot branding |\n\n### Manage Portal\n\n```ts\n// Link agent to portal\nawait plazbot.portal.addAgentToPortal({ portalId, id: agentId });\n\n// Remove agent from portal\nawait plazbot.portal.removeAgentFromPortal({ portalId, id: agentId });\n\n// Add links (max 5)\nawait plazbot.portal.addLinkToPortal({\n  portalId,\n  value: \"Documentation\",\n  url: \"https://docs.plazbot.com\"\n});\n\n// Clear all links\nawait plazbot.portal.clearLinks(portalId);\n\n// Get portal info\nconst info = await plazbot.portal.getPortal(portalId);\n\n// Update portal\nawait plazbot.portal.updatePortal({ id: portalId, name: \"New Name\", theme: \"dark\" });\n\n// Delete portal\nawait plazbot.portal.deletePortal(portalId);\n```\n\n---\n\n## WhatsApp\n\n### Configuration\n\nBefore using WhatsApp features, connect your number in the Plazbot Dashboard.\n\nGuide: [WhatsApp Configuration](https://docs.plazbot.com/guides/primeros-pasos/conectar-whatsapp)\n\n### Send Messages\n\n```ts\n// Simple message (requires active 24h conversation window)\nawait plazbot.message.onWhatsappMessage({\n  message: \"Hello! Thanks for contacting us.\",\n  to: \"51912345678\"\n});\n\n// Template message (works anytime)\nawait plazbot.message.onConversation({\n  to: \"51912345678\",\n  template: \"welcome_plazbot\"\n});\n\n// Template with variables\nawait plazbot.message.onConversation({\n  to: \"51912345678\",\n  template: \"order_confirmation\",\n  variablesBody: [\n    { variable: \"1\", value: \"John\" },\n    { variable: \"2\", value: \"ORD-12345\" }\n  ]\n});\n\n// Template with file attachment\nawait plazbot.message.onConversation({\n  to: \"51912345678\",\n  template: \"invoice_template\",\n  file: {\n    fileUrl: \"https://example.com/invoice.pdf\",\n    fileName: \"invoice.pdf\"\n  }\n});\n```\n\n### Webhooks\n\nReceive incoming WhatsApp messages on your endpoint:\n\n```ts\n// Register\nawait plazbot.message.registerWebhook({\n  number: \"51912345678\",\n  webhookUrl: \"https://your-server.com/webhooks/whatsapp\"\n});\n\n// Remove\nawait plazbot.message.deleteWebhook({ number: \"51912345678\" });\n```\n\n### Message History\n\n```ts\nconst messages = await plazbot.message.getMessages({ limit: 10 });\nconst history = await plazbot.message.getConversationHistory({ contactId: \"id\" });\nconst results = await plazbot.message.searchMessages({ query: \"pricing\" });\n```\n\n---\n\n## Templates\n\nManage WhatsApp message templates:\n\n```ts\n// List all templates\nconst templates = await plazbot.template.getTemplates();\n\n// List active templates only\nconst active = await plazbot.template.getActiveTemplates();\n\n// Get template details\nconst template = await plazbot.template.getTemplate(\"template-id\");\n```\n\n---\n\n## Contacts\n\nManage your contact database:\n\n```ts\n// Create\nconst contact = await plazbot.contact.createContact({\n  name: \"John Doe\",\n  cellphone: \"51912345678\",\n  email: \"john@example.com\",\n  tags: [\"lead\", \"website\"]\n});\n\n// Read\nconst contacts = await plazbot.contact.getContacts();\nconst found = await plazbot.contact.getContact(\"contact-id\");\n\n// Search\nconst byPhone = await plazbot.contact.searchByPhone(\"51912345678\");\nconst byEmail = await plazbot.contact.searchByEmail(\"john@example.com\");\n\n// Update\nawait plazbot.contact.updateContact({\n  id: contact.id,\n  name: \"John Doe Updated\",\n  tags: [\"lead\", \"premium\"]\n});\n\n// Delete\nawait plazbot.contact.deleteContacts([\"contact-id-1\", \"contact-id-2\"]);\n```\n\n---\n\n## Visual Reference\n\n### Portal\n\n![Portal](./assets/portal.png)\n\n### Portal Light Mode\n![Portal Light](./assets/portal-light.png)\n\n### Portal Dark Mode\n![Portal Dark](./assets/portal-dark.png)\n\n### Widget\n![Widget](./assets/widget-dark.png)\n\n### Widget Messages\n![Widget Messages](./assets/widget-ligth.png)\n\n### WhatsApp\n![WhatsApp](./assets/wsp.png)\n\n---\n\n## Language Codes\n\n| Code | Language |\n|------|----------|\n| `es` | Spanish (General) |\n| `es-419` | Spanish (Latin America) |\n| `es-ES` | Spanish (Spain) |\n| `en` | English (General) |\n| `en-US` | English (United States) |\n| `en-GB` | English (United Kingdom) |\n| `fr` | French |\n| `pt-BR` | Portuguese (Brazil) |\n| `de` | German |\n\n---\n\n## TypeScript Support\n\nThe SDK exports all types for full IntelliSense support:\n\n```ts\nimport type {\n  AgentConfig,\n  AgentData,\n  AgentResponse,\n  PortalConfig,\n  PortalData,\n  SendTemplateParams,\n  TemplateVariable,\n  WhatsAppTemplate,\n  ContactData,\n  CreateContactParams,\n  PlazbotOptions\n} from 'plazbot';\n```\n\n---\n\n## Links\n\n- [NPM Package](https://www.npmjs.com/package/plazbot)\n- [Developer Documentation](https://docs.plazbot.com)\n- [API Reference](https://docs.plazbot.com/api-reference/introduction)\n- [Changelog](https://docs.plazbot.com/changelog/sdk)\n- [Blog](https://www.plazbot.com/blog)\n\n---\n\n## Community\n\nJoin us to get updates, early access, and support:\n\n[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=for-the-badge\u0026logo=discord\u0026logoColor=white)](https://discord.gg/SgyAtrwzp7)\n[![Twitter](https://img.shields.io/badge/Twitter-Follow-1DA1F2?style=for-the-badge\u0026logo=twitter\u0026logoColor=white)](https://twitter.com/plazbotia)\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-0A66C2?style=for-the-badge\u0026logo=linkedin\u0026logoColor=white)](https://www.linkedin.com/company/plazbotcrm)\n\n**Support:** [support@plazbot.com](mailto:support@plazbot.com)\n**Sales \u0026 Partnerships:** [sales@plazbot.com](mailto:sales@plazbot.com)\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplazbot%2Fplazbot-sdk-examples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplazbot%2Fplazbot-sdk-examples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplazbot%2Fplazbot-sdk-examples/lists"}