Public API v1
API reference
Every endpoint by group, with parameters, request body and a curl command.
Call it remotely through the Internet address under Settings → Internet & Cloud (the “Employees and API” service).
System4Health check, key info, server info.GETendpointsAccounts10Zalo, Facebook and Telegram accounts on the machine: list, status, connection, proxy.GETPOSTPUTPATCHendpointsChat44Conversations and messages on every channel: read, search, send, recall, react, pin, mark as read.GETPATCHDELETEPOSTPUTendpointsMedia13Upload files to send, download attachments, media library.GETPOSTDELETEPATCHendpointsLabels & quick replies30Conversation labels (local), quick replies, stickers.GETPOSTPATCHDELETEPUTendpointsGroups38Group chats: info, members, renaming, invite links.GETPOSTPATCHDELETEPUTendpointsContacts19Friends, friend requests, user lookup.GETPOSTDELETEPUTendpointsProduct catalog8GETPOSTDELETEPATCHendpointsCRM13Customers, CRM tags, notes, messaging campaigns.GETPATCHPOSTDELETEendpointsCampaigns15GETPOSTPATCHDELETEendpointsWorkflow16Automation workflows: read, edit, enable/disable, run, trigger.api events.GETPOSTPUTPATCHDELETEendpointsIntegrations9POS, shipping and payment connections: call adapter actions.GETPOSTPATCHDELETEendpointsERP49Tasks, projects, calendar, notes, attendance, leave, notifications.GETPOSTPATCHDELETEendpointsAI9AI assistants: chat, reply suggestions, usage statistics.GETPOSTendpointsReports1Overview, message volume, peak hours, campaign and workflow reports.GETendpointsEmployees13Manage employees, module permissions, account assignment.GETPOSTPATCHDELETEPUTendpointsEvents3Receive realtime events: Socket.IO, SSE, polling.GETendpointsWebhook8Register outbound webhooks signed with HMAC.GETPOSTPATCHDELETEendpointsPlugin5Routes registered by plugins, and plugin info.GETPOSTPUTPATCHDELETEendpoints
Error codes
| Code | HTTP | Description |
|---|---|---|
UNAUTHORIZED | 401 | Key missing, invalid, revoked or expired |
FORBIDDEN_SCOPE | 403 | The key lacks the scope this endpoint requires |
FORBIDDEN_ACCOUNT | 403 | The key has not been granted this account |
FORBIDDEN_IP | 403 | The calling IP is not in the key's allowlist |
FORBIDDEN_ERP | 403 | The key's ERP role does not have permission |
NOT_FOUND | 404 | Endpoint or data not found |
METHOD_NOT_ALLOWED | 405 | Sai HTTP method |
VALIDATION_ERROR | 400 | Invalid parameters (see details) |
INVALID_JSON | 400 | Body is not valid JSON |
PAYLOAD_TOO_LARGE | 413 | Body exceeds the size limit |
CONFLICT | 409 | State conflict |
ACCOUNT_OFFLINE | 409 | Account not connected |
CHANNEL_UNSUPPORTED | 422 | The account's channel does not support this operation |
RATE_LIMITED | 429 | Exceeded the rate limit you set for the key |
AUTH_BLOCKED | 429 | IP temporarily blocked for sending too many invalid keys |
UPSTREAM_ERROR | 502 | Zalo/Facebook/Telegram or an internal handler returned an error |
NOT_IMPLEMENTED | 501 | The corresponding IPC channel is missing |
API_DISABLED | 503 | The API is turned off in Settings (Cài đặt) |
TIMEOUT | 504 | Processing took longer than allowed |
PLUGIN_ERROR | 502 | The plugin's route/node returned an error |
PLUGIN_DISABLED | 404 | Plugin not installed or disabled |
INTERNAL_ERROR | 500 | Unexpected error |
Scopes
| Scope | Description |
|---|---|
accounts:read | Accounts · View accounts and their status |
accounts:manage | Accounts · Connect, disconnect, change proxy |
chat:read | Chat · Read conversations, messages, labels, quick replies |
chat:send | Chat · Send messages, files, stickers, reactions, typing |
chat:manage | Chat · Mark as read, recall, pin, assign labels, manage groups |
contacts:read | Contacts · View friends, friend requests, look up users |
contacts:write | Contacts · Send/accept/decline friend requests, unfriend |
crm:read | CRM · View customers, tags, notes, campaigns |
crm:write | CRM · Edit customers, tags, notes, campaigns |
campaigns:run | CRM · Start/stop campaigns |
workflow:read | Workflow · View workflows and run history |
workflow:write | Workflow · Create, edit, enable/disable, delete workflows |
workflow:run | Workflow · Run workflows, fire trigger.api events |
integrations:read | Integrations · View integrations (credentials never exposed) |
integrations:execute | Integrations · Call integration actions (POS, shipping...) |
integrations:manage | Integrations · Add integrations, edit credentials, enable/disable, delete integrations |
erp:read | ERP · View tasks, projects, calendar, notes, staff |
erp:write | ERP · Create/edit tasks, projects, calendar, notes |
ai:use | AI · Chat with AI assistants, reply suggestions |
ai:manage | AI · Manage AI assistants, view usage statistics |
media:read | Media · Download attachments, media library |
media:write | Media · Upload files, manage the media library |
analytics:read | Reports · View reports |
events:subscribe | Events · Receive realtime events (Socket.IO, SSE, polling) |
webhooks:manage | Events · Manage this key's webhook subscriptions |
employees:manage | Administration · Manage employees, permissions, account assignment |
settings:read | Administration · Read settings (allowlisted) |
settings:write | Administration · Write settings (allowlisted) |
plugins:manage | Administration · Manage apps (plugins) |
admin | Administration · Full access (every scope above) |