pinto-app-openclaw 1.3.17 → 1.3.19

package/README.md

@@ -29,7 +29,7 @@ flow การทำงาน:
 - OpenClaw ที่รันได้แล้ว
 - Node.js 20+ และ npm
 - Pinto bot ที่สร้างไว้แล้ว
-- Bot UUID จริงของ Pinto
+- Bot ID จริงของ Pinto
 - Pinto API base URL ที่ถูกต้อง เช่น `https://api.pinto-app.com`
 - URL ที่ Pinto เข้าถึง OpenClaw ได้จริง เช่น domain, reverse proxy, Tailscale, tunnel
 
@@ -82,16 +82,21 @@ openclaw plugins install .
   - ใส่ได้ทั้งแบบมี `/` ท้ายหรือไม่มี `/` ท้าย
   - ตัวอย่าง `https://api.pinto-app.com`
 - `Bot Id`
-  - ต้องเป็น Bot UUID จริงของ Pinto
-  - ไม่ใช่ `bot_id` แบบ slug
+  - ต้องเป็น Bot ID จริงของ Pinto
+  - ต้องตรงกับค่า `bot_id` ที่ Pinto ส่งมา
 - `Enabled`
   - เปิดหรือปิด channel
 - `Agent Id`
   - optional
   - ถ้าตั้งค่าไว้ bot นี้จะถูก route ไปยัง agent ที่ระบุโดยตรง
   - ถ้าไม่ตั้งค่า OpenClaw จะใช้ routing/config ปกติของระบบ
+- `Observer Agent Ids`
+  - optional
+  - เป็นรายชื่อ agent เสริมที่รับข้อความเดียวกัน
+  - observer จะไม่ตอบกลับ Pinto โดยตรง
 - `Webhook Secret`
   - secret ที่ใช้ร่วมกับ header `X-Pinto-Secret`
+  - ระบบไม่ generate ค่านี้ให้อัตโนมัติ
   - ถ้าไม่ได้ตั้งค่าไว้ ระบบจะไม่บังคับตรวจ secret ขาเข้า
 - `Webhook Path`
   - path ของ webhook endpoint บน OpenClaw
@@ -104,9 +109,11 @@ openclaw plugins install .
 - ระบบจะเติม `apiUrl` เป็น `https://api.pinto-app.com`
 - ระบบจะเติม `botId` เป็นสตริงว่าง `""`
 - ระบบจะเติม `agentId` เป็นสตริงว่าง `""`
-- ระบบจะ generate `webhookSecret` ให้ 1 ค่าอัตโนมัติ
+- ระบบจะไม่เติม `observerAgentIds` ถ้ายังไม่ได้ใช้
+- ระบบจะเติม `webhookSecret` เป็นสตริงว่าง `""`
 - ระบบจะเติม `webhookPath` เป็น `/plugins/pinto/webhook`
 - ผู้ใช้ยังต้องกรอก `botId` เองจาก Pinto bot จริง
+- ถ้าต้องการตรวจ secret ผู้ใช้ต้องกรอก `webhookSecret` เอง และตั้งค่าเดียวกันใน Pinto
 
 ตัวอย่าง config:
 
@@ -118,7 +125,7 @@ openclaw plugins install .
       "apiUrl": "https://api.pinto-app.com",
       "botId": "",
       "agentId": "",
-      "webhookSecret": "pinto-oc-9f3a1b7c5d2e8k4m",
+      "webhookSecret": "",
       "webhookPath": "/plugins/pinto/webhook"
     }
   }
@@ -140,15 +147,16 @@ openclaw plugins install .
         "sales": {
           "enabled": true,
           "apiUrl": "https://api.pinto-app.com",
-          "botId": "20387880-7934-40c3-b7d4-9fa6557697cf",
+          "botId": "bot-sales",
           "agentId": "sales-agent",
+          "observerAgentIds": ["audit-agent", "memory-agent"],
           "webhookSecret": "pinto-oc-sales-secret",
           "webhookPath": "/plugins/pinto/sales"
         },
         "support": {
           "enabled": true,
           "apiUrl": "https://api.pinto-app.com",
-          "botId": "d03cb2fd-6fd6-4d93-8f30-111111111111",
+          "botId": "bot-support",
           "agentId": "support-agent",
           "webhookSecret": "pinto-oc-support-secret",
           "webhookPath": "/plugins/pinto/support"
@@ -163,8 +171,10 @@ openclaw plugins install .
 
 - Pinto bot แต่ละตัวควรมี `botId`, `webhookSecret`, และ `webhookPath` ของตัวเอง
 - ถ้าต้องการแยก agent ต่อ bot ให้กำหนด `agentId` ของแต่ละ account
+- ถ้าต้องการให้ agent เสริมช่วยวิเคราะห์หรือบันทึกข้อมูล ให้กำหนด `observerAgentIds`
 - ให้ตั้ง `webhook_url` ของแต่ละ bot ไปยัง path ของตัวเอง
 - ถ้ากำหนด `agentId` ไว้ ปลั๊กอินจะ route bot นั้นไป agent ที่ระบุทันที
+- ถ้ากำหนด `observerAgentIds` ไว้ observer จะได้รับ inbound context เดียวกัน แต่จะไม่ตอบกลับ Pinto
 - ถ้าไม่กำหนด `agentId` ปลั๊กอินจะ fallback ไปใช้ routing/config ปกติของ OpenClaw
 - ห้ามใช้ `webhookPath` ซ้ำกันหลาย account เพราะ route จะชนกัน
 - `botId` ต้องตรงกับค่าที่ Pinto ส่งมาใน `payload.bot_id` จริง ไม่ควรใช้ alias ที่ตั้งเอง
@@ -174,6 +184,201 @@ openclaw plugins install .
 - channel id ของปลั๊กอินคือ `pinto`
 - package name คือ `pinto-app-openclaw`
 
+### วิธีสร้าง Agent และผูกกับ Pinto Bot
+
+`agentId` เป็น id ของ agent ฝั่ง OpenClaw ไม่ได้มาจาก Pinto
+
+แนวคิด:
+
+- `botId` คือ id ของ bot ใน Pinto
+- `agentId` คือ id ของ agent ใน OpenClaw
+- Pinto bot แต่ละตัวสามารถชี้ไป agent คนละตัวได้
+
+#### ขั้นตอนที่ 1: เพิ่ม agent ใน OpenClaw config
+
+แก้ไฟล์ `openclaw.json`
+
+ตำแหน่งไฟล์โดยทั่วไป:
+
+- macOS: `~/.openclaw/openclaw.json`
+- Windows: `%USERPROFILE%\.openclaw\openclaw.json`
+
+ตัวอย่าง:
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "name": "Main Agent",
+        "workspace": "~/.openclaw/workspace-main"
+      },
+      {
+        "id": "sales-agent",
+        "name": "Sales Agent",
+        "workspace": "~/.openclaw/workspace-sales"
+      }
+    ]
+  }
+}
+```
+
+ความหมาย:
+
+- `id` คือ `agentId` ที่จะเอาไปใส่ใน Pinto config
+- `name` คือชื่อที่อ่านง่าย
+- `workspace` คือโฟลเดอร์งานของ agent ตัวนั้น
+
+บน Windows ใช้ path แบบนี้ได้เช่นกัน:
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "name": "Main Agent",
+        "workspace": "C:\\Users\\Administrator\\.openclaw\\workspace-main"
+      },
+      {
+        "id": "sales-agent",
+        "name": "Sales Agent",
+        "workspace": "C:\\Users\\Administrator\\.openclaw\\workspace-sales"
+      }
+    ]
+  }
+}
+```
+
+#### ขั้นตอนที่ 2: สร้าง workspace ของ agent
+
+ตัวอย่าง path:
+
+- macOS:
+  - `~/.openclaw/workspace-main`
+  - `~/.openclaw/workspace-sales`
+- Windows:
+  - `C:\Users\Administrator\.openclaw\workspace-main`
+  - `C:\Users\Administrator\.openclaw\workspace-sales`
+
+ถ้าต้องการให้ agent มีบุคลิกหรือหน้าที่เฉพาะ ให้เพิ่มไฟล์ `AGENTS.md` ใน workspace ของ agent นั้น
+
+ตัวอย่าง `AGENTS.md`:
+
+```md
+You are the sales assistant for Pinto.
+Focus on product guidance, pricing, promotions, and converting leads.
+When a message comes from Pinto, answer with normal user-facing text.
+Do not call the Pinto API or include bot_id/chat_id JSON in the reply.
+Be concise and helpful.
+```
+
+#### ขั้นตอนที่ 3: restart หรือ reload OpenClaw
+
+หลังแก้ `openclaw.json` ให้ restart OpenClaw หรือ reload plugins/config เพื่อให้ระบบรู้จัก agent ใหม่
+
+#### ขั้นตอนที่ 4: ใส่ agentId ใน Pinto config
+
+ตัวอย่าง single-account:
+
+```json
+{
+  "channels": {
+    "pinto": {
+      "enabled": true,
+      "apiUrl": "https://api.pinto-app.com",
+      "botId": "bot-sales",
+      "agentId": "sales-agent",
+      "webhookSecret": "pinto-oc-9f3a1b7c5d2e8k4m",
+      "webhookPath": "/plugins/pinto/webhook"
+    }
+  }
+}
+```
+
+ตัวอย่าง multi-account:
+
+```json
+{
+  "channels": {
+    "pinto": {
+      "defaultAccount": "sales",
+      "accounts": {
+        "sales": {
+          "enabled": true,
+          "apiUrl": "https://api.pinto-app.com",
+          "botId": "bot-sales",
+          "agentId": "sales-agent",
+          "webhookSecret": "secret-sales",
+          "webhookPath": "/plugins/pinto/sales"
+        },
+        "support": {
+          "enabled": true,
+          "apiUrl": "https://api.pinto-app.com",
+          "botId": "bot-support",
+          "agentId": "main",
+          "webhookSecret": "secret-support",
+          "webhookPath": "/plugins/pinto/support"
+        }
+      }
+    }
+  }
+}
+```
+
+#### ขั้นตอนที่ 5: ตั้งค่าฝั่ง Pinto
+
+ใน Pinto bot ให้ตั้ง:
+
+- `webhook_url = <public-openclaw-base-url> + <webhookPath>`
+- `X-Pinto-Secret` ให้ตรงกับ `webhookSecret`
+
+ตัวอย่าง:
+
+- `sales-agent` ใช้ path `/plugins/pinto/sales`
+- `webhook_url` เป็น `https://bot.example.com/plugins/pinto/sales`
+
+#### ขั้นตอนที่ 6: ทดสอบ
+
+ทดสอบ healthcheck:
+
+```bash
+curl -i https://bot.example.com/plugins/pinto/sales
+```
+
+ควรได้:
+
+```json
+{"ok":true,"channel":"pinto"}
+```
+
+ทดสอบ webhook:
+
+```bash
+curl -i -X POST https://bot.example.com/plugins/pinto/sales \
+  -H 'Content-Type: application/json' \
+  -H 'X-Pinto-Secret: secret-sales' \
+  -d '{
+    "bot_id":"bot-sales",
+    "chat_id":"chat-001",
+    "message":"โปรโมชั่นวันนี้มีอะไรบ้าง",
+    "user_id":"user-123"
+  }'
+```
+
+ผลที่ควรเกิด:
+
+- Pinto ยิง webhook เข้ามา
+- plugin ตรวจ `botId`, `webhookSecret`, และ `webhookPath`
+- ถ้าตั้ง `agentId` ไว้ ระบบจะ route ไป agent ตัวนั้นทันที
+- จากนั้นคำตอบของ agent จะถูกส่งกลับไป Pinto
+
+หมายเหตุ:
+
+- ถ้ายังไม่ได้แยก agent หลายตัว ให้ใช้ `agentId: "main"` ได้เลย
+- ถ้าไม่ใส่ `agentId` ปลั๊กอินจะ fallback ไปใช้ routing ปกติของ OpenClaw
+
 ### การตั้งค่าฝั่ง Pinto
 
 Pinto bot ต้องมีข้อมูลต่อไปนี้:
@@ -186,8 +391,8 @@ Pinto bot ต้องมีข้อมูลต่อไปนี้:
   - `webhook_url = <public-openclaw-base-url> + <Webhook Path>`
   - ตัวอย่างเช่น ถ้า OpenClaw เปิดผ่าน `https://bot.example.com` และ `Webhook Path` เป็น `/plugins/pinto/custom-webhook`
   - ให้ใส่ `https://bot.example.com/plugins/pinto/custom-webhook`
-- Bot UUID
-  - ใช้ค่า `_id` ของ bot เป็นค่า `Bot Id` ใน OpenClaw
+- Bot ID
+  - ใช้ค่า `bot_id` ของ bot เป็นค่า `Bot Id` ใน OpenClaw
 - ถ้ามีการเปิดใช้ secret
   - Pinto ต้องส่ง header `X-Pinto-Secret` เข้ามา
   - ค่า secret ต้องตรงกับ `Webhook Secret` ใน OpenClaw
@@ -240,7 +445,7 @@ POST /plugins/pinto/webhook
 
 ```json
 {
-  "bot_id": "20387880-7934-40c3-b7d4-9fa6557697cf",
+  "bot_id": "bot-sales",
   "chat_id": "5f315d4e-cf22-4054-bbb0-2fe074bd3892",
   "message": "hello",
   "user_id": "a7c3fe36-cf41-42b5-a290-ca98e6129fac",
@@ -260,7 +465,7 @@ POST <apiUrl>/v1/bots/webhook/receive
 
 ```json
 {
-  "bot_id": "20387880-7934-40c3-b7d4-9fa6557697cf",
+  "bot_id": "bot-sales",
   "chat_id": "5f315d4e-cf22-4054-bbb0-2fe074bd3892",
   "reply_message": "สวัสดีจาก OpenClaw"
 }
@@ -270,7 +475,7 @@ POST <apiUrl>/v1/bots/webhook/receive
 
 ```json
 {
-  "bot_id": "20387880-7934-40c3-b7d4-9fa6557697cf",
+  "bot_id": "bot-sales",
   "chat_id": "5f315d4e-cf22-4054-bbb0-2fe074bd3892",
   "reply_message": "ดูรูปนี้",
   "media_url": "https://example.com/image.png"
@@ -303,7 +508,7 @@ curl -i -X POST http://127.0.0.1:18789/plugins/pinto/webhook \
   -H 'Content-Type: application/json' \
   -H 'X-Pinto-Secret: pinto-oc-9f3a1b7c5d2e8k4m' \
   -d '{
-    "bot_id":"20387880-7934-40c3-b7d4-9fa6557697cf",
+    "bot_id":"bot-sales",
     "chat_id":"5f315d4e-cf22-4054-bbb0-2fe074bd3892",
     "message":"hello",
     "user_id":"a7c3fe36-cf41-42b5-a290-ca98e6129fac"
@@ -323,7 +528,7 @@ curl -i -X POST https://your-host.example.com/plugins/pinto/webhook \
   -H 'Content-Type: application/json' \
   -H 'X-Pinto-Secret: pinto-oc-9f3a1b7c5d2e8k4m' \
   -d '{
-    "bot_id":"20387880-7934-40c3-b7d4-9fa6557697cf",
+    "bot_id":"bot-sales",
     "chat_id":"5f315d4e-cf22-4054-bbb0-2fe074bd3892",
     "message":"hello",
     "user_id":"a7c3fe36-cf41-42b5-a290-ca98e6129fac"
@@ -337,7 +542,7 @@ curl -i -X POST https://api.pinto-app.com/v1/bots/webhook/receive \
   -H 'Content-Type: application/json' \
   -H 'X-Pinto-Secret: pinto-oc-9f3a1b7c5d2e8k4m' \
   -d '{
-    "bot_id":"20387880-7934-40c3-b7d4-9fa6557697cf",
+    "bot_id":"bot-sales",
     "chat_id":"5f315d4e-cf22-4054-bbb0-2fe074bd3892",
     "reply_message":"OpenClaw outbound test"
   }'
@@ -365,7 +570,7 @@ curl -i -X POST https://api.pinto-app.com/v1/bots/webhook/receive \
 
 สาเหตุที่พบบ่อย:
 
-- `Bot Id` ไม่ใช่ UUID จริง
+- `Bot Id` ไม่ตรงกับค่า `bot_id` จริงของ Pinto
 - `chat_id` อยู่คนละ environment
 - payload ที่ส่งไป `POST /v1/bots/webhook/receive` ไม่ตรงกับ backend Pinto
 
@@ -412,7 +617,7 @@ Main features:
 - A working OpenClaw instance
 - Node.js 20+ and npm
 - An existing Pinto bot
-- The real Pinto bot UUID
+- The real Pinto bot ID
 - A valid Pinto API base URL such as `https://api.pinto-app.com`
 - A public or reachable URL that Pinto can call
 
@@ -464,16 +669,21 @@ Fields:
   - Pinto API base URL
   - With or without a trailing slash is supported
 - `Bot Id`
-  - Must be the real Pinto bot UUID
-  - Do not use the human-readable bot slug
+  - Must be the real Pinto bot ID
+  - Must match the `bot_id` value Pinto sends
 - `Enabled`
   - Enables or disables the channel
 - `Agent Id`
   - Optional
   - If set, this bot will be routed directly to that OpenClaw agent
   - If empty, the plugin falls back to normal OpenClaw routing
+- `Observer Agent Ids`
+  - Optional
+  - Additional agents that receive the same inbound context
+  - Observer agents do not reply back to Pinto
 - `Webhook Secret`
   - Shared secret used with `X-Pinto-Secret`
+  - The plugin does not generate this value by default
   - If empty, inbound secret validation is not enforced
 
 Example config:
@@ -486,7 +696,7 @@ Example config:
       "apiUrl": "https://api.pinto-app.com",
       "botId": "",
       "agentId": "",
-      "webhookSecret": "pinto-oc-9f3a1b7c5d2e8k4m",
+      "webhookSecret": "",
       "webhookPath": "/plugins/pinto/webhook"
     }
   }
@@ -504,15 +714,16 @@ Multi-account example:
         "sales": {
           "enabled": true,
           "apiUrl": "https://api.pinto-app.com",
-          "botId": "20387880-7934-40c3-b7d4-9fa6557697cf",
+          "botId": "bot-sales",
           "agentId": "sales-agent",
+          "observerAgentIds": ["audit-agent", "memory-agent"],
           "webhookSecret": "pinto-oc-sales-secret",
           "webhookPath": "/plugins/pinto/sales"
         },
         "support": {
           "enabled": true,
           "apiUrl": "https://api.pinto-app.com",
-          "botId": "d03cb2fd-6fd6-4d93-8f30-111111111111",
+          "botId": "bot-support",
           "agentId": "support-agent",
           "webhookSecret": "pinto-oc-support-secret",
           "webhookPath": "/plugins/pinto/support"
@@ -527,8 +738,10 @@ Multi-account notes:
 
 - Each Pinto bot should have its own `botId`, `webhookSecret`, and `webhookPath`
 - If you want a specific bot to use a specific agent, set `agentId` on that account
+- If you want helper agents to observe the same inbound message, set `observerAgentIds`
 - Each bot's `webhook_url` should point to its own unique path
 - When `agentId` is set, the plugin routes that bot directly to the named agent
+- When `observerAgentIds` is set, those observer agents receive the same inbound context but do not reply to Pinto
 - When `agentId` is empty, the plugin falls back to normal OpenClaw routing
 - Do not reuse the same `webhookPath` across multiple accounts, or routes will collide
 - `botId` must exactly match the value Pinto sends in `payload.bot_id`
@@ -538,6 +751,198 @@ Notes:
 - The channel id is `pinto`
 - The package name is `pinto-app-openclaw`
 
+### How To Create An Agent And Connect It To A Pinto Bot
+
+`agentId` comes from OpenClaw, not from Pinto.
+
+Concept:
+
+- `botId` is the Pinto bot id
+- `agentId` is the OpenClaw agent id
+- Each Pinto bot can use a different OpenClaw agent
+
+#### Step 1: Add the agent to OpenClaw config
+
+Edit `openclaw.json`
+
+Common locations:
+
+- macOS: `~/.openclaw/openclaw.json`
+- Windows: `%USERPROFILE%\.openclaw\openclaw.json`
+
+Example:
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "name": "Main Agent",
+        "workspace": "~/.openclaw/workspace-main"
+      },
+      {
+        "id": "sales-agent",
+        "name": "Sales Agent",
+        "workspace": "~/.openclaw/workspace-sales"
+      }
+    ]
+  }
+}
+```
+
+Windows path example:
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "name": "Main Agent",
+        "workspace": "C:\\Users\\Administrator\\.openclaw\\workspace-main"
+      },
+      {
+        "id": "sales-agent",
+        "name": "Sales Agent",
+        "workspace": "C:\\Users\\Administrator\\.openclaw\\workspace-sales"
+      }
+    ]
+  }
+}
+```
+
+#### Step 2: Create the agent workspace
+
+Example paths:
+
+- macOS:
+  - `~/.openclaw/workspace-main`
+  - `~/.openclaw/workspace-sales`
+- Windows:
+  - `C:\Users\Administrator\.openclaw\workspace-main`
+  - `C:\Users\Administrator\.openclaw\workspace-sales`
+
+If you want a dedicated persona or behavior for that agent, add `AGENTS.md` inside that workspace.
+
+Example `AGENTS.md`:
+
+```md
+You are the sales assistant for Pinto.
+Focus on product guidance, pricing, promotions, and converting leads.
+When a message comes from Pinto, answer with normal user-facing text.
+Do not call the Pinto API or include bot_id/chat_id JSON in the reply.
+Be concise and helpful.
+```
+
+#### Step 3: Restart or reload OpenClaw
+
+After editing `openclaw.json`, restart OpenClaw or reload config/plugins so the new agent becomes available.
+
+#### Step 4: Set `agentId` in Pinto config
+
+Single-account example:
+
+```json
+{
+  "channels": {
+    "pinto": {
+      "enabled": true,
+      "apiUrl": "https://api.pinto-app.com",
+      "botId": "bot-sales",
+      "agentId": "sales-agent",
+      "observerAgentIds": ["audit-agent", "memory-agent"],
+      "webhookSecret": "pinto-oc-9f3a1b7c5d2e8k4m",
+      "webhookPath": "/plugins/pinto/webhook"
+    }
+  }
+}
+```
+
+Multi-account example:
+
+```json
+{
+  "channels": {
+    "pinto": {
+      "defaultAccount": "sales",
+      "accounts": {
+        "sales": {
+          "enabled": true,
+          "apiUrl": "https://api.pinto-app.com",
+          "botId": "bot-sales",
+          "agentId": "sales-agent",
+          "observerAgentIds": ["audit-agent", "memory-agent"],
+          "webhookSecret": "secret-sales",
+          "webhookPath": "/plugins/pinto/sales"
+        },
+        "support": {
+          "enabled": true,
+          "apiUrl": "https://api.pinto-app.com",
+          "botId": "bot-support",
+          "agentId": "main",
+          "webhookSecret": "secret-support",
+          "webhookPath": "/plugins/pinto/support"
+        }
+      }
+    }
+  }
+}
+```
+
+#### Step 5: Configure Pinto
+
+In your Pinto bot settings:
+
+- set `webhook_url = <public-openclaw-base-url> + <webhookPath>`
+- set `X-Pinto-Secret` to match `webhookSecret`
+
+Example:
+
+- `sales-agent` uses `/plugins/pinto/sales`
+- `webhook_url` becomes `https://bot.example.com/plugins/pinto/sales`
+
+#### Step 6: Test it
+
+Healthcheck:
+
+```bash
+curl -i https://bot.example.com/plugins/pinto/sales
+```
+
+Expected:
+
+```json
+{"ok":true,"channel":"pinto"}
+```
+
+Webhook test:
+
+```bash
+curl -i -X POST https://bot.example.com/plugins/pinto/sales \
+  -H 'Content-Type: application/json' \
+  -H 'X-Pinto-Secret: secret-sales' \
+  -d '{
+    "bot_id":"bot-sales",
+    "chat_id":"chat-001",
+    "message":"What promotions are available today?",
+    "user_id":"user-123"
+  }'
+```
+
+Expected behavior:
+
+- Pinto sends the webhook
+- the plugin validates `botId`, `webhookSecret`, and `webhookPath`
+- if `agentId` is set, the message is routed directly to that agent
+- the reply is sent back to Pinto
+
+Notes:
+
+- If you do not need multiple agents yet, start with `agentId: "main"`
+- If `agentId` is omitted, the plugin falls back to normal OpenClaw routing
+- If you use `observerAgentIds`, they observe the same inbound message but do not send replies to Pinto
+
 ### Pinto Configuration
 
 Your Pinto bot must have:
@@ -546,8 +951,8 @@ Your Pinto bot must have:
   - The URL Pinto calls
   - Example:
   - `https://your-host.example.com/plugins/pinto/webhook`
-- Bot UUID
-  - Use the bot `_id` as `Bot Id` in OpenClaw
+- Bot ID
+  - Use the bot `bot_id` as `Bot Id` in OpenClaw
 - If webhook security is enabled
   - Pinto must send `X-Pinto-Secret`
   - The value must match the OpenClaw `Webhook Secret`
@@ -602,7 +1007,7 @@ Example request body:
 
 ```json
 {
-  "bot_id": "20387880-7934-40c3-b7d4-9fa6557697cf",
+  "bot_id": "bot-sales",
   "chat_id": "5f315d4e-cf22-4054-bbb0-2fe074bd3892",
   "message": "hello",
   "user_id": "a7c3fe36-cf41-42b5-a290-ca98e6129fac",
@@ -622,7 +1027,7 @@ Example body:
 
 ```json
 {
-  "bot_id": "20387880-7934-40c3-b7d4-9fa6557697cf",
+  "bot_id": "bot-sales",
   "chat_id": "5f315d4e-cf22-4054-bbb0-2fe074bd3892",
   "reply_message": "Hello from OpenClaw"
 }
@@ -632,7 +1037,7 @@ Media example:
 
 ```json
 {
-  "bot_id": "20387880-7934-40c3-b7d4-9fa6557697cf",
+  "bot_id": "bot-sales",
   "chat_id": "5f315d4e-cf22-4054-bbb0-2fe074bd3892",
   "reply_message": "See this image",
   "media_url": "https://example.com/image.png"
@@ -665,7 +1070,7 @@ curl -i -X POST http://127.0.0.1:18789/plugins/pinto/webhook \
   -H 'Content-Type: application/json' \
   -H 'X-Pinto-Secret: pinto-oc-9f3a1b7c5d2e8k4m' \
   -d '{
-    "bot_id":"20387880-7934-40c3-b7d4-9fa6557697cf",
+    "bot_id":"bot-sales",
     "chat_id":"5f315d4e-cf22-4054-bbb0-2fe074bd3892",
     "message":"hello",
     "user_id":"a7c3fe36-cf41-42b5-a290-ca98e6129fac"
@@ -685,7 +1090,7 @@ curl -i -X POST https://your-host.example.com/plugins/pinto/webhook \
   -H 'Content-Type: application/json' \
   -H 'X-Pinto-Secret: pinto-oc-9f3a1b7c5d2e8k4m' \
   -d '{
-    "bot_id":"20387880-7934-40c3-b7d4-9fa6557697cf",
+    "bot_id":"bot-sales",
     "chat_id":"5f315d4e-cf22-4054-bbb0-2fe074bd3892",
     "message":"hello",
     "user_id":"a7c3fe36-cf41-42b5-a290-ca98e6129fac"
@@ -699,7 +1104,7 @@ curl -i -X POST https://api.pinto-app.com/v1/bots/webhook/receive \
   -H 'Content-Type: application/json' \
   -H 'X-Pinto-Secret: pinto-oc-9f3a1b7c5d2e8k4m' \
   -d '{
-    "bot_id":"20387880-7934-40c3-b7d4-9fa6557697cf",
+    "bot_id":"bot-sales",
     "chat_id":"5f315d4e-cf22-4054-bbb0-2fe074bd3892",
     "reply_message":"OpenClaw outbound test"
   }'
@@ -727,7 +1132,7 @@ Common causes:
 
 Common causes:
 
-- `Bot Id` is not a real UUID
+- `Bot Id` does not match the real Pinto `bot_id`
 - `chat_id` belongs to a different environment
 - The payload sent to `POST /v1/bots/webhook/receive` does not match Pinto backend expectations