@framers/agentos-ext-channel-zalo 0.1.4 → 0.1.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +74 -0
- package/manifest.json +1 -1
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Zalo channel
|
|
2
|
+
|
|
3
|
+
This pack gives an agent text messaging through the Zalo Bot API using HTTP requests, with inbound updates from long polling or a registered webhook handler.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @framers/agentos-ext-channel-zalo
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Peer dependency: `@framers/agentos` `>=0.10.40`.
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { AgentOS } from '@framers/agentos';
|
|
17
|
+
|
|
18
|
+
const agentos = await AgentOS.create({
|
|
19
|
+
extensionManifest: {
|
|
20
|
+
packs: [
|
|
21
|
+
{
|
|
22
|
+
package: '@framers/agentos-ext-channel-zalo',
|
|
23
|
+
options: { botToken: process.env.ZALO_BOT_TOKEN },
|
|
24
|
+
},
|
|
25
|
+
],
|
|
26
|
+
},
|
|
27
|
+
});
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Configuration
|
|
31
|
+
|
|
32
|
+
| Option | Secret id | Environment variable | Required | Default |
|
|
33
|
+
| --- | --- | --- | --- | --- |
|
|
34
|
+
| `botToken` | `zalo.botToken` | `ZALO_BOT_TOKEN` | Yes | None |
|
|
35
|
+
| `webhookSecret` | `zalo.webhookSecret` | `ZALO_WEBHOOK_SECRET` | No | Empty string |
|
|
36
|
+
| `webhookPath` | None | `ZALO_WEBHOOK_PATH` | No | `/zalo-webhook` |
|
|
37
|
+
| `poll` | None | None | No | Enabled unless `false` or a webhook secret resolves |
|
|
38
|
+
| `pollTimeoutSec` | None | None | No | `30` seconds |
|
|
39
|
+
| `maxBodyBytes` | None | None | No | `1024 * 1024` bytes |
|
|
40
|
+
| `priority` | None | None | No | `50` |
|
|
41
|
+
| `secrets` | `zalo.botToken`, `zalo.webhookSecret` | None | No | None |
|
|
42
|
+
|
|
43
|
+
Token and webhook secret resolve from options, then `options.secrets`, then environment variables. Webhook secrets are trimmed. Webhook paths gain a leading slash and lose a trailing slash. A webhook secret disables polling even if `poll` is `true`.
|
|
44
|
+
|
|
45
|
+
## Tools
|
|
46
|
+
|
|
47
|
+
| Tool | What it does |
|
|
48
|
+
| --- | --- |
|
|
49
|
+
| `zaloChannelSendMessage` | Send a text message through the Zalo channel adapter. |
|
|
50
|
+
|
|
51
|
+
### `zaloChannelSendMessage`
|
|
52
|
+
|
|
53
|
+
| Parameter | Type | Required | Description |
|
|
54
|
+
| --- | --- | --- | --- |
|
|
55
|
+
| `conversationId` | string | Yes | Target Zalo user/thread ID |
|
|
56
|
+
| `text` | string | Yes | Message text |
|
|
57
|
+
|
|
58
|
+
## Channel adapter
|
|
59
|
+
|
|
60
|
+
The adapter registers platform `zalo`. Sending uses the first text block and posts it to the Bot API's `sendMessage` endpoint. Incoming polling or webhook updates become direct or group text events. It uses message text or a caption, with `<media:image>` and `<media:sticker>` fallbacks for image and sticker events. Updates without chat ID, sender ID or usable text are ignored. Typing indicators do nothing.
|
|
61
|
+
|
|
62
|
+
Activation initializes the service and starts polling when enabled. The pack also registers the `zaloWebhook` HTTP handler. With a webhook secret set, the handler accepts requests at `webhookPath`, answers GET requests, and requires POST requests to carry a matching `x-bot-api-secret-token` header. Valid payloads are acknowledged and passed to the adapter. The pack does not start an HTTP server or register the webhook URL with Zalo.
|
|
63
|
+
|
|
64
|
+
## Notes
|
|
65
|
+
|
|
66
|
+
Creating the pack throws if no bot token resolves. Sending trims the target and text, rejects empty values and truncates messages to `2000` characters. Sends change the target chat's content. If the API supplies no message ID, the service generates one locally.
|
|
67
|
+
|
|
68
|
+
Polling timeouts are floored and clamped between `5` and `60` seconds; the HTTP request deadline adds `5` seconds. Polling API timeout errors are ignored, while other errors log a warning and pause for `2500` ms before continuing. Send requests have no explicit timeout.
|
|
69
|
+
|
|
70
|
+
Webhook bodies default to a `1024 * 1024`-byte limit. A positive finite `maxBodyBytes` overrides it. Missing or mismatched secret headers, oversized bodies, invalid payloads and unsupported methods receive error responses. With `poll: false` and no webhook secret, neither inbound transport runs.
|
|
71
|
+
|
|
72
|
+
## License
|
|
73
|
+
|
|
74
|
+
Apache-2.0
|
package/manifest.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"$schema": "https://agentos.sh/schemas/extension-manifest-v1.json",
|
|
3
3
|
"id": "com.framers.channels.zalo",
|
|
4
4
|
"name": "Zalo Channel Extension",
|
|
5
|
-
"version": "0.1.
|
|
5
|
+
"version": "0.1.5",
|
|
6
6
|
"description": "Zalo Bot API — text messaging with optional webhook or long-polling.",
|
|
7
7
|
"categories": ["channel", "communication"],
|
|
8
8
|
"platforms": ["zalo"],
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@framers/agentos-ext-channel-zalo",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.5",
|
|
4
4
|
"description": "Zalo Bot API channel adapter for AgentOS — polling + webhook support",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"types": "dist/index.d.ts",
|
|
@@ -27,7 +27,7 @@
|
|
|
27
27
|
"@types/node": "^20.0.0",
|
|
28
28
|
"typescript": "^5.0.0",
|
|
29
29
|
"vitest": "^3.2.7",
|
|
30
|
-
"@framers/agentos": "^0.13.
|
|
30
|
+
"@framers/agentos": "^0.13.47"
|
|
31
31
|
},
|
|
32
32
|
"engines": {
|
|
33
33
|
"node": ">=22"
|