curl -X POST http://localhost:8080/admin/users \\ \n-H \"Authorization: $ZUCKZAPGO_ADMIN_TOKEN\" \\ \n-H \"Content-Type: application/json\" \\ \n-d '{\"name\": \"John\", \"token\": \"Z1234ABCCXD\"}' Configure tenant-level skips for the shared dispatcher via /session/globaltransports/config and toggle Info.IsFromAPI emission through /session/echo/api. Both flows are surfaced in the dashboard and Postman collection.
ECHO_API_MESSAGES_ENABLED is true and the per-session echo setting is enabled, every successful API send emits a synthetic Message event through your configured transports/webhook. These events include the Info.IsFromAPI: true marker so downstream consumers can distinguish API-originated traffic. This ensures API-sent messages pass through the same filters/media pipeline as user-originated messages.\n\nPer-Message Echo Control (EchoApi Field)EchoApi boolean field that provides message-level control over echo behavior. When set to true, the message will emit an API echo event regardless of global (ECHO_API_MESSAGES_ENABLED) or per-session (echo_api_messages) settings. This allows selective tracking of specific API-sent messages without enabling echo for all messages. The field is completely optional and defaults to respecting the configured echo settings when omitted. Use cases include: tracking critical business messages, monitoring specific conversation flows, or debugging individual message delivery."
- name: Label
description: Chat labeling and organization features
- name: Group
description: Group management including creation, participant management, and group settings
- name: Community
description: Community and sub-group management, announcements, and join requests
- name: Business
description: Business profiles, bots, order messages, and business-specific features
- name: Device
description: Device management, platform detection, and linked device information
- name: Privacy
description: Privacy settings, blocklist management, and disappearing message configuration
- name: Newsletter
description: Newsletter/channel management, subscriptions, and newsletter messaging
- name: Status
description: Status/story posting in various formats (text, image, video, audio)
- name: Call
description: Call handling and rejection operations
- name: Sync
description: Synchronization and data consistency management
paths:
/session/echo/api:
post:
tags:
- Session Echo
summary: Enable or disable API message echo
operationId: configureEchoApiMessages
description: |
Controls whether messages sent via this API should emit Message events through the standard transports/webhook pipeline.
Behavior:
- When enabled, after each successful send, the server emits a synthetic Message event flagged as API-sourced.
- Event marker: The emitted event's Info structure includes IsFromAPI: true
- The emitted event rides the same media/filters pipeline as regular messages.
Requirements:
- Global kill switch ECHO_API_MESSAGES_ENABLED must be true.
- This endpoint toggles the per-session setting stored on the user.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/EchoAPISettingsRequest"
responses:
200:
description: Echo API messages configuration updated
content:
application/json:
schema:
$ref: "#/definitions/EchoAPISettingsResponse"
401:
description: Unauthorized - user token required
content:
application/json:
schema:
example: { "error": "unauthorized" }
500:
description: Internal server error
content:
application/json:
schema:
example:
{
"error": "failed to update echo api messages configuration",
}
get:
tags:
- Session Echo
summary: Get API message echo configuration
operationId: getEchoApiMessagesConfig
description: |
Retrieves whether API message echo is enabled for this session.
Note: The global kill switch ECHO_API_MESSAGES_ENABLED must be true for echo events to be emitted even when the per-session flag is enabled.
security:
- ApiKeyAuth: []
responses:
200:
description: Echo API messages configuration retrieved
content:
application/json:
schema:
$ref: "#/definitions/EchoAPISettingsResponse"
401:
description: Unauthorized - user token required
content:
application/json:
schema:
example: { "error": "unauthorized" }
500:
description: Internal server error
content:
application/json:
schema:
example:
{ "error": "failed to get echo api messages configuration" }
/admin/users:
get:
tags:
- Admin
summary: List all users
description: Retrieve a complete list of all ZuckZapGo users with their full configuration including connection status, webhook settings, proxy configuration, S3 storage, RabbitMQ messaging, WhatsApp configuration, and event filtering preferences.
security:
- AdminAuth: []
responses:
200:
description: A JSON array of user objects with complete configuration
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
data:
type: array
items:
$ref: "#/definitions/User"
success:
type: boolean
example: true
example:
{
"code": 200,
"data":
[
{
"connected": true,
"loggedIn": true,
"events": "All",
"expiration": 0,
"id": "bec45bb93cbd24cbec32941ec3c93a12",
"jid": "5491155551122:12@s.whatsapp.net",
"name": "Some User",
"avatar_url": "https://example.com/avatar.jpg",
"token": "d030sl9aDL39sl3075zz",
"webhook": "https://some.domain/webhook",
"qrcode": "",
"skip_media_download": false,
"skip_groups": false,
"skip_newsletters": false,
"skip_broadcasts": false,
"skip_own_messages": false,
"skip_calls": false,
"call_reject_message": "Sorry, I cannot take calls at the moment.",
"call_reject_type": "busy",
"globalTransportSkips":
{
"skipGlobalWebhook": false,
"skipGlobalRabbitMQ": false,
"skipGlobalSQS": false,
"skipGlobalRedis": false,
"skipGlobalWebSocket": false,
"skipGlobalS3": false,
},
"isFromAPI": false,
"proxy_config": { "enabled": false, "proxy_url": "" },
"s3_config": { "enabled": false },
"rabbitmq_config": { "enabled": false },
"whatsapp_config":
{
"wa_platform": "WEB",
"wa_release_channel": "RELEASE",
},
"echo_api_messages": false,
},
],
"success": true,
}
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
500:
description: Internal server error
content:
application/json:
schema:
example:
{
"code": 500,
"error": "problem accessing DB",
"success": false,
}
post:
tags:
- Admin
summary: Create a new ZuckZapGo user account
description: Create a new ZuckZapGo user account with complete configuration options including webhook URL, proxy settings, S3 storage configuration, RabbitMQ messaging setup, WhatsApp client configuration, and event filtering settings. The user will receive a unique ID and authentication token upon successful creation. All configuration options are optional and will use sensible defaults if not provided. Admin authentication required. `s3Config` accepts both `snake_case` and `camelCase` keys for compatibility.
security:
- AdminAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/CreateUser"
responses:
201:
description: User created
content:
application/json:
schema:
$ref: "#/definitions/User"
example:
code: 201
data:
id: "5663e0c52063ec35d0ba45f7c2011c06"
name: "John Doe"
token: "1234ABCD"
echoApiMessages: false
skipMediaDownload: false
skipGroups: false
skipNewsletters: false
skipBroadcasts: false
skipOwnMessages: false
globalTransportSkips:
skipGlobalWebhook: false
skipGlobalRabbitMQ: false
skipGlobalSQS: false
skipGlobalRedis: false
skipGlobalWebSocket: false
skipGlobalS3: false
isFromAPI: false
skipCalls: false
callRejectMessage: "Sorry, I cannot take calls at the moment."
callRejectType: "busy"
webhook: "https://webhook.site/1234567890"
events: "All"
proxyConfig:
enabled: true
proxyURL: "https://serverproxy.com:9080"
s3Config:
enabled: true
endpoint: "https://s3.amazonaws.com"
region: "us-east-1"
bucket: "my-bucket"
access_key: "***"
secret_key: "***"
path_style: true
public_url: "https://s3.amazonaws.com"
media_delivery: "both"
retention_days: 30
disable_acl: true
rabbitmqConfig:
enabled: true
url: "amqp://guest:guest@localhost:5672/"
events: "All"
exchange: "whatsapp.events"
exchange_type: "topic"
queue: "whatsapp.user.{user_id}"
queue_type: "classic"
routing_key: "whatsapp.{event_type}"
durable: true
auto_delete: false
exclusive: false
no_wait: false
delivery_mode: 2
dead_letter_exchange: "dlx.whatsapp"
dead_letter_routing_key: "dlq.events"
message_ttl: 86400000
max_length: 100000
max_length_bytes: 104857600
queue_arguments: { "x-overflow": "reject-publish" }
exchange_arguments: {}
whatsappConfig:
waVersion: "2.3000.1026436087"
waPlatform: "WEB"
waReleaseChannel: "RELEASE"
waWebSubPlatform: "WEB_BROWSER"
waOsName: "Mac OS 10"
waOsVersion: "10.15.7"
waDeviceName: "Desktop"
waManufacturer: "Apple"
waDeviceBoard: ""
waLocaleLanguage: "en"
waLocaleCountry: "US"
waMcc: "000"
waMnc: "000"
waConnectType: "WIFI_UNKNOWN"
waPlatformType: "DESKTOP"
/admin/instances/status:
get:
tags:
- Admin
summary: List instance connection status
description: |
Retrieve a lightweight paginated view of instance connection health using runtime state when available and database fallback when no in-memory client is present.
Each entry includes the current QR code (base64 PNG and raw text) for unpaired instances. QR code fields are only populated when the instance is not connected or not logged in.
security:
- AdminAuth: []
parameters:
- in: query
name: limit
schema:
type: integer
default: 200
minimum: 1
maximum: 1000
description: Number of instances per page (default 200, max 1000)
- in: query
name: offset
schema:
type: integer
default: 0
minimum: 0
description: Pagination offset
- in: query
name: ids
schema:
type: string
description: Optional comma-separated list of instance IDs for selective lookup
- in: query
name: include_total
schema:
type: boolean
default: false
description: When true, includes total row count in pagination metadata
responses:
200:
description: Paginated status list
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
data:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
jid:
type: string
qrcode:
type: string
description: "Base64 PNG QR code for pairing (empty when connected and logged in)"
qrcode_text:
type: string
description: "Raw QR code text string for pairing (empty when connected and logged in)"
connected:
type: boolean
loggedIn:
type: boolean
hasClient:
type: boolean
connectionHealth:
type: string
enum:
[
"connected",
"connected_not_logged",
"disconnected",
"no_client",
]
lastSuccessfulConnect:
type: integer
format: int64
autoReconnectErrors:
type: integer
enableAutoReconnect:
type: boolean
source:
type: string
enum: ["runtime", "database"]
timestamp:
type: string
format: date-time
pagination:
type: object
properties:
limit:
type: integer
offset:
type: integer
has_more:
type: boolean
next_offset:
type: integer
nullable: true
total:
type: integer
success:
type: boolean
example: true
example:
code: 200
data:
- id: "4721ca1031bc81b888efc7f407e455ad"
name: "teste-api-com-s3"
jid: "5511999999999@s.whatsapp.net"
qrcode: ""
qrcode_text: ""
connected: true
loggedIn: true
hasClient: true
connectionHealth: "connected"
lastSuccessfulConnect: 1740248400
autoReconnectErrors: 0
enableAutoReconnect: false
source: "runtime"
timestamp: "2026-02-22T15:05:00Z"
pagination:
limit: 200
offset: 0
has_more: false
next_offset: null
success: true
400:
description: Invalid pagination/filter parameter
content:
application/json:
schema:
example:
{
"code": 400,
"error": "invalid limit parameter",
"success": false,
}
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
500:
description: Internal server error
content:
application/json:
schema:
example:
{ "code": 500, "error": "database error", "success": false }
/admin/users/{id}:
get:
tags:
- Admin
summary: Get specific user by ID
description: Retrieve detailed information about a specific ZuckZapGo user by their unique ID, including complete configuration, connection status, webhook settings, proxy configuration, S3 storage, RabbitMQ messaging, WhatsApp configuration, and event filtering preferences.
security:
- AdminAuth: []
parameters:
- name: id
in: path
required: true
description: Unique ID of the user to retrieve
schema:
type: string
example: 4e4942c7dee1deef99ab8fd9f7350de5
responses:
200:
description: User details retrieved successfully
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
data:
type: array
items:
$ref: "#/definitions/User"
description: "Array containing the single user object"
success:
type: boolean
example: true
example:
{
"code": 200,
"data":
[
{
"connected": true,
"loggedIn": true,
"events": "All",
"expiration": 0,
"id": "4e4942c7dee1deef99ab8fd9f7350de5",
"jid": "5491155551122:12@s.whatsapp.net",
"name": "John Doe",
"avatar_url": "https://example.com/avatar.jpg",
"token": "1234ABCD",
"webhook": "https://webhook.site/1234567890",
"qrcode": "",
"skip_media_download": false,
"skip_groups": false,
"skip_newsletters": false,
"skip_broadcasts": false,
"skip_own_messages": false,
"skip_calls": false,
"call_reject_message": "Sorry, I cannot take calls at the moment.",
"call_reject_type": "busy",
"globalTransportSkips":
{
"skipGlobalWebhook": false,
"skipGlobalRabbitMQ": false,
"skipGlobalSQS": false,
"skipGlobalRedis": false,
"skipGlobalWebSocket": false,
"skipGlobalS3": false,
},
"isFromAPI": false,
"proxy_config":
{
"enabled": true,
"proxy_url": "https://serverproxy.com:9080",
},
"s3_config":
{
"enabled": true,
"endpoint": "https://s3.amazonaws.com",
"region": "us-east-1",
"bucket": "my-bucket",
},
"rabbitmq_config":
{
"enabled": true,
"url": "amqp://guest:guest@localhost:5672/",
"exchange": "whatsapp.events",
},
"whatsapp_config":
{
"wa_platform": "WEB",
"wa_release_channel": "RELEASE",
"wa_web_sub_platform": "WEB_BROWSER",
},
"echo_api_messages": false,
},
],
"success": true,
}
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
404:
description: User not found
content:
application/json:
schema:
example:
{ "code": 404, "error": "user not found", "success": false }
500:
description: Internal server error
content:
application/json:
schema:
example:
{
"code": 500,
"error": "problem accessing DB",
"success": false,
}
delete:
tags:
- Admin
summary: Delete a user from DB
description: Deletes a user by their ID.
security:
- AdminAuth: []
parameters:
- name: id
in: path
required: true
description: ID of the user to delete
schema:
type: string
example: 4e4942c7dee1deef99ab8fd9f7350de5
responses:
200:
description: User deleted
content:
application/json:
schema:
example:
{
"code": 200,
"data": { "id": "6b927654cada7635a4586bf8fad260a3" },
"details": "User deleted successfully",
"success": true,
}
/admin/users/{id}/full:
delete:
tags:
- Admin
summary: Delete a user from DB, S3, RabbitMQ, logout and disconnect from whatsapp and clear it up from memory
description: Deletes a user by their ID, including login out, disconnect and memory cleanup Also removes all user files from S3 and RabbitMQ.
security:
- AdminAuth: []
parameters:
- name: id
in: path
required: true
description: ID of the user to delete
schema:
type: string
example: 4e4942c7dee1deef99ab8fd9f7350de5
responses:
200:
description: User deleted
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"id": "4e4942c7dee1deef99ab8fd9f7350de5",
"jid": "",
"name": "mariano",
},
"details": "User instance removed completely",
"success": true,
}
/admin/license/info:
get:
tags:
- Admin License
summary: Get license information
description: |
Retrieve complete license information including validation status, expiration date, features, and grace period details.
**Status Types**:
- `active`: License valid and active
- `expiring_soon`: License expires within 7 days (renewal recommended)
- `grace_period`: License in grace period after expiration (limited time to renew)
- `expired`: License expired (limited functionality)
**Plan Types**:
- `BASIC`: Basic features and standard support
- `PRO`: Advanced features and priority support
- `ENTERPRISE`: Full features, 24/7 support, and SLA guarantees
**Authentication**: Requires admin token in Authorization header
security:
- AdminAuth: []
responses:
200:
description: License information retrieved successfully
content:
application/json:
schema:
type: object
required:
- valid
- installation_id
- customer_id
- installation_name
- plan_type
- expires_at
- max_instances
- license_key
- instance_id
- last_validation
- days_until_expiry
- is_in_grace_period
- status
- status_message
- features
- support_email
- documentation_url
properties:
valid:
type: boolean
description: Whether the license is currently valid
example: true
installation_id:
type: string
description: Unique installation identifier
example: "inst_1234567890abcdef"
customer_id:
type: string
description: Customer account identifier
example: "cust_abcdef1234567890"
installation_name:
type: string
description: Human-readable installation name
example: "Production Server - São Paulo"
plan_type:
type: string
description: Current subscription plan
enum: [BASIC, PRO, ENTERPRISE]
example: "ENTERPRISE"
expires_at:
type: string
format: date-time
description: License expiration date and time (UTC)
example: "2025-12-31T23:59:59Z"
max_instances:
type: integer
description: Maximum number of concurrent instances allowed
example: 10
license_key:
type: string
description: Complete license key (frontend controls visibility via toggle)
example: "ZUCKZAP-ENT-2024-ABCD1234-EFGH5678-IJKL9012"
instance_id:
type: string
description: Current running instance identifier
example: "zuckzapgo-prod-01"
last_validation:
type: string
format: date-time
description: Timestamp of last successful license validation
example: "2025-10-31T12:00:00Z"
days_until_expiry:
type: integer
description: Number of days remaining until license expires (negative if expired)
example: 61
is_in_grace_period:
type: boolean
description: Whether license is currently in grace period
example: false
grace_period_end:
type: string
format: date-time
description: Grace period end date (only present when is_in_grace_period is true)
example: "2025-11-07T23:59:59Z"
status:
type: string
description: Current license status
enum: [active, expiring_soon, grace_period, expired]
example: "active"
status_message:
type: string
description: Human-readable status message
example: "Licença ativa e válida"
features:
type: array
description: List of features available in current plan
items:
type: string
example:
- "API RESTful completa"
- "Suporte a múltiplas instâncias"
- "Eventos em tempo real"
- "Suporte 24/7"
- "SLA garantido"
- "Botões interativos"
support_email:
type: string
format: email
description: Support contact email
example: "suporte@setupautomatizado.com.br"
documentation_url:
type: string
format: uri
description: Documentation URL
example: "https://github.com/guilhermejansen/use-zuckzapgo"
example:
{
"valid": true,
"installation_id": "inst_1234567890abcdef",
"customer_id": "cust_abcdef1234567890",
"installation_name": "Production Server - São Paulo",
"plan_type": "ENTERPRISE",
"expires_at": "2025-12-31T23:59:59Z",
"max_instances": 10,
"license_key": "ZUCKZAP-ENT-2024-ABCD1234-EFGH5678-IJKL9012",
"instance_id": "zuckzapgo-prod-01",
"last_validation": "2025-10-31T12:00:00Z",
"days_until_expiry": 61,
"is_in_grace_period": false,
"status": "active",
"status_message": "Licença ativa e válida",
"features":
[
"API RESTful completa",
"Suporte a múltiplas instâncias",
"Eventos em tempo real",
"Suporte prioritário",
"Integrações avançadas",
"Suporte 24/7",
"SLA garantido",
"Botões interativos",
],
"support_email": "suporte@setupautomatizado.com.br",
"documentation_url": "https://github.com/guilhermejansen/use-zuckzapgo",
}
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: "unauthorized - admin token required"
code:
type: integer
example: 401
503:
description: Service unavailable - License validator not initialized or cache unavailable
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: "License information not available"
code:
type: integer
example: 503
/newsletter/list:
get:
tags:
- Newsletter
summary: List subscribed newsletters
description: Get complete list of subscribed newsletters with metadata
security:
- ApiKeyAuth: []
responses:
200:
description: Newsletter list retrieved successfully
content:
application/json:
schema:
example:
{
"Newsletter":
[
{
"id": "1203631448483540@newsletter",
"state": { "type": "active" },
"thread_metadata":
{
"creation_time": "1688746895",
"description":
{
"id": "1689653839450668",
"text": "WhatsApp's official channel",
"update_time": "1689653839450668",
},
"invite": "0029Va4K0PZ5a245NkngBA2M",
"name":
{
"id": "1688746895480511",
"text": "WhatsApp",
"update_time": "1688746895480511",
},
"subscribers_count": "1000000",
"verification": "verified",
},
"viewer_metadata":
{ "mute": "off", "role": "subscriber" },
},
],
}
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "no session" }
/newsletter/create:
post:
tags:
- Newsletter
summary: Create new newsletter/channel
description: Create a new WhatsApp newsletter/channel with optional picture (supports base64 data URLs and HTTP(S) URLs)
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
description: Newsletter name (automatically truncated to 25 characters)
maxLength: 25
example: "My Newsletter"
description:
type: string
description: Newsletter description (optional)
example: "A newsletter about interesting topics"
picture:
type: string
description: Base64 data URL (data:image/jpeg;base64,...) or HTTP(S) URL for newsletter picture. Supported formats JPEG, PNG, GIF, WebP
example: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
responses:
200:
description: Newsletter created successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
jid:
type: string
name:
type: string
message:
type: string
example:
{
"success": true,
"jid": "120363025246817665@newsletter",
"name": "My Newsletter",
"message": "Newsletter created successfully",
}
400:
description: Bad request - validation error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example: { "success": false, "message": "name is required" }
500:
description: Internal server error - no session
content:
application/json:
schema:
type: string
example: "no session"
/newsletter/subscribed:
get:
tags:
- Newsletter
summary: Get subscribed newsletters
description: List all newsletters that the user is subscribed to with structured information
security:
- ApiKeyAuth: []
responses:
200:
description: Subscribed newsletters retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
newsletters:
type: array
items:
type: object
properties:
jid:
type: string
name:
type: string
description:
type: string
subscribers:
type: integer
muted:
type: boolean
invite_code:
type: string
example:
{
"success": true,
"newsletters":
[
{
"jid": "120363025246817665@newsletter",
"name": "Tech News",
"description": "Latest tech updates",
"subscribers": 1500,
"muted": false,
"invite_code": "ABC123XYZ",
},
],
}
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example: { "success": false, "message": "no session" }
/newsletter/info:
post:
tags:
- Newsletter
summary: Get newsletter information
description: Get detailed information about a specific newsletter by JID
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- jid
properties:
jid:
type: string
description: Newsletter JID (format 120363025246817665@newsletter)
example: "120363025246817665@newsletter"
responses:
200:
description: Newsletter information retrieved successfully
content:
application/json:
schema:
type: object
properties:
jid:
type: string
name:
type: string
description:
type: string
subscribers:
type: integer
invite_code:
type: string
muted:
type: boolean
role:
type: string
example:
{
"jid": "120363025246817665@newsletter",
"name": "Tech News",
"description": "Latest technology updates",
"subscribers": 1500,
"invite_code": "ABC123XYZ",
"muted": false,
"role": "subscriber",
}
400:
description: Bad request - invalid newsletter ID
content:
application/json:
schema:
type: string
example: "invalid newsletter ID"
500:
description: Internal server error
content:
application/json:
schema:
type: string
example: "no session"
/newsletter/send:
post:
tags:
- Newsletter
summary: Send message to newsletter
description: Send text, image, video, document, or audio message to a newsletter. Media supports both base64 data URLs and HTTP(S) URLs. Audio messages are sent as voice notes (PTT=true) for newsletters.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- jid
properties:
jid:
type: string
description: Newsletter JID
example: "120363025246817665@newsletter"
message:
type: string
description: Text message content (for text messages)
example: "Hello subscribers!"
image:
type: string
description: Base64 data URL (data:image/jpeg;base64,...) or HTTP(S) URL for image
example: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
video:
type: string
description: Base64 data URL (data:video/mp4;base64,...) or HTTP(S) URL for video
example: "https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4"
document:
type: string
description: Base64 data URL (data:application/pdf;base64,...) or HTTP(S) URL for document
example: "data:application/pdf;base64,JVBERi0xLjQKJcfs..."
audio:
type: string
description: Base64 data URL (data:audio/ogg;base64,...) or HTTP(S) URL for audio (automatically sent as voice note PTT=true for newsletters)
example: "data:audio/ogg;base64,T2dnUwACAAAAAAAAAAA..."
caption:
type: string
description: Caption for media messages (image, video)
example: "Check this out!"
filename:
type: string
description: Filename for document messages (defaults to 'document' if not provided)
example: "document.pdf"
oneOf:
- required: ["message"]
- required: ["image"]
- required: ["video"]
- required: ["document"]
- required: ["audio"]
responses:
200:
description: Message sent successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
id:
type: string
timestamp:
type: integer
format: int64
example:
{
"success": true,
"id": "3EB0C767D26A1D74",
"timestamp": 1640995200,
}
400:
description: Bad request - invalid input or no content
content:
application/json:
schema:
type: string
example: "no message content provided"
500:
description: Internal server error
content:
application/json:
schema:
type: string
example: "no session"
/newsletter/follow:
post:
tags:
- Newsletter
summary: Subscribe to newsletter
description: Subscribe to a newsletter using its JID
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- jid
properties:
jid:
type: string
description: Newsletter JID to subscribe to
example: "120363025246817665@newsletter"
responses:
200:
description: Successfully subscribed to newsletter
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
{ "success": true, "message": "Subscribed successfully" }
400:
description: Bad request - invalid newsletter ID
content:
application/json:
schema:
type: string
example: "invalid newsletter ID"
500:
description: Internal server error
content:
application/json:
schema:
type: string
example: "no session"
/newsletter/follow-invite:
post:
tags:
- Newsletter
summary: Subscribe via invite code
description: Subscribe to a newsletter using an invite code
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- invite_code
properties:
invite_code:
type: string
description: Newsletter invite code
example: "ABC123XYZ"
responses:
200:
description: Successfully subscribed via invite code
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
jid:
type: string
example:
{
"success": true,
"message": "Subscribed successfully",
"jid": "120363025246817665@newsletter",
}
500:
description: Internal server error
content:
application/json:
schema:
type: string
example: "error getting info"
/newsletter/unfollow:
post:
tags:
- Newsletter
summary: Unsubscribe from newsletter
description: Unsubscribe from a newsletter using its JID
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- jid
properties:
jid:
type: string
description: Newsletter JID to unsubscribe from
example: "120363025246817665@newsletter"
responses:
200:
description: Successfully unsubscribed from newsletter
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
{ "success": true, "message": "Unsubscribed successfully" }
400:
description: Bad request - invalid newsletter ID
content:
application/json:
schema:
type: string
example: "invalid newsletter ID"
500:
description: Internal server error
content:
application/json:
schema:
type: string
example: "no session"
/newsletter/unfollow-invite:
post:
tags:
- Newsletter
summary: Unsubscribe via invite code
description: Unsubscribe from a newsletter using an invite code
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- invite_code
properties:
invite_code:
type: string
description: Newsletter invite code
example: "ABC123XYZ"
responses:
200:
description: Successfully unsubscribed via invite code
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
{ "success": true, "message": "Unsubscribed successfully" }
500:
description: Internal server error
content:
application/json:
schema:
type: string
example: "error getting info"
/newsletter/mute:
post:
tags:
- Newsletter
summary: Mute/unmute newsletter notifications
description: Toggle mute status for newsletter notifications
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- jid
- mute
properties:
jid:
type: string
description: Newsletter JID
example: "120363025246817665@newsletter"
mute:
type: boolean
description: True to mute notifications, false to enable
example: true
responses:
200:
description: Mute status changed successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
{
"success": true,
"message": "Notifications muted successfully",
}
400:
description: Bad request - invalid JID
content:
application/json:
schema:
type: string
example: "invalid JID"
500:
description: Internal server error
content:
application/json:
schema:
type: string
example: "no session"
/newsletter/messages:
post:
tags:
- Newsletter
summary: Get newsletter messages
description: Retrieve messages from a newsletter with pagination support
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- jid
properties:
jid:
type: string
description: Newsletter JID
example: "120363025246817665@newsletter"
count:
type: integer
description: Number of messages to retrieve (default 25)
default: 25
example: 25
before:
type: integer
description: Server ID to get messages before this ID (for pagination)
example: 12345
responses:
200:
description: Newsletter messages retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
messages:
type: array
items:
type: object
properties:
id:
type: string
server_id:
type: integer
type:
type: string
timestamp:
type: integer
format: int64
text:
type: string
caption:
type: string
views_count:
type: integer
reaction_counts:
type: object
media:
type: object
example:
{
"success": true,
"messages":
[
{
"id": "3EB0C767D26A1D74",
"server_id": 12345,
"type": "text",
"timestamp": 1640995200,
"text": "Hello world!",
"views_count": 150,
"reaction_counts": { "👍": 25, "❤️": 10 },
},
],
}
400:
description: Bad request - invalid newsletter ID
content:
application/json:
schema:
type: string
example: "invalid newsletter ID"
500:
description: Internal server error
content:
application/json:
schema:
type: string
example: "no session"
/newsletter/reaction:
post:
tags:
- Newsletter
summary: Send reaction to newsletter message
description: Send an emoji reaction to a specific newsletter message
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- jid
- server_id
- reaction
properties:
jid:
type: string
description: Newsletter JID
example: "120363025246817665@newsletter"
server_id:
type: integer
description: Server ID of the message to react to
example: 12345
reaction:
type: string
description: Emoji reaction (empty string to remove reaction)
example: "👍"
responses:
200:
description: Reaction sent successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
{ "success": true, "message": "Reaction sent successfully" }
400:
description: Bad request - invalid JID
content:
application/json:
schema:
type: string
example: "invalid JID"
500:
description: Internal server error
content:
application/json:
schema:
type: string
example: "no session"
/newsletter/mark-viewed:
post:
tags:
- Newsletter
summary: Mark newsletter messages as viewed
description: Mark specific newsletter messages as viewed to update read status
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- jid
- server_ids
properties:
jid:
type: string
description: Newsletter JID
example: "120363025246817665@newsletter"
server_ids:
type: array
items:
type: integer
description: Array of server IDs to mark as viewed
example: [12345, 12346, 12347]
responses:
200:
description: Messages marked as viewed successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
{ "success": true, "message": "Messages marked as viewed" }
400:
description: Bad request - invalid JID
content:
application/json:
schema:
type: string
example: "invalid JID"
500:
description: Internal server error
content:
application/json:
schema:
type: string
example: "no session"
/newsletter/subscribe-live-updates:
post:
tags:
- Newsletter
summary: Subscribe to live updates
description: Subscribe to real-time updates for a newsletter (30 second timeout)
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- jid
properties:
jid:
type: string
description: Newsletter JID
example: "120363025246817665@newsletter"
responses:
200:
description: Successfully subscribed to live updates
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
duration:
type: number
format: float
message:
type: string
example:
{
"success": true,
"duration": 3600.0,
"message": "Subscribed to live updates",
}
400:
description: Bad request - invalid JID
content:
application/json:
schema:
type: string
example: "invalid JID"
500:
description: Internal server error
content:
application/json:
schema:
type: string
example: "no session"
/newsletter/message-updates:
post:
tags:
- Newsletter
summary: Get newsletter message updates
description: Get updates for newsletter messages with filtering options
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- jid
properties:
jid:
type: string
description: Newsletter JID
example: "120363025246817665@newsletter"
count:
type: integer
description: Number of updates to retrieve (optional)
example: 25
since:
type: integer
format: int64
description: Unix timestamp to get updates since (optional)
example: 1640995200
after:
type: integer
description: Server ID to get updates after (optional)
example: 12345
responses:
200:
description: Message updates retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
updates:
type: array
items:
type: object
properties:
id:
type: string
server_id:
type: integer
type:
type: string
timestamp:
type: integer
format: int64
views_count:
type: integer
reaction_counts:
type: object
text:
type: string
caption:
type: string
media:
type: object
example:
{
"success": true,
"updates":
[
{
"id": "3EB0C767D26A1D74",
"server_id": 12346,
"type": "text",
"timestamp": 1640995300,
"text": "Updated message",
"views_count": 200,
"reaction_counts": { "👍": 30, "❤️": 15 },
},
],
}
400:
description: Bad request - invalid JID
content:
application/json:
schema:
type: string
example: "invalid JID"
500:
description: Internal server error
content:
application/json:
schema:
type: string
example: "no session"
/newsletter/accept-tos:
post:
tags:
- Newsletter
summary: Accept Terms of Service
description: Accept WhatsApp Terms of Service notice required for newsletter creation
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
notice_id:
type: string
description: Terms of Service notice ID (default "20601218" for newsletter creation)
default: "20601218"
example: "20601218"
stage:
type: string
description: TOS stage (default "5" for newsletter creation)
default: "5"
example: "5"
responses:
200:
description: Terms of service accepted successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
{ "success": true, "message": "Terms of service accepted" }
500:
description: Internal server error
content:
application/json:
schema:
type: string
example: "no session"
/newsletter/admin-invite:
post:
tags:
- Newsletter
summary: Send Newsletter Admin Invite
description: Send an admin invitation for a newsletter to a phone number with image and custom message
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- phone
- newsletter_jid
- image
- caption
- name
properties:
phone:
type: string
description: Recipient phone number (with country code, no + prefix)
example: "5491155553934"
newsletter_jid:
type: string
description: Newsletter JID to invite admin for
example: "120363025246817665@newsletter"
image:
type: string
description: Base64 data URL or HTTP(S) URL for invitation image
example: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
caption:
type: string
description: Invitation message text
example: "You're invited to be an admin of our newsletter!"
name:
type: string
description: Newsletter/invite name
example: "Tech Newsletter Admin Invite"
responses:
200:
description: Admin invite sent successfully
content:
application/json:
schema:
example:
{
"success": true,
"id": "3EB0C767D26A1D74",
"timestamp": 1640995200,
"recipient": "5491155553934",
"newsletter_jid": "120363025246817665@newsletter",
"invite_name": "Tech Newsletter Admin Invite",
"expires_at": 1641600000,
"message": "Newsletter admin invite sent successfully",
}
400:
description: Bad request - invalid input
content:
application/json:
schema:
example:
{
"error": "phone, newsletter_jid, image, caption and name are required",
}
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "no session" }
/health:
get:
tags:
- System
summary: Health check
description: Returns system health status for monitoring purposes
responses:
200:
description: System is healthy
content:
application/json:
schema:
type: object
required:
- code
- data
- success
- status
- version
- uptime
- timestamp
- metrics
- environment
properties:
code:
type: integer
format: int32
description: HTTP status code mirrored from the response
example: 200
data:
type: string
description: Legacy health message (kept for backward compatibility)
example: OK
success:
type: boolean
description: Indicates the health endpoint responded successfully
example: true
status:
type: string
description: Aggregated health status derived from dependency checks
enum: [healthy, degraded, unhealthy]
example: healthy
version:
type: string
description: Running build version identifier
example: 3.0.0
uptime:
type: integer
format: int64
description: Uptime in seconds since the process started
example: 86400
timestamp:
type: string
format: date-time
description: Moment the health snapshot was generated (UTC)
example: 2024-01-01T12:00:00Z
metrics:
type: object
required: [goroutines, go_version, cpu_count, go_max_procs]
properties:
goroutines:
type: integer
example: 42
go_version:
type: string
example: go1.21.5
cpu_count:
type: integer
example: 8
go_max_procs:
type: integer
example: 8
environment:
type: object
required: [containerized]
properties:
containerized:
type: boolean
example: false
hostname:
type: string
nullable: true
example: zuckzapgo-01
app_env:
type: string
nullable: true
example: production
app_region:
type: string
nullable: true
example: us-east-1
build:
type: object
nullable: true
properties:
commit:
type: string
description: Deployed git commit hash (if available)
example: a1b2c3d4
services:
type: object
nullable: true
additionalProperties:
type: object
properties:
status:
type: string
description: Dependency health status
example: up
latency_ms:
type: number
format: float
example: 12.5
open_connections:
type: integer
example: 10
in_use:
type: integer
example: 2
idle:
type: integer
example: 8
driver:
type: string
example: postgres
error:
type: string
nullable: true
example: ""
example:
{
"code": 200,
"data": "OK",
"success": true,
"status": "healthy",
"version": "3.0.0",
"uptime": 86400,
"timestamp": "2024-01-01T12:00:00Z",
"metrics":
{
"goroutines": 42,
"go_version": "go1.21.5",
"cpu_count": 8,
"go_max_procs": 8,
},
"environment":
{
"containerized": false,
"hostname": "zuckzapgo-01",
"app_env": "production",
"app_region": "us-east-1",
},
"build": { "commit": "a1b2c3d4" },
"services":
{
"database":
{
"status": "up",
"latency_ms": 12.5,
"open_connections": 10,
"in_use": 2,
"idle": 8,
"driver": "postgres",
},
},
}
503:
description: System is unhealthy
content:
application/json:
schema:
type: object
required:
- code
- data
- success
- status
- version
- uptime
- timestamp
- metrics
- environment
properties:
code:
type: integer
format: int32
example: 503
data:
type: string
example: ERROR
success:
type: boolean
example: true
status:
type: string
enum: [healthy, degraded, unhealthy]
example: unhealthy
version:
type: string
example: 3.0.0
uptime:
type: integer
format: int64
example: 86400
timestamp:
type: string
format: date-time
example: 2024-01-01T12:00:00Z
metrics:
type: object
required: [goroutines, go_version, cpu_count, go_max_procs]
properties:
goroutines:
type: integer
example: 42
go_version:
type: string
example: go1.21.5
cpu_count:
type: integer
example: 8
go_max_procs:
type: integer
example: 8
environment:
type: object
required: [containerized]
properties:
containerized:
type: boolean
example: false
hostname:
type: string
nullable: true
example: zuckzapgo-01
app_env:
type: string
nullable: true
example: production
app_region:
type: string
nullable: true
example: us-east-1
build:
type: object
nullable: true
properties:
commit:
type: string
example: a1b2c3d4
services:
type: object
nullable: true
additionalProperties:
type: object
properties:
status:
type: string
example: down
latency_ms:
type: number
format: float
example: 950.0
open_connections:
type: integer
example: 10
in_use:
type: integer
example: 4
idle:
type: integer
example: 6
driver:
type: string
example: postgres
error:
type: string
example: Database connection failed
example:
{
"code": 503,
"data": "ERROR",
"success": true,
"status": "unhealthy",
"version": "3.0.0",
"uptime": 86410,
"timestamp": "2024-01-01T12:05:00Z",
"metrics":
{
"goroutines": 55,
"go_version": "go1.21.5",
"cpu_count": 8,
"go_max_procs": 8,
},
"environment":
{
"containerized": false,
"hostname": "zuckzapgo-01",
"app_env": "production",
"app_region": "us-east-1",
},
"services":
{
"database":
{
"status": "down",
"latency_ms": 950.0,
"open_connections": 10,
"in_use": 4,
"idle": 6,
"driver": "postgres",
"error": "Database connection failed",
},
},
}
/webhook:
get:
tags:
- Webhook
summary: Shows webhook
description: |
Gets the configured webhook and subscribed events.
## Webhook
The following _webhook_ endpoints are used to get or set the webhook that will be called whenever a message or event is received. Available event types are:
**Messages and Communication:**
* Message - Incoming/outgoing messages
* UndecryptableMessage - Messages that couldn't be decrypted
* Receipt - Message delivery receipts
* MediaRetry - Media message retry events
* ReadReceipt - Message read receipts
**Groups and Contacts:**
* GroupInfo - Group information changes
* JoinedGroup - User joined/left group events
* Picture - Profile/group picture changes
* BlocklistChange - Blocklist modification events
* Blocklist - Complete blocklist updates
**Connection and Session:**
* Connected - Successfully connected to WhatsApp
* Disconnected - Disconnected from WhatsApp
* ConnectFailure - Connection failure events
* KeepAliveRestored - Connection keep-alive restored
* KeepAliveTimeout - Connection keep-alive timeout
* LoggedOut - User logged out
* ClientOutdated - Client version outdated
* TemporaryBan - Temporary account ban
* StreamError - WebSocket stream errors
* StreamReplaced - WebSocket stream replaced
* PairSuccess - Device pairing successful
* PairError - Device pairing failed
* QR - QR code generation/updates
* QRScannedWithoutMultidevice - QR scanned without multidevice
**Privacy and Settings:**
* PrivacySettings - Privacy settings changes
* PushNameSetting - Push name updates
* UserAbout - User about/status changes
**Synchronization and State:**
* AppState - Application state changes
* AppStateSyncComplete - App state sync completed
* HistorySync - Message history synchronization
* OfflineSyncCompleted - Offline sync completed
* OfflineSyncPreview - Offline sync preview
**Calls:**
* CallOffer - Incoming call offer
* CallAccept - Call accepted
* CallTerminate - Call terminated
* CallOfferNotice - Call offer notification
* CallRelayLatency - Call relay latency updates
**Presence and Activity:**
* Presence - User online/offline status
* ChatPresence - Chat typing/recording status
**Identity and Security:**
* IdentityChange - User identity changes
**Errors:**
* CATRefreshError - CAT token refresh errors
**Newsletter (WhatsApp Channels):**
* NewsletterJoin - Joined newsletter/channel
* NewsletterLeave - Left newsletter/channel
* NewsletterMuteChange - Newsletter mute status change
* NewsletterLiveUpdate - Newsletter live updates
**Facebook/Meta Bridge:**
* FBMessage - Facebook messages
**Special:**
* All - Subscribes to all event types above
security:
- ApiKeyAuth: []
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"subscribe": ["Message", "ReadReceipt"],
"webhook": "https://example.net/webhook",
},
"success": true,
}
post:
tags:
- Webhook
summary: Sets webhook
description: |
Sets the webhook that will be used to POST information when messages are received and configures the events to subscribe to.
## Webhook
The following _webhook_ endpoints are used to get or set the webhook that will be called whenever a message or event is received. Available event types are:
**Messages and Communication:**
* Message - Incoming/outgoing messages
* UndecryptableMessage - Messages that couldn't be decrypted
* Receipt - Message delivery receipts
* MediaRetry - Media message retry events
* ReadReceipt - Message read receipts
**Groups and Contacts:**
* GroupInfo - Group information changes
* JoinedGroup - User joined/left group events
* Picture - Profile/group picture changes
* BlocklistChange - Blocklist modification events
* Blocklist - Complete blocklist updates
**Connection and Session:**
* Connected - Successfully connected to WhatsApp
* Disconnected - Disconnected from WhatsApp
* ConnectFailure - Connection failure events
* KeepAliveRestored - Connection keep-alive restored
* KeepAliveTimeout - Connection keep-alive timeout
* LoggedOut - User logged out
* ClientOutdated - Client version outdated
* TemporaryBan - Temporary account ban
* StreamError - WebSocket stream errors
* StreamReplaced - WebSocket stream replaced
* PairSuccess - Device pairing successful
* PairError - Device pairing failed
* QR - QR code generation/updates
* QRScannedWithoutMultidevice - QR scanned without multidevice
**Privacy and Settings:**
* PrivacySettings - Privacy settings changes
* PushNameSetting - Push name updates
* UserAbout - User about/status changes
**Synchronization and State:**
* AppState - Application state changes
* AppStateSyncComplete - App state sync completed
* HistorySync - Message history synchronization
* OfflineSyncCompleted - Offline sync completed
* OfflineSyncPreview - Offline sync preview
**Calls:**
* CallOffer - Incoming call offer
* CallAccept - Call accepted
* CallTerminate - Call terminated
* CallOfferNotice - Call offer notification
* CallRelayLatency - Call relay latency updates
**Presence and Activity:**
* Presence - User online/offline status
* ChatPresence - Chat typing/recording status
**Identity and Security:**
* IdentityChange - User identity changes
**Errors:**
* CATRefreshError - CAT token refresh errors
**Newsletter (WhatsApp Channels):**
* NewsletterJoin - Joined newsletter/channel
* NewsletterLeave - Left newsletter/channel
* NewsletterMuteChange - Newsletter mute status change
* NewsletterLiveUpdate - Newsletter live updates
**Facebook/Meta Bridge:**
* FBMessage - Facebook messages
**Special:**
* All - Subscribes to all event types above
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/WebhookSet"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"WebhookURL": "https://example.net/webhook",
"Events": ["Message", "ReadReceipt"],
},
"success": true,
}
delete:
tags:
- Webhook
summary: Deletes webhook
description: Removes the configured webhook and clears events for the user
security:
- ApiKeyAuth: []
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{ "Details": "Webhook and events deleted successfully" },
"success": true,
}
put:
tags:
- Webhook
summary: Updates webhook
description: |
Updates the webhook URL, events, and activation status.
## Webhook
The following _webhook_ endpoints are used to get or set the webhook that will be called whenever a message or event is received. Available event types are:
**Messages and Communication:**
* Message - Incoming/outgoing messages
* UndecryptableMessage - Messages that couldn't be decrypted
* Receipt - Message delivery receipts
* MediaRetry - Media message retry events
* ReadReceipt - Message read receipts
**Groups and Contacts:**
* GroupInfo - Group information changes
* JoinedGroup - User joined/left group events
* Picture - Profile/group picture changes
* BlocklistChange - Blocklist modification events
* Blocklist - Complete blocklist updates
**Connection and Session:**
* Connected - Successfully connected to WhatsApp
* Disconnected - Disconnected from WhatsApp
* ConnectFailure - Connection failure events
* KeepAliveRestored - Connection keep-alive restored
* KeepAliveTimeout - Connection keep-alive timeout
* LoggedOut - User logged out
* ClientOutdated - Client version outdated
* TemporaryBan - Temporary account ban
* StreamError - WebSocket stream errors
* StreamReplaced - WebSocket stream replaced
* PairSuccess - Device pairing successful
* PairError - Device pairing failed
* QR - QR code generation/updates
* QRScannedWithoutMultidevice - QR scanned without multidevice
**Privacy and Settings:**
* PrivacySettings - Privacy settings changes
* PushNameSetting - Push name updates
* UserAbout - User about/status changes
**Synchronization and State:**
* AppState - Application state changes
* AppStateSyncComplete - App state sync completed
* HistorySync - Message history synchronization
* OfflineSyncCompleted - Offline sync completed
* OfflineSyncPreview - Offline sync preview
**Calls:**
* CallOffer - Incoming call offer
* CallAccept - Call accepted
* CallTerminate - Call terminated
* CallOfferNotice - Call offer notification
* CallRelayLatency - Call relay latency updates
**Presence and Activity:**
* Presence - User online/offline status
* ChatPresence - Chat typing/recording status
**Identity and Security:**
* IdentityChange - User identity changes
**Errors:**
* CATRefreshError - CAT token refresh errors
**Newsletter (WhatsApp Channels):**
* NewsletterJoin - Joined newsletter/channel
* NewsletterLeave - Left newsletter/channel
* NewsletterMuteChange - Newsletter mute status change
* NewsletterLiveUpdate - Newsletter live updates
**Facebook/Meta Bridge:**
* FBMessage - Facebook messages
**Special:**
* All - Subscribes to all event types above
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/WebhookUpdate"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Webhook": "https://example.net/webhook",
"Events": ["Message", "ReadReceipt"],
"active": true,
},
"success": true,
}
/session/connect:
post:
tags:
- Session
summary: connects to WhatsApp servers
description: "Initiates connection to WhatsApp servers.\n\nIf there is no previous session created, it will generate a QR code that can be retrieved via the [qr](#/Session/get_session_qr) API call.\n\nIf the optional Subscribe is supplied it will limit webhooks to the specified event types. Available events: Message, UndecryptableMessage, Receipt, MediaRetry, ReadReceipt, GroupInfo, JoinedGroup, Picture, BlocklistChange, Blocklist, Connected, Disconnected, ConnectFailure, KeepAliveRestored, KeepAliveTimeout, LoggedOut, ClientOutdated, TemporaryBan, StreamError, StreamReplaced, PairSuccess, PairError, QR, QRScannedWithoutMultidevice, PrivacySettings, PushNameSetting, UserAbout, AppState, AppStateSyncComplete, HistorySync, OfflineSyncCompleted, OfflineSyncPreview, CallOffer, CallAccept, CallTerminate, CallOfferNotice, CallRelayLatency, Presence, ChatPresence, IdentityChange, CATRefreshError, NewsletterJoin, NewsletterLeave, NewsletterMuteChange, NewsletterLiveUpdate, FBMessage, All.\n\nIf no Subscribe is supplied it will subscribe to All events.\n\nIf Immediate is set to false, the action will wait for 10 seconds to retrieve actual connection status from whatsapp, otherwise it will return immediatly.\n\nWhen setting Immediate to true you should check for actual connection status after a few seconds via the [status](#/Session/get_session_status) API call as your connection might fail if the session was closed from another device.\n\n**Connection Behavior:**\n- If you have a valid stored session (previously logged in), it will connect directly without requiring QR code scanning\n- If no valid session exists, a QR code will be generated that must be scanned with your phone\n- Use this endpoint after calling [disconnect](#/Session/post_session_disconnect) to reconnect without QR scanning"
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/Connect"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"details": "Connected!",
"events": "Message",
"jid": "5491155555555.0:53@s.whatsapp.net",
"webhook": "https://some.site/webhook?request=parameter",
},
"success": true,
}
/session/disconnect:
post:
tags:
- Session
summary: disconnects from WhatsApp servers
description: "**Soft Disconnect - WebSocket Only**\n\nCloses the WebSocket connection to WhatsApp servers while preserving your session credentials. This is a **non-destructive operation** that:\n\n- ✅ Maintains your login session and stored credentials\n- ✅ Allows reconnection using [connect](#/Session/post_session_connect) **without QR code scanning**\n- ✅ Preserves all chat history and settings\n- ✅ Keeps the session valid for future connections\n\n**Use Cases:**\n- Temporarily pause message receiving (maintenance, debugging)\n- Switch between different webhook configurations\n- Restart connection without losing authentication\n- Network troubleshooting\n\n**Important:** After disconnect, you can reconnect instantly with the connect endpoint. No QR code scanning required as your WhatsApp session remains active and valid.\n\n**Comparison with other endpoints:**\n- Use `disconnect` for temporary connection suspension\n- Use [logout](#/Session/post_session_logout) for complete session termination\n- Use [refresh](#/Session/post_session_refresh) for session cleanup without disconnection"
security:
- ApiKeyAuth: []
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data": { "Details": "Disconnected" },
"success": true,
}
/session/logout:
post:
tags:
- Session
summary: Logs out from WhatsApp
description: "**Complete Session Termination - Full Logout**\n\nPerforms a complete logout and terminates all connections to WhatsApp servers. This is a **destructive operation** that:\n\n- ❌ **Completely removes** your stored session and credentials\n- ❌ **Requires QR code scanning** for next connection\n- ❌ Closes all WebSocket connections permanently\n- ❌ Clears all local session data and authentication tokens\n- ❌ Invalidates the session on WhatsApp's servers\n\n**What happens after logout:**\n1. Your device is removed from WhatsApp's active device list\n2. All stored session credentials are permanently deleted\n3. Next [connect](#/Session/post_session_connect) call will require fresh QR code authentication\n4. You must scan the QR code with your phone to re-establish the session\n\n**Use Cases:**\n- Permanently removing the API connection from your WhatsApp account\n- Security purposes (revoke access completely)\n- Switching to a different WhatsApp account\n- Full reset of the API integration\n\n**Important:** This action cannot be undone. After logout, you must go through the complete setup process again, including QR code scanning.\n\n**Comparison with other endpoints:**\n- Use [disconnect](#/Session/post_session_disconnect) for temporary suspension (preserves session)\n- Use `logout` for permanent termination (requires new QR setup)\n- Use [refresh](#/Session/post_session_refresh) for session cleanup without logout"
security:
- ApiKeyAuth: []
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data": { "Details": "Logged out" },
"success": true,
}
/session/refresh:
post:
tags:
- Session
summary: Complete session refresh with full synchronization
description: |
**Complete Session Refresh with Full Synchronization**
Performs a complete session refresh including reconnection and optional full synchronization of all WhatsApp data. This is the most comprehensive refresh operation available.
**What this endpoint does:**
1. Disconnects and reconnects to WhatsApp servers
2. Synchronizes all 5 App State patch types (contacts, chats, settings)
3. Checks and uploads PreKeys if needed (encryption keys)
4. Refreshes Privacy Settings from server
5. Requests automatic recovery for any failed syncs
**Sync Options (all default to true):**
- `sync_app_state`: Sync all 5 app state patches (critical_block, critical_unblock_low, regular_low, regular_high, regular)
- `refresh_prekeys`: Check server prekey count and upload if low (<5 keys)
- `refresh_privacy`: Force refresh of privacy settings from server
- `auto_recovery`: If app state sync fails, automatically request recovery from primary device
**App State Patches Explained:**
- **critical_block**: User settings (push name, locale)
- **critical_unblock_low**: Contact list
- **regular_low**: Chat settings (pin, archive, unarchive behavior)
- **regular_high**: More chat settings (mute, starred messages)
- **regular**: Protocol info (key expiration)
**PreKeys:**
PreKeys are encryption keys used by the Signal Protocol. WhatsApp servers need a pool of these keys to establish encrypted sessions. This endpoint checks if the server has enough keys and uploads more if needed.
**Auto Recovery:**
If app state sync fails (corrupted data, version mismatch), the auto_recovery feature uses `BuildAppStateRecoveryRequest` to request an unencrypted snapshot from your primary device (phone).
**Typical Duration:** 7-10 seconds (3s reconnect + 2-5s app state + 1s prekeys + 1s privacy)
**Use Cases:**
- Complete session refresh after long disconnection
- Recover from sync issues or corrupted local state
- Ensure all data is up-to-date after configuration changes
- Periodic maintenance for production deployments
- Troubleshoot message delivery issues
security:
- ApiKeyAuth: []
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
sync_app_state:
type: boolean
description: Sync all 5 app state patch types (contacts, chats, settings). Default true.
default: true
example: true
refresh_prekeys:
type: boolean
description: Check server prekey count and upload new keys if below threshold. Default true.
default: true
example: true
refresh_privacy:
type: boolean
description: Force refresh of privacy settings from WhatsApp servers. Default true.
default: true
example: true
auto_recovery:
type: boolean
description: If app state sync fails, automatically request recovery from primary device. Default true.
default: true
example: true
example:
sync_app_state: true
refresh_prekeys: true
refresh_privacy: true
auto_recovery: true
responses:
200:
description: Session refreshed successfully with sync results
content:
application/json:
schema:
type: object
properties:
Details:
type: string
example: "Connection refresh completed"
refreshSuccess:
type: boolean
example: true
wasConnected:
type: boolean
example: true
wasLoggedIn:
type: boolean
example: true
newConnected:
type: boolean
example: true
newLoggedIn:
type: boolean
example: true
jid:
type: string
example: "5521999999999@s.whatsapp.net"
sync_options:
type: object
properties:
sync_app_state:
type: boolean
refresh_prekeys:
type: boolean
refresh_privacy:
type: boolean
auto_recovery:
type: boolean
sync:
type: object
properties:
app_state:
type: array
items:
type: object
properties:
name:
type: string
success:
type: boolean
error:
type: string
duration:
type: string
recovery_requested:
type: boolean
app_state_success:
type: boolean
prekeys:
type: object
properties:
checked:
type: boolean
server_count:
type: integer
upload_triggered:
type: boolean
error:
type: string
privacy_settings:
type: object
properties:
fetched:
type: boolean
error:
type: string
total_duration:
type: string
example:
Details: "Connection refresh completed"
refreshSuccess: true
wasConnected: true
wasLoggedIn: true
newConnected: true
newLoggedIn: true
jid: "5521999999999@s.whatsapp.net"
sync_options:
sync_app_state: true
refresh_prekeys: true
refresh_privacy: true
auto_recovery: true
sync:
app_state:
- name: "critical_block"
success: true
duration: "1.234s"
recovery_requested: false
- name: "critical_unblock_low"
success: true
duration: "0.856s"
recovery_requested: false
- name: "regular_low"
success: true
duration: "0.523s"
recovery_requested: false
- name: "regular_high"
success: true
duration: "0.412s"
recovery_requested: false
- name: "regular"
success: true
duration: "0.678s"
recovery_requested: false
app_state_success: true
prekeys:
checked: true
server_count: 47
upload_triggered: false
privacy_settings:
fetched: true
total_duration: "4.521s"
400:
description: Bad request - no JID found, QR scan required
content:
application/json:
schema:
example:
{
"code": 400,
"error": "no JID found, QR scan required for initial pairing",
"success": false,
}
500:
description: Connection refresh failed
content:
application/json:
schema:
example:
{
"code": 500,
"error": "Failed to refresh connection",
"refreshSuccess": false,
"wasConnected": true,
"wasLoggedIn": true,
"newConnected": false,
"newLoggedIn": false,
}
/session/status:
get:
tags:
- Session
summary: Gets connection and session status
description: Gets status from connection, including websocket connection and logged in status (session)
security:
- ApiKeyAuth: []
responses:
200:
description: Response
content:
application/json:
schema:
type: object
required:
- code
- data
- success
properties:
code:
type: integer
example: 200
data:
$ref: "#/definitions/SessionStatus"
success:
type: boolean
example: true
example:
{
"code": 200,
"success": true,
"data":
{
"id": "bec45bb93cbd24cbec32941ec3c93a12",
"name": "Some User",
"avatar_url": "https://example.com/avatar.jpg",
"connected": true,
"loggedIn": true,
"hasClient": true,
"connectionHealth": "connected",
"lastSuccessfulConnect": 1705312845,
"autoReconnectErrors": 0,
"enableAutoReconnect": true,
"expiration": 86400,
"token": "d030sl9aDL39sl3075zz",
"jid": "5491155551122:12@s.whatsapp.net",
"webhook": "https://some.domain/webhook",
"events": "All",
"proxy_url": "",
"qrcode": "",
"skip_media_download": false,
"skip_groups": false,
"skip_newsletters": false,
"skip_broadcasts": false,
"skip_own_messages": false,
"echo_api_messages": false,
"skip_calls": false,
"call_reject_message": "Sorry, I cannot take calls at the moment.",
"call_reject_type": "busy",
"globalTransportSkips":
{
"skipGlobalWebhook": false,
"skipGlobalRabbitMQ": false,
"skipGlobalSQS": false,
"skipGlobalRedis": false,
"skipGlobalWebSocket": false,
"skipGlobalS3": false,
},
"isFromAPI": false,
"proxy_config": { "enabled": false, "proxy_url": "" },
"s3_config": { "enabled": false },
"rabbitmq_config": { "enabled": false },
"timestamp": 1705312845,
},
}
/session/pairphone:
post:
tags:
- Session
summary: Gets pair by phone code
description: Gets the code to enter into whatsapp client when pairing by phone number instead of QR code
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/Pairphone"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data": { "LinkingCode": "9H3J-H3J8" },
"success": true,
}
/session/qr:
get:
tags:
- Session
summary: Gets QR code for scanning
description: Gets QR code if the user is connected but not logged in. If the user is already logged in, QRCode will be empty.
security:
- ApiKeyAuth: []
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"QRCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlBMVEX///8AAABVwtN+AAAEw0lEQVR42uyZPa7zqhaGX0ThLmsCkZlGCktMKaU76FxmSkgUmQZWJkA6CuT3avlLvrNvvRMX9x6KXWQ/UhCsn2cR/Lv+v5YhudQ6njEs1bBjqGYDwlJJpoOAArtUbK4Pi5jN3qPAlCkstcAeBazMUaoj78RpxGW4yWYzWVfmzwFLlLX4O+VkkucN5tFDOxiIAvfoA/X4uVQ4sgUcCBTYCG7AEGGKvbdrBabQ8OOyvg3ovm4ynqfLXJ9rvi+303ie5vm/gvZXgK6BLC7fo5hiG4KwW7b6I/2+DJi1+ybVFQyx6o6bbKPVDCyjTwcBZB9uevBtAEafhiosCFH/4kNA8i1gg02B3KxezGbzEjUCDgIwYppR3SNdgtY3H0M1j8xFzCscvg/8uQvZAB9piidv1RXfZhbHdAwAlzsCNCaJDdMF4WQeeSGACZ8BMNl4FZYJA7j2YalPPhhngetHAaZPcyBg2wyYdAk0fKQ5yPja5PcBzTZW4uxJ2bTGwmxnu/BH4vwSgEsYItcCH+VZJt/AYhmHatbXdX8d2JvaTVzxCVW2aVhqheXSqvnR9b4L6AoUx3zX+jZd5rDB5jbLuv0txd8GRs+liuv+TsKloQWujxxRYf5s8gOA7fMVK9PQuDtMNCx2ibIdCMCy1s0yQU6Od9bqim1BuzoOAgzTHOiKv0d5Mt+XClN8DBxN/wxg2G2DbDYNJExCqE+Ne8poXoLxdUA/w5VrnxBQ9fjlqaJMwWgPAzLjtfKRW4A21ojnStX0dX2d5PeB0fawu2pChcuM4bk+tLmbMn0GMJslb5ptDXySbb5W1+0SyVcJOgRIQxSc7X0RUSvGs2DSeaz4gwCMNi/7XNACZc0KbPBtruv2KQA+DVFladBvt4xywhmh1Xd2fx8wzGTUltqCWrHWgqL7Jg8E0hSiFJfbUJ/Fpx3L1OHsVR8+APgoZMclUKvcft2+zTBrwjHArosim4ZcfW4Y4lVWnYXg2A8C9C5aEFXDoEJzmXFyfZoH/p0Wvw7oXoZbNQ823ase1wk2DQ3u7XK/BkzOqovwpM68Ko+jUyPFu6F8H4DvqsAuaUMZJ6+azjTPdS32KMBkLnpQ3VPnbsZgiktALW91/wDQEV5V7gT4JT6L62GRzeV0EDDC7rVFax2ZW6Aa6V5h/FEAgBlSbLrMVScU1s09+jxwG/9q87cB/Yxw3acBsk2Yw+nPf9Y1p88ARlNPtvPkF3LlPQYp8MtSx/FtpF8H4DNrZd8fOtTOxJSzXdo/c/fXAbN2DLeKs1dxHeEZZVWaju/3h18CcDk3qePZpllglDZ89MCq8nIQoDPAVaPi3iAFFwS1xjjr+HcYwD+hri216vBZzQbbZsE44RhAp+sQxfTpApGCoV1NOfsl4pX+nwC65a1uLnkK9TSuVTOhaQ4cBOzvtDcZXU5Bdl28SrF9HqrZJhwD7O/VsZpi7xSz7pXW6ahQ1/dB/RrYf2QhLBmr1lNINVRZfw9BBwArc4SszGlWWd2fxB9cFvJQYKnUUWAgV22y5v1e/ffHpiOAqMLCiOpymwNGtxvk9s8mfwcU2CiydqvJbdKuSX0K8a/KHQDsMQkyeVbtISFif8mRcfwRtF8F/l3/O+s/AQAA///lM0dZSaTeTQAAAABJRU5ErkJggg==",
},
"success": true,
}
/session/proxy:
post:
tags:
- Session
summary: Set Proxy Configuration
description: |
Sets or disables the proxy configuration for the user.
Provide a JSON payload with "proxy_url" (e.g. "http://host:port" or "socks5://user:pass@host:port") and "enable" (boolean).
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
proxy_url:
type: string
description: Proxy URL in format "http://host:port" or "socks5://user:pass@host:port"
enable:
type: boolean
description: Whether to enable or disable the proxy.
required:
- proxy_url
- enable
responses:
"200":
description: Proxy configured successfully
content:
application/json:
schema:
type: object
properties:
Details:
type: string
example: Proxy configured successfully
ProxyURL:
type: string
example: socks5://user:pass@host:port
"400":
description: Bad Request
"500":
description: Internal Server Error
/session/s3/config:
post:
tags:
- Session S3
summary: Configure S3 Storage
description: |
Configures S3 storage settings for the user to store media files.
Supports AWS S3, MinIO, Backblaze B2, and other S3-compatible services.
When enabled, media files will be uploaded to S3 and can be accessed via public URLs.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/S3Config"
responses:
200:
description: S3 configuration saved successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "S3 configuration saved successfully",
"Enabled": true,
},
"success": true,
}
400:
description: Bad Request
500:
description: Internal Server Error
get:
tags:
- Session S3
summary: Get S3 Configuration
description: Retrieves the current S3 storage configuration for the user.
security:
- ApiKeyAuth: []
responses:
200:
description: S3 configuration retrieved successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"enabled": true,
"endpoint": "https://s3.amazonaws.com",
"region": "us-east-1",
"bucket": "my-bucket",
"access_key": "***",
"path_style": false,
"public_url": "",
"media_delivery": "both",
"retention_days": 30,
},
"success": true,
}
500:
description: Internal Server Error
delete:
tags:
- Session S3
summary: Delete S3 Configuration
description: Removes the S3 storage configuration for the user and reverts to default base64 media delivery.
security:
- ApiKeyAuth: []
responses:
200:
description: S3 configuration deleted successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{ "Details": "S3 configuration deleted successfully" },
"success": true,
}
500:
description: Internal Server Error
/session/s3/test:
post:
tags:
- Session S3
summary: Test S3 Connection
description: Tests the S3 connection using the current configuration to ensure it's working properly.
security:
- ApiKeyAuth: []
responses:
200:
description: S3 connection test successful
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "S3 connection test successful",
"Bucket": "my-bucket",
"Region": "us-east-1",
},
"success": true,
}
400:
description: S3 is not enabled or configuration error
500:
description: S3 connection test failed
/session/rabbitmq/config:
post:
tags:
- Session RabbitMQ
summary: Configure RabbitMQ - Advanced with Dynamic Queues
description: |
Configures RabbitMQ settings for the user to publish WhatsApp events with **dynamic queues per event type** and **auto-recovery system**.
**🚀 FILAS DINÂMICAS POR EVENTO:**
- Use placeholders `{user_id}` and `{event_type}` in queue/routing_key patterns
- System automatically creates event-specific queues as events arrive
- Example: `user_abc123_event_Message`, `user_abc123_event_Receipt`, etc.
**⚡ AUTO-RECOVERY SYSTEM:**
- Health check every 30 seconds with automatic reconnection
- Circuit breaker prevents overload during connectivity issues
- Connection pool with retry logic and exponential backoff
- Queue cache prevents unnecessary recreations
Supports AMQP protocol with exchanges, queues, and routing keys.
When enabled, WhatsApp events will be published to the configured RabbitMQ server with enterprise-grade reliability.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/RabbitMQConfig"
responses:
200:
description: RabbitMQ configuration saved successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "RabbitMQ configuration saved successfully",
"Enabled": true,
},
"success": true,
}
400:
description: Bad Request
500:
description: Internal Server Error
get:
tags:
- Session RabbitMQ
summary: Get RabbitMQ Configuration with Queue Statistics
description: Retrieves the current RabbitMQ configuration for the user including dynamic queue statistics and created queues list.
security:
- ApiKeyAuth: []
responses:
200:
description: RabbitMQ configuration retrieved successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"config":
{
"enabled": true,
"url": "amqp://user:***@localhost:5672/",
"exchange": "whatsapp.events",
"exchange_type": "topic",
"queue": "whatsapp.user.{user_id}",
"queue_type": "classic",
"routing_key": "whatsapp.{event_type}",
"events": "Message,ReadReceipt,All",
"durable": true,
"auto_delete": false,
"exclusive": false,
"no_wait": false,
"delivery_mode": 2,
"dead_letter_exchange": "dlx.whatsapp",
"dead_letter_routing_key": "dlq.events",
"message_ttl": 86400000,
"max_length": 100000,
"max_length_bytes": 104857600,
"queue_arguments": '{"x-overflow":"reject-publish"}',
"exchange_arguments": "{}",
},
"stats":
{
"active_queues":
[
"whatsapp.user.abc123_Message",
"whatsapp.user.abc123_Receipt",
],
"total_published": 15420,
"last_publish": "2024-01-15T10:30:00Z",
},
},
"success": true,
}
500:
description: Internal Server Error
delete:
tags:
- Session RabbitMQ
summary: Delete RabbitMQ Configuration
description: Removes the RabbitMQ configuration for the user and disables RabbitMQ event publishing.
security:
- ApiKeyAuth: []
responses:
200:
description: RabbitMQ configuration deleted successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "RabbitMQ configuration deleted successfully",
},
"success": true,
}
500:
description: Internal Server Error
/session/rabbitmq/test:
post:
tags:
- Session RabbitMQ
summary: Test RabbitMQ Connection
description: Tests the RabbitMQ connection using the current configuration to ensure it's working properly.
security:
- ApiKeyAuth: []
responses:
200:
description: RabbitMQ connection test successful
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "RabbitMQ connection test successful",
"Host": "localhost",
"Port": 5672,
"Exchange": "whatsapp.events",
},
"success": true,
}
400:
description: RabbitMQ is not enabled or configuration error
500:
description: RabbitMQ connection test failed
/session/skipmedia/config:
post:
tags:
- Session Skips
summary: Configure Skip Media Download
description: |
Configure whether to skip downloading media files (images, videos, audio, documents, stickers) during WhatsApp events.
When enabled, events will only contain WhatsApp metadata without base64 content or S3 uploads,
dramatically improving performance for high-volume scenarios.
**Performance Benefits:**
- ⚡ Faster event processing (up to 90% improvement)
- 📊 Reduced bandwidth usage
- 💾 Lower storage requirements
- 🔄 Better performance for high-volume scenarios
- 📱 Original WhatsApp metadata preserved
**Configuration Hierarchy:**
1. Command Line Flag (-skipmedia) - Highest priority
2. Environment Variable (GLOBAL_SKIP_MEDIA_DOWNLOAD) - Global setting
3. User Configuration (skip_media_download) - Individual setting
4. Default Behavior - Normal media processing
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/SkipMediaConfig"
responses:
200:
description: Skip media download configuration updated successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Skip media download configuration updated successfully",
"SkipMediaDownload": true,
},
"success": true,
}
400:
description: Invalid request payload
500:
description: Internal Server Error
get:
tags:
- Session Skips
summary: Get Skip Media Download Configuration
description: |
Retrieves the current skip media download configuration for the authenticated user,
including both user-specific and global settings.
**Response includes:**
- UserSkipMediaDownload: Individual user setting
- GlobalSkipMediaDownload: Server-wide setting (read-only)
- Configuration hierarchy status
security:
- ApiKeyAuth: []
responses:
200:
description: Skip media download configuration retrieved successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"UserSkipMediaDownload": false,
"GlobalSkipMediaDownload": false,
"Details": "Skip media download configuration retrieved successfully",
},
"success": true,
}
500:
description: Internal Server Error
/session/skipgroups/config:
post:
tags:
- Session Skips
summary: Configure Skip Groups
description: |
Configure whether to skip processing messages from WhatsApp groups.
When enabled, the system will ignore all messages from group chats, processing only direct messages.
This can improve performance and reduce processing overhead for applications that don't need group functionality.
Priority order:
1. User Configuration (skip_groups) - Individual setting
2. Global setting (if implemented)
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/SkipGroupsConfig"
responses:
200:
description: Skip groups configuration updated successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Skip groups configuration updated successfully",
"SkipGroups": true,
},
"success": true,
}
500:
description: Internal Server Error
get:
tags:
- Session Skips
summary: Get Skip Groups Configuration
description: |
Retrieves the current skip groups configuration for the authenticated user.
Returns:
- UserSkipGroups: Individual user setting
security:
- ApiKeyAuth: []
responses:
200:
description: Skip groups configuration retrieved successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"UserSkipGroups": false,
"Details": "Skip groups configuration retrieved successfully",
},
"success": true,
}
500:
description: Internal Server Error
/session/skipnewsletters/config:
post:
tags:
- Session Skips
summary: Configure Skip Newsletters
description: |
Configure whether to skip processing messages from WhatsApp newsletters.
When enabled, the system will ignore all messages from newsletter channels, processing only direct messages and groups.
This can improve performance and reduce processing overhead for applications that don't need newsletter functionality.
Priority order:
1. User Configuration (skip_newsletters) - Individual setting
2. Global setting (if implemented)
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/SkipNewslettersConfig"
responses:
200:
description: Skip newsletters configuration updated successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Skip newsletters configuration updated successfully",
"SkipNewsletters": true,
},
"success": true,
}
500:
description: Internal Server Error
get:
tags:
- Session Skips
summary: Get Skip Newsletters Configuration
description: |
Retrieves the current skip newsletters configuration for the authenticated user.
Returns:
- SkipNewsletters: Individual user setting
security:
- ApiKeyAuth: []
responses:
200:
description: Skip newsletters configuration retrieved successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"SkipNewsletters": false,
"Details": "Skip newsletters configuration retrieved successfully",
},
"success": true,
}
500:
description: Internal Server Error
/session/skipbroadcasts/config:
post:
tags:
- Session Skips
summary: Configure Skip Broadcasts
description: |
Configure whether to skip processing messages from WhatsApp broadcasts and status updates.
When enabled, the system will ignore all messages from broadcast lists and status updates, processing only direct messages, groups, and newsletters.
This can improve performance and reduce processing overhead for applications that don't need broadcast functionality.
Priority order:
1. User Configuration (skip_broadcasts) - Individual setting
2. Global setting (if implemented)
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/SkipBroadcastsConfig"
responses:
200:
description: Skip broadcasts configuration updated successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Skip broadcasts configuration updated successfully",
"SkipBroadcasts": true,
},
"success": true,
}
500:
description: Internal Server Error
get:
tags:
- Session Skips
summary: Get Skip Broadcasts Configuration
description: |
Retrieves the current skip broadcasts configuration for the authenticated user.
Returns:
- SkipBroadcasts: Individual user setting
security:
- ApiKeyAuth: []
responses:
200:
description: Skip broadcasts configuration retrieved successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"SkipBroadcasts": false,
"Details": "Skip broadcasts configuration retrieved successfully",
},
"success": true,
}
500:
description: Internal Server Error
/session/skipownmessages/config:
post:
tags:
- Session Skips
summary: Configure Skip Own Messages
description: |
Configure whether to skip processing your own sent messages (IsFromMe: true).
When enabled, the system will ignore all messages that were sent by you, processing only messages received from others.
This can improve performance and reduce processing overhead for applications that don't need to track outgoing messages.
Priority order:
1. User Configuration (skip_own_messages) - Individual setting
2. Global setting (if implemented)
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/SkipOwnMessagesConfig"
responses:
200:
description: Skip own messages configuration updated successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Skip own messages configuration updated successfully",
"SkipOwnMessages": true,
},
"success": true,
}
500:
description: Internal Server Error
get:
tags:
- Session Skips
summary: Get Skip Own Messages Configuration
description: |
Retrieves the current skip own messages configuration for the authenticated user.
Returns:
- SkipOwnMessages: Individual user setting
security:
- ApiKeyAuth: []
responses:
200:
description: Skip own messages configuration retrieved successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"SkipOwnMessages": false,
"Details": "Skip own messages configuration retrieved successfully",
},
"success": true,
}
500:
description: Internal Server Error
/session/skipcalls/config:
post:
tags:
- Session Skips
summary: Configure Skip Calls
description: |
Configure automatic call rejection settings for the session.
When enabled, all incoming calls will be automatically rejected and an optional custom message will be sent to the caller.
Features:
- Automatic call rejection
- Customizable rejection message
- Configurable rejection type (busy, declined, unavailable)
- Zero-query cache optimization
Priority order:
1. User Configuration (skip_calls) - Individual setting
2. Global setting (if implemented)
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/SkipCallsConfig"
responses:
200:
description: Skip calls configuration updated successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Skip calls configuration updated successfully",
"SkipCalls": true,
"RejectMessage": "Sorry, I cannot take calls at the moment. Please send a message.",
"RejectType": "busy",
},
"success": true,
}
400:
description: Bad Request - Invalid rejection type
content:
application/json:
schema:
example:
{
"code": 400,
"error": "invalid reject_type, must be: busy, declined, or unavailable",
"success": false,
}
500:
description: Internal Server Error
get:
tags:
- Session Skips
summary: Get Skip Calls Configuration
description: |
Retrieves the current skip calls configuration for the authenticated user.
Returns:
- SkipCalls: Individual user setting
- RejectMessage: Custom message sent to callers
- RejectType: Type of call rejection used
security:
- ApiKeyAuth: []
responses:
200:
description: Skip calls configuration retrieved successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"SkipCalls": false,
"RejectMessage": "Sorry, I cannot take calls at the moment.",
"RejectType": "busy",
"Details": "Skip calls configuration retrieved successfully",
},
"success": true,
}
500:
description: Internal Server Error
/session/globaltransports/config:
post:
tags:
- Session Global Transports
summary: Configure global transport skip flags
operationId: configureGlobalTransportSkips
description: |
Configure per-transport skip flags that the global dispatcher consults before enriching and fan-out events. Use these flags when you need to disable the global webhook, RabbitMQ, SQS, Redis, WebSocket, or shared S3 enrichment for a specific tenant without affecting per-user transports.
Behavior:
- Updates only the transports included in the payload (partial updates supported)
- Triggers an immediate cache refresh so dispatcher decisions reflect the new state instantly
- Does not affect per-user transports (local webhooks/rabbitmq); only the shared/global dispatcher pipeline
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/GlobalTransportSkipsRequest"
responses:
200:
description: Global transport skip flags updated successfully
content:
application/json:
schema:
$ref: "#/definitions/GlobalTransportSkipsResponse"
example:
{
"code": 200,
"data":
{
"skipGlobalWebhook": false,
"skipGlobalRabbitMQ": true,
"skipGlobalSQS": false,
"skipGlobalRedis": false,
"skipGlobalWebSocket": false,
"skipGlobalS3": true,
"details": "Global transport skip configuration updated successfully",
},
"success": true,
}
400:
description: Bad Request - No valid fields provided
content:
application/json:
schema:
example:
{
"code": 400,
"error": "no fields provided",
"success": false,
}
401:
description: Unauthorized - user token required
content:
application/json:
schema:
example:
{ "code": 401, "error": "unauthorized", "success": false }
500:
description: Internal Server Error - database or cache failure
content:
application/json:
schema:
example:
{
"code": 500,
"error": "failed to update transport configuration",
"success": false,
}
get:
tags:
- Session Global Transports
summary: Get global transport skip flags
operationId: getGlobalTransportSkips
description: |
Retrieve the current snapshot of global transport skip flags for the authenticated session. The response mirrors what the global dispatcher caches, so you can inspect which transports (webhook, RabbitMQ, SQS, Redis, WebSocket, S3 enrichment) are disabled for the tenant.
security:
- ApiKeyAuth: []
responses:
200:
description: Global transport skip flags retrieved successfully
content:
application/json:
schema:
$ref: "#/definitions/GlobalTransportSkipsResponse"
example:
{
"code": 200,
"data":
{
"skipGlobalWebhook": false,
"skipGlobalRabbitMQ": false,
"skipGlobalSQS": false,
"skipGlobalRedis": false,
"skipGlobalWebSocket": false,
"skipGlobalS3": false,
"details": "Global transport skip configuration retrieved successfully",
},
"success": true,
}
401:
description: Unauthorized - user token required
content:
application/json:
schema:
example:
{ "code": 401, "error": "unauthorized", "success": false }
500:
description: Internal Server Error - cache or database failure
content:
application/json:
schema:
example:
{
"code": 500,
"error": "failed to load user configuration",
"success": false,
}
/session/presence/config:
post:
tags:
- Session Presence
summary: Configure Auto Presence Unavailable
operationId: configureAutoPresenceUnavailable
description: |
Enable or disable automatic presence unavailable after connection.
When enabled, the system sends PresenceUnavailable 3 seconds after the protocol-required PresenceAvailable,
preserving push notifications on the phone while keeping the API session active.
Behavior:
- Default: false (standard behavior - stays as Available after connection)
- When enabled: Available → 3s delay → Unavailable (phone keeps receiving push notifications)
- The PresenceAvailable is still sent first (required for WhatsApp protocol handshake)
- Manual presence control via POST /user/presence is not affected
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- enabled
properties:
enabled:
type: boolean
description: Whether to automatically send PresenceUnavailable after connection
example:
enabled: true
responses:
200:
description: Auto presence unavailable configuration updated successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Auto presence unavailable configuration updated successfully",
"AutoPresenceUnavailable": true,
},
"success": true,
}
400:
description: Bad Request - Invalid payload
401:
description: Unauthorized - user token required
500:
description: Internal Server Error
get:
tags:
- Session Presence
summary: Get Auto Presence Unavailable Configuration
operationId: getAutoPresenceUnavailableConfig
description: |
Retrieves the current auto presence unavailable configuration for the authenticated user.
security:
- ApiKeyAuth: []
responses:
200:
description: Auto presence unavailable configuration retrieved successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"AutoPresenceUnavailable": false,
"Details": "Auto presence unavailable configuration retrieved successfully",
},
"success": true,
}
401:
description: Unauthorized - user token required
500:
description: Internal Server Error
/user/info:
post:
tags:
- User
summary: Get user information
description: Gets detailed information about WhatsApp users, including status, profile picture, verified names, and device information
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
Phone:
oneOf:
- type: string
description: Single phone number
example: "5521971532700"
- type: array
items:
type: string
description: Array of phone numbers
example: ["5521971532700", "5521979232690"]
required:
- Phone
additionalProperties: false
examples:
responses:
"200":
description: User information retrieved successfully
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
success:
type: boolean
example: true
data:
type: object
properties:
users:
type: object
description: Object containing user information indexed by WhatsApp JID
additionalProperties:
type: object
properties:
jid:
type: string
description: WhatsApp JID
example: "5521971532700@s.whatsapp.net"
status:
type: string
description: User status message
example: "Hey there! I am using WhatsApp."
picture_id:
type: string
description: Profile picture ID
example: "1729003008"
verified_name:
type: string
description: Verified business name (if available)
example: "Business Name"
business_name:
type: string
description: Business name (if different from verified name)
example: "My Business"
lid:
type: string
description: "Linked ID (LID) - Privacy feature JID used in groups when user hasn't shared phone number publicly. Only present for group members with privacy protection enabled."
example: "1234567890abcd@lid"
is_business_account:
type: boolean
description: Whether this is a business account
example: false
device_count:
type: integer
description: Total number of connected devices
example: 4
first_device:
type: string
description: JID of the primary device
example: "5521971532700@s.whatsapp.net"
devices:
type: array
description: Detailed information about all connected devices
items:
type: object
properties:
user:
type: string
description: User number
example: "5521971532700"
agent:
type: string
description: Device agent ID
example: "0"
device:
type: string
description: Device platform
example: "SAFARI"
enum:
[
"UNKNOWN",
"CHROME",
"FIREFOX",
"IE",
"OPERA",
"SAFARI",
"EDGE",
"DESKTOP",
"IPAD",
"ANDROID_TABLET",
"OHANA",
"ALOHA",
"CATALINA",
"TCL_TV",
]
server:
type: string
description: WhatsApp server
example: "s.whatsapp.net"
ad:
type: string
description: Full device address
example: "5521971532700.0:5@s.whatsapp.net"
jid:
type: string
description: Device JID
example: "5521971532700:59@s.whatsapp.net"
examples:
success_response:
summary: Successful response with multiple users
value:
code: 200
success: true
data:
users:
"5521971532700@s.whatsapp.net":
jid: "5521971532700@s.whatsapp.net"
status: ""
picture_id: "1729003008"
is_business_account: false
device_count: 4
first_device: "5521971532700@s.whatsapp.net"
devices:
- user: "5521971532700"
agent: "0"
device: "UNKNOWN"
server: "s.whatsapp.net"
ad: "5521971532700.0:0@s.whatsapp.net"
jid: "5521971532700@s.whatsapp.net"
- user: "5521971532700"
agent: "0"
device: "SAFARI"
server: "s.whatsapp.net"
ad: "5521971532700.0:5@s.whatsapp.net"
jid: "5521971532700:5@s.whatsapp.net"
- user: "5521971532700"
agent: "0"
device: "UNKNOWN"
server: "s.whatsapp.net"
ad: "5521971532700.0:66@s.whatsapp.net"
jid: "5521971532700:66@s.whatsapp.net"
- user: "5521971532700"
agent: "0"
device: "UNKNOWN"
server: "s.whatsapp.net"
ad: "5521971532700.0:67@s.whatsapp.net"
jid: "5521971532700:67@s.whatsapp.net"
"5521979232690@s.whatsapp.net":
jid: "5521979232690@s.whatsapp.net"
status: ""
picture_id: "1728656243"
is_business_account: false
device_count: 3
first_device: "5521979232690@s.whatsapp.net"
devices:
- user: "5521979232690"
agent: "0"
device: "UNKNOWN"
server: "s.whatsapp.net"
ad: "5521979232690.0:0@s.whatsapp.net"
jid: "5521979232690@s.whatsapp.net"
- user: "5521979232690"
agent: "0"
device: "SAFARI"
server: "s.whatsapp.net"
ad: "5521979232690.0:5@s.whatsapp.net"
jid: "5521979232690:5@s.whatsapp.net"
- user: "5521979232690"
agent: "0"
device: "UNKNOWN"
server: "s.whatsapp.net"
ad: "5521979232690.0:99@s.whatsapp.net"
jid: "5521979232690:99@s.whatsapp.net"
"400":
description: Bad request - invalid payload
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 400
success:
type: boolean
example: false
error:
type: string
example: "missing phone numbers in payload. Use 'Phone' or 'phone' field"
"500":
description: Internal server error
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 500
success:
type: boolean
example: false
error:
type: string
example: "no session"
/user/privacy/settings:
get:
tags:
- User
summary: Get user privacy settings
description: |
Retrieves the current privacy settings for the authenticated user including:
- Group add permissions
- Last seen visibility
- Status visibility
- Profile photo visibility
- Read receipts setting
- Online status visibility
- Call add permissions
All settings return values like: "all", "contacts", "contact_blacklist", "none", "match_last_seen", "known"
security:
- ApiKeyAuth: []
responses:
200:
description: Privacy settings retrieved successfully
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
data:
type: object
properties:
group_add:
type: string
description: "Who can add you to groups"
example: "contacts"
last_seen:
type: string
description: "Who can see your last seen"
example: "contacts"
status:
type: string
description: "Who can see your status"
example: "contacts"
profile:
type: string
description: "Who can see your profile photo"
example: "all"
read_receipts:
type: string
description: "Read receipts setting"
example: "all"
online:
type: string
description: "Who can see when you're online"
example: "match_last_seen"
call_add:
type: string
description: "Who can call you"
example: "all"
success:
type: boolean
example: true
example:
code: 200
data:
group_add: "contacts"
last_seen: "contacts"
status: "contacts"
profile: "all"
read_receipts: "all"
online: "match_last_seen"
call_add: "all"
success: true
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "no session" }
/user/pushname:
post:
tags:
- User
summary: Change user push name (display name)
description: |
Changes the push name (display name) for the authenticated user.
This name appears in chats and contact lists for other WhatsApp users.
**Important Notes:**
- Push name cannot be empty
- Changes are synchronized across all devices
- May take a few minutes to propagate to all contacts
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/ChangePushNameRequest"
responses:
200:
description: Push name updated successfully
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
data:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "Push name updated successfully"
push_name:
type: string
example: "John Doe"
success:
type: boolean
example: true
example:
code: 200
data:
success: true
message: "Push name updated successfully"
push_name: "John Doe"
success: true
400:
description: Bad request - push name cannot be empty
content:
application/json:
schema:
example: { "error": "push name cannot be empty" }
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "no session" }
/user/contact/info:
post:
tags:
- User
summary: Get comprehensive contact information
description: |
Retrieve comprehensive information about a WhatsApp contact by combining data from multiple sources.
Accepts a phone number (international format without +), a JID (e.g., 5511999999999@s.whatsapp.net),
or a LID (e.g., 123456@lid).
**Data Sources Combined:**
- **IsOnWhatsApp**: Registration status and verified name
- **GetUserInfo**: About/status, picture ID, devices, LID, verified name
- **GetProfilePictureInfo**: Avatar URL and direct path
- **GetBusinessProfile**: Email, address, categories, business hours
- **Store.Contacts**: Cached names (push name, business name, full name)
- **Store.LIDs**: LID ↔ phone number mapping
**Input Formats:**
- Phone number: `5511999999999` (international format without +)
- JID: `5511999999999@s.whatsapp.net`
- LID: `123456@lid` (will be resolved to phone number first)
**Important Notes:**
- If a LID is provided, it is resolved to a phone number JID before fetching data
- If the number is not registered on WhatsApp, only basic info is returned with null fields
- Business profile data is only available for WhatsApp Business accounts
- Avatar URL has a temporary expiration and should be consumed promptly
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- phone
properties:
phone:
type: string
description: "Phone number (international format without +), JID (e.g., 5511999999999@s.whatsapp.net), or LID (e.g., 123456@lid)"
example: "5511999999999"
examples:
phone_number:
summary: Using phone number
value:
phone: "5511999999999"
jid_format:
summary: Using JID
value:
phone: "5511999999999@s.whatsapp.net"
lid_format:
summary: Using LID
value:
phone: "123456@lid"
responses:
200:
description: Contact information retrieved successfully
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
data:
type: object
properties:
phone:
type: string
description: Phone number extracted from JID
example: "5511999999999"
jid:
type: string
description: Canonical WhatsApp JID
example: "5511999999999@s.whatsapp.net"
input_type:
type: string
description: "Type of input provided: phone, jid, or lid"
enum:
- phone
- jid
- lid
example: "phone"
is_on_whatsapp:
type: boolean
description: Whether the number is registered on WhatsApp
example: true
verified_name:
type: string
nullable: true
description: Verified business name (if available)
example: "My Business"
lid:
type: string
nullable: true
description: Linked ID for the contact
example: "123456:78@lid"
devices:
type: array
nullable: true
description: List of connected devices
items:
type: object
properties:
user:
type: string
example: "5511999999999"
agent:
type: string
example: "0"
device:
type: string
example: "iPhone"
server:
type: string
example: "s.whatsapp.net"
ad:
type: string
example: "5511999999999.0:0@s.whatsapp.net"
jid:
type: string
example: "5511999999999.0:0@s.whatsapp.net"
user_info:
type: object
nullable: true
description: User profile information
properties:
status:
type: string
description: About/status text
example: "Hey there! I am using WhatsApp"
picture_id:
type: string
example: "1234567890"
verified_name:
type: string
nullable: true
example: "My Business"
is_business_account:
type: boolean
example: false
device_count:
type: integer
example: 2
avatar:
type: object
nullable: true
description: Profile picture information
properties:
url:
type: string
description: Temporary URL for the profile picture
example: "https://pps.whatsapp.net/v/t62.123-24/example.jpg"
id:
type: string
example: "1234567890"
type:
type: string
example: "image"
direct_path:
type: string
example: "/v/t62.123-24/example.jpg"
contact_names:
type: object
nullable: true
description: Locally cached contact names
properties:
first_name:
type: string
example: "João"
full_name:
type: string
example: "João Silva"
push_name:
type: string
example: "João"
business_name:
type: string
example: ""
business_profile:
type: object
nullable: true
description: Business profile data (only for business accounts)
properties:
address:
type: string
example: "Rua Example, 123"
email:
type: string
example: "contact@business.com"
business_hours_timezone:
type: string
example: "America/Sao_Paulo"
categories:
type: array
items:
type: object
properties:
id:
type: string
example: "123"
name:
type: string
example: "Shopping & Retail"
profile_options:
type: object
description: Additional business profile options
business_hours:
type: array
items:
type: object
properties:
day_of_week:
type: string
example: "mon"
mode:
type: string
example: "open_with_hours"
open_time:
type: string
example: "08:00"
close_time:
type: string
example: "18:00"
success:
type: boolean
example: true
example:
code: 200
data:
phone: "5511999999999"
jid: "5511999999999@s.whatsapp.net"
input_type: "phone"
is_on_whatsapp: true
verified_name: null
lid: "123456:78@lid"
devices:
- user: "5511999999999"
agent: "0"
device: "iPhone"
server: "s.whatsapp.net"
ad: "5511999999999.0:0@s.whatsapp.net"
jid: "5511999999999.0:0@s.whatsapp.net"
user_info:
status: "Hey there! I am using WhatsApp"
picture_id: "1234567890"
verified_name: null
is_business_account: false
device_count: 1
avatar:
url: "https://pps.whatsapp.net/v/t62.123-24/example.jpg"
id: "1234567890"
type: "image"
direct_path: "/v/t62.123-24/example.jpg"
contact_names:
first_name: "João"
full_name: "João Silva"
push_name: "João"
business_name: ""
business_profile: null
success: true
400:
description: Bad request - missing or invalid parameters
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
missing_phone:
value:
error: "missing phone in payload"
invalid_input:
value:
error: "invalid phone number, JID, or LID"
bad_payload:
value:
error: "could not decode payload"
404:
description: LID could not be resolved to a phone number
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "could not resolve LID to phone number. The LID mapping may not be cached locally"
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
no_session:
value:
error: "no session"
whatsapp_check_failed:
value:
error: "failed to check WhatsApp registration: connection error"
lid_store_unavailable:
value:
error: "LID store not available"
/user/contact/add:
post:
tags:
- User
summary: Add or update a contact
description: |
Add a new contact or update an existing contact's full name in WhatsApp.
The contact will be saved to the primary address book and synchronized across all devices.
**Important Notes:**
- Phone number must be in international format without the + prefix (e.g., 5511999999999)
- Full name is required and cannot be empty
- If contact already exists, the name will be updated
- Changes are synchronized across all devices
- Uses WhatsApp's app state sync mechanism (BuildContact)
**Technical Details:**
- Operation: `SyncdMutation_SET`
- App State Type: `WAPatchCriticalUnblockLow`
- Index Type: `IndexContact`
- Saves to primary addressbook automatically
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- phone
- full_name
properties:
phone:
type: string
description: Phone number in international format without + prefix
example: "5511999999999"
full_name:
type: string
description: Full name for the contact
example: "João Silva"
example:
phone: "5511999999999"
full_name: "João Silva"
responses:
200:
description: Contact added successfully
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
data:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "Contact added successfully"
phone:
type: string
example: "5511999999999"
full_name:
type: string
example: "João Silva"
success:
type: boolean
example: true
example:
code: 200
data:
success: true
message: "Contact added successfully"
phone: "5511999999999"
full_name: "João Silva"
success: true
400:
description: Bad request - missing or invalid parameters
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "phone number cannot be empty"
examples:
missing_phone:
value:
error: "phone number cannot be empty"
missing_name:
value:
error: "full name cannot be empty"
invalid_phone:
value:
error: "could not parse phone number"
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
no_session:
value:
error: "no session"
operation_failed:
value:
error: "failed to add contact: connection error"
/user/contact/remove:
post:
tags:
- User
summary: Remove a contact
description: |
Remove a contact from your WhatsApp address book.
The contact will be deleted and synchronized across all devices.
**Important Notes:**
- Phone number must be in international format without the + prefix (e.g., 5511999999999)
- Removing a contact doesn't block them or delete chat history
- Changes are synchronized across all devices
- Uses WhatsApp's app state sync mechanism (RemoveContact)
**Technical Details:**
- Operation: `SyncdMutation_REMOVE`
- App State Type: `WAPatchCriticalUnblockLow`
- Index Type: `IndexContact`
- Removes from primary addressbook
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- phone
properties:
phone:
type: string
description: Phone number in international format without + prefix
example: "5511999999999"
example:
phone: "5511999999999"
responses:
200:
description: Contact removed successfully
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
data:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "Contact removed successfully"
phone:
type: string
example: "5511999999999"
success:
type: boolean
example: true
example:
code: 200
data:
success: true
message: "Contact removed successfully"
phone: "5511999999999"
success: true
400:
description: Bad request - missing or invalid phone number
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
missing_phone:
value:
error: "phone number cannot be empty"
invalid_phone:
value:
error: "could not parse phone number"
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
no_session:
value:
error: "no session"
operation_failed:
value:
error: "failed to remove contact: connection error"
/user/status:
get:
tags:
- User
summary: Get user status message
description: |
Retrieves the current status message (about text) of the authenticated user.
This is the text that appears in the "About" section of the user's profile,
different from ephemeral status broadcasts.
security:
- ApiKeyAuth: []
responses:
200:
description: User status retrieved successfully
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
data:
type: object
properties:
status:
type: string
description: "Current status message/about text"
example: "Available for work 💼"
success:
type: boolean
example: true
example:
code: 200
data:
status: "Available for work 💼"
success: true
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "no session" }
post:
tags:
- User
summary: Set user status message
description: |
Updates the status message (about text) for the authenticated user.
This text appears in the "About" section of the user's profile.
**Important Notes:**
- This is different from ephemeral status broadcasts
- The status is visible to contacts based on privacy settings
- Changes are synchronized across all devices
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/SetMyStatusRequest"
responses:
200:
description: Status updated successfully
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
data:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "Status updated successfully"
status:
type: string
example: "Working from home 🏠"
success:
type: boolean
example: true
example:
code: 200
data:
success: true
message: "Status updated successfully"
status: "Working from home 🏠"
success: true
400:
description: Bad request - invalid JSON payload
content:
application/json:
schema:
example: { "error": "could not decode payload" }
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "no session" }
/user/update:
post:
tags:
- User
summary: Update user profile (name and/or token)
description: |
Allows authenticated users to update their own name and/or authentication token.
**Important Security Notes:**
- Token is invalidated immediately after change - you must use the new token in subsequent requests
- Changing the token will disconnect any active sessions using the old token
- Both fields are optional, but at least one must be provided and different from current value
- Token changes use optimistic locking to prevent race conditions
**Use Cases:**
- Change display name for better identification
- Rotate authentication token for security purposes
- Update both name and token in a single atomic operation
**Cache Behavior:**
- Old token cache is invalidated immediately
- New token cache is pre-populated with complete user configuration
- Zero downtime during token transition
**Requirements:**
- User must be authenticated (token header required)
- At least one field (name or token) must be provided
- Name: 1-255 characters
- Token: minimum 8 characters
- Token must be unique across all users
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: New user display name (1-255 characters)
minLength: 1
maxLength: 255
example: "John Doe Updated"
token:
type: string
description: New authentication token (minimum 8 characters, must be unique)
minLength: 8
example: "new_secure_token_12345678"
example:
name: "John Doe Updated"
token: "new_secure_token_12345678"
responses:
200:
description: Profile updated successfully
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
success:
type: boolean
example: true
data:
type: object
properties:
id:
type: string
description: User unique identifier
example: "bec45bb93cbd24cbec32941ec3c93a12"
name:
type: string
description: Updated user name
example: "John Doe Updated"
token:
type: string
description: New authentication token (use this for subsequent requests)
example: "new_secure_token_12345678"
message:
type: string
example: "Profile updated successfully"
example:
code: 200
success: true
data:
id: "bec45bb93cbd24cbec32941ec3c93a12"
name: "John Doe Updated"
token: "new_secure_token_12345678"
message: "Profile updated successfully"
400:
description: Bad request - validation error
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 400
success:
type: boolean
example: false
error:
type: string
example: "Name cannot be empty"
examples:
emptyName:
value:
code: 400
success: false
error: "Name cannot be empty"
noChanges:
value:
code: 400
success: false
error: "No changes detected"
tokenTooShort:
value:
code: 400
success: false
error: "Token too short (min 8 characters)"
nameTooLong:
value:
code: 400
success: false
error: "Name too long (max 255 characters)"
invalidJson:
value:
code: 400
success: false
error: "Invalid JSON"
401:
description: Unauthorized - user token required
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "unauthorized"
409:
description: Conflict - token already in use or concurrent modification
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 409
success:
type: boolean
example: false
error:
type: string
example: "Token already in use"
examples:
tokenInUse:
value:
code: 409
success: false
error: "Token already in use"
concurrentModification:
value:
code: 409
success: false
error: "Profile was modified by another request. Please try again"
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 500
success:
type: boolean
example: false
error:
type: string
example: "Failed to update profile: database error"
/user/business/profile:
post:
tags:
- User
summary: Get business profile information
description: |
Retrieves detailed business profile information for WhatsApp Business accounts including:
- Business email and address
- Business categories
- Operating hours with timezone
- Profile options and settings
**Note:** This endpoint only works for WhatsApp Business accounts.
Regular personal accounts will return an error.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/BusinessProfileRequest"
responses:
200:
description: Business profile retrieved successfully
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
data:
type: object
properties:
jid:
type: string
example: "5491155553934@s.whatsapp.net"
email:
type: string
example: "business@company.com"
address:
type: string
example: "123 Business Street, City, Country"
categories:
type: array
items:
type: object
properties:
id:
type: string
example: "PROFESSIONAL_SERVICES"
name:
type: string
example: "Professional Services"
profile_options:
type: object
additionalProperties:
type: string
example:
website: "https://company.com"
about: "We provide excellent services"
business_hours_timezone:
type: string
example: "America/Argentina/Buenos_Aires"
business_hours:
type: array
items:
type: object
properties:
day_of_week:
type: string
example: "MONDAY"
mode:
type: string
example: "OPEN"
open_time:
type: string
example: "09:00"
close_time:
type: string
example: "18:00"
success:
type: boolean
example: true
example:
code: 200
data:
jid: "5491155553934@s.whatsapp.net"
email: "business@company.com"
address: "123 Business Street, Buenos Aires, Argentina"
categories:
- id: "PROFESSIONAL_SERVICES"
name: "Professional Services"
- id: "CONSULTING"
name: "Business Consulting"
profile_options:
website: "https://company.com"
about: "We provide excellent professional services"
business_hours_timezone: "America/Argentina/Buenos_Aires"
business_hours:
- day_of_week: "MONDAY"
mode: "OPEN"
open_time: "09:00"
close_time: "18:00"
- day_of_week: "FRIDAY"
mode: "OPEN"
open_time: "09:00"
close_time: "17:00"
success: true
400:
description: Bad request - missing or invalid phone number
content:
application/json:
schema:
example: { "error": "missing phone number in payload" }
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "no session" }
/user/check:
post:
tags:
- User
summary: Checks if user has WhatsApp
description: Checks if users have an account with WhatsApp
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/Checkuser"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Users":
[
{
"IsInWhatsapp": true,
"JID": "5491155553934@s.whatsapp.net",
"Query": "5491155553934",
"VerifiedName": "Company Name",
},
{
"IsInWhatsapp": false,
"JID": "5521971532700@s.whatsapp.net",
"Query": "5521971532700",
"VerifiedName": "",
},
],
},
"success": true,
}
/user/presence:
post:
tags:
- User
summary: Send user global presence
description: Sends user presence Available or Unavailable
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/UserPresence"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data": { "Details": "Presence set successfuly" },
"success": true,
}
400:
description: Response
content:
application/json:
schema:
example:
{
"code": 400,
"error": "Invalid presence type. Allowed values: 'available', 'unavailable'",
"success": false,
}
/user/avatar:
post:
tags:
- User
summary: Gets profile picture information
description: |
Gets information about users profile pictures on WhatsApp, either a thumbnail (Preview=true) or full picture.
**Advanced Features:**
- **CommonGID**: Get profile pictures of users through a shared group, bypassing some privacy restrictions
- **InviteCode**: Preview group profile pictures before joining using an invite code
- **PersonaID**: Retrieve profile pictures of Meta AI bots
- **IsCommunity**: Specify when querying Community profile pictures
All advanced parameters are optional and maintain full backward compatibility.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/Checkavatar"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"direct_path": "/v/t61.24694-24/462747675_396645986828450_4384832977029011659_n.jpg?stp=dst-jpg_s96x96_tt6&ccb=11-4&oh=01_Q5Aa1wGBFw0hNQaFWtrLrS0BPrIrq6hN0w96ytplsv7__yI42g&oe=68565151&_nc_sid=5e03e0&_nc_cat=107",
"id": "1729003008",
"type": "preview",
"url": "https://pps.whatsapp.net/v/t61.24694-24/462747675_396645986828450_4384832977029011659_n.jpg?stp=dst-jpg_s96x96_tt6&ccb=11-4&oh=01_Q5Aa1wGBFw0hNQaFWtrLrS0BPrIrq6hN0w96ytplsv7__yI42g&oe=68565151&_nc_sid=5e03e0&_nc_cat=107",
},
"success": true,
}
/user/photo:
post:
tags:
- User
summary: Set profile photo
operationId: setMyProfilePhoto
description: |
Set or update the authenticated user's own WhatsApp profile photo.
**Accepted input formats:**
- **Base64 data URL**: `"data:image/jpeg;base64,/9j/4AAQ..."` — inline JPEG encoded as data URL
- **HTTP/HTTPS URL**: `"https://example.com/photo.jpg"` — remote image URL (will be downloaded server-side)
**Image requirements:**
- **Format**: JPEG only (`.jpg` / `.jpeg`). Other formats (PNG, GIF, WebP) are **not accepted** by WhatsApp and will be rejected
- **Maximum resolution**: 640x640 pixels (images larger than this may be rejected by WhatsApp)
- **Minimum resolution**: No strict minimum, but very small images may appear pixelated
- **File size**: No strict limit, but recommended under 5MB for optimal processing
- **Aspect ratio**: Square (1:1) is recommended. Non-square images may be cropped by WhatsApp clients
**How it works internally:**
Uses the WhatsApp `w:profile:picture` IQ namespace with an empty JID target, which tells the server to update the authenticated user's own profile picture rather than a group photo.
**Important Notes:**
- Changes propagate to all contacts immediately
- The previous profile photo is replaced (not archived)
- To remove the photo entirely, use the `/user/photo/remove` endpoint
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/SetProfilePhoto"
examples:
base64:
summary: Base64 data URL
value:
Image: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
url:
summary: Remote URL
value:
Image: "https://example.com/my-profile-photo.jpg"
responses:
200:
description: Profile photo set successfully
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
data:
type: object
properties:
Details:
type: string
example: "Profile photo set successfully"
PictureID:
type: string
description: "Unique identifier assigned to the new profile picture by WhatsApp"
example: "1729003008"
success:
type: boolean
example: true
example:
code: 200
data:
Details: "Profile photo set successfully"
PictureID: "1729003008"
success: true
400:
description: Bad request - invalid image format, missing field, or download failure
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 400
data:
type: string
success:
type: boolean
example: false
examples:
missing_image:
summary: Missing Image field
value:
code: 400
data: "missing Image in Payload"
success: false
not_jpeg:
summary: Image is not JPEG
value:
code: 400
data: "image must be in JPEG format. WhatsApp only accepts JPEG images for profile photos"
success: false
invalid_input:
summary: Invalid input format
value:
code: 400
data: 'Image must be a base64 data URL ("data:image/jpeg;base64,...") or an HTTP/HTTPS URL'
success: false
download_failed:
summary: Remote URL download failed
value:
code: 400
data: "could not download image from URL: HTTP error 404 when downloading from URL"
success: false
decode_failed:
summary: Base64 decode failed
value:
code: 400
data: "could not decode base64 encoded data from payload"
success: false
500:
description: Internal server error - no active session or WhatsApp rejected the image
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 500
data:
type: string
success:
type: boolean
example: false
examples:
no_session:
summary: No active WhatsApp session
value:
code: 500
data: "no session"
success: false
whatsapp_rejected:
summary: WhatsApp rejected the image
value:
code: 500
data: "failed to set profile photo: image not acceptable"
success: false
/user/photo/remove:
post:
tags:
- User
summary: Remove profile photo
operationId: removeMyProfilePhoto
description: |
Remove the authenticated user's own WhatsApp profile photo.
After removal, the profile will display the default WhatsApp placeholder avatar (grey silhouette).
**Important Notes:**
- This action is immediate and irreversible (the previous photo is permanently deleted from WhatsApp servers)
- All contacts will see the default placeholder avatar
- No request body is required
security:
- ApiKeyAuth: []
responses:
200:
description: Profile photo removed successfully
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
data:
type: object
properties:
Details:
type: string
example: "Profile photo removed successfully"
success:
type: boolean
example: true
example:
code: 200
data:
Details: "Profile photo removed successfully"
success: true
500:
description: Internal server error - no active session or WhatsApp error
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 500
data:
type: string
success:
type: boolean
example: false
examples:
no_session:
summary: No active WhatsApp session
value:
code: 500
data: "no session"
success: false
removal_failed:
summary: WhatsApp error during removal
value:
code: 500
data: "failed to remove profile photo: connection closed"
success: false
/user/contacts:
get:
tags:
- User
summary: Gets all contacts for the account
description: Gets complete list of contacts for the connected account
security:
- ApiKeyAuth: []
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"5491122223333@s.whatsapp.net":
{
"BusinessName": "",
"FirstName": "",
"Found": true,
"FullName": "",
"PushName": "FOP2",
},
"549113334444@s.whatsapp.net":
{
"BusinessName": "",
"FirstName": "",
"Found": true,
"FullName": "",
"PushName": "Guilherme Jansen",
},
},
}
/user/lid/get:
get:
tags:
- User LID
summary: Get LID from Phone/JID (GET)
description: Convert a phone number or JID to its corresponding LID (Link ID) format using GET method with query parameter
security:
- ApiKeyAuth: []
parameters:
- name: phone
in: query
required: true
description: Phone number or JID to convert to LID
schema:
type: string
example: "5521971532700@s.whatsapp.net"
responses:
200:
description: Successfully retrieved LID information
content:
application/json:
schema:
$ref: "#/definitions/LIDResponse"
400:
description: Invalid phone/JID format
content:
application/json:
schema:
example: { "error": "invalid phone/JID format" }
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "no session" }
post:
tags:
- User LID
summary: Get LID from Phone/JID (POST)
description: Convert a phone number or JID to its corresponding LID (Link ID) format using POST method with JSON payload
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/GetLIDRequest"
responses:
200:
description: Successfully retrieved LID information
content:
application/json:
schema:
$ref: "#/definitions/LIDResponse"
400:
description: Invalid phone/JID format
content:
application/json:
schema:
example: { "error": "invalid phone/JID format" }
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "no session" }
/user/lid/from-lid:
get:
tags:
- User LID
summary: Get Phone/JID from LID (GET)
description: Convert a LID (Link ID) to its corresponding phone number or JID using GET method with query parameter
security:
- ApiKeyAuth: []
parameters:
- name: lid
in: query
required: true
description: LID to convert to phone/JID
schema:
type: string
example: "2:abcd1234efgh5678@lid"
responses:
200:
description: Successfully retrieved phone/JID information
content:
application/json:
schema:
$ref: "#/definitions/JIDFromLIDResponse"
400:
description: Invalid LID format
content:
application/json:
schema:
example: { "error": "invalid LID format" }
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "no session" }
post:
tags:
- User LID
summary: Get Phone/JID from LID (POST)
description: Convert a LID (Link ID) to its corresponding phone number or JID using POST method with JSON payload
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/GetJIDFromLIDRequest"
responses:
200:
description: Successfully retrieved phone/JID information
content:
application/json:
schema:
$ref: "#/definitions/JIDFromLIDResponse"
400:
description: Invalid LID format
content:
application/json:
schema:
example: { "error": "invalid LID format" }
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "no session" }
/user/lid/mappings:
get:
tags:
- User LID
summary: List LID Mappings
description: List all LID (Link ID) mappings for the authenticated user, showing the relationship between phone numbers/JIDs and their corresponding LIDs
security:
- ApiKeyAuth: []
parameters:
- name: limit
in: query
required: false
description: Maximum number of mappings to return (default 100)
schema:
type: integer
default: 100
example: 50
- name: offset
in: query
required: false
description: Number of mappings to skip for pagination (default 0)
schema:
type: integer
default: 0
example: 0
responses:
200:
description: Successfully retrieved LID mappings
content:
application/json:
schema:
$ref: "#/definitions/LIDMappingsResponse"
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "no session" }
/chat/delete:
post:
tags:
- Chat
summary: Deletes a message sent by user
description: Deletes a messages sent by the same user
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/DeleteMessage"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data": { "Details": "Message deleted" },
"success": true,
}
/chat/markread:
post:
tags:
- Chat
summary: Marks a message as read
description: Marks one or more received messages as read
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/Markread"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data": { "Details": "Message(s) marked as read" },
"success": true,
}
/chat/react:
post:
tags:
- Chat
summary: Reacts to a message
description: Sends a reaction to some message. Phone, Body and Id are mandatory. If reaction is for your own message, prefix Phone with 'me:'. Body should be the reaction emoji.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/ReactionText"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Sent",
"Id": "3EB06F9067F80BAB89FF",
"Timestamp": "2022-05-10T12:49:08-03:00",
},
"success": true,
}
/chat/send/text:
post:
tags:
- Send
summary: Sends a text message
description: |
Sends a text message. Phone and Body are mandatory. If no Id is supplied, a random one will be generated.
**Reply Support (ContextInfo):**
ContextInfo is optional and used when replying to a message. Required fields for replies:
- `stanzaID`: The message ID you are replying to
- `participant`: JID of who wrote the original message
**Full Reply Preview (quotedMessage):**
For proper reply preview display on all devices, include `quotedMessage` with the original message content:
```json
{
"Phone": "5511999999999",
"Body": "My reply",
"ContextInfo": {
"stanzaID": "ABC123DEF456",
"participant": "5511888888888@s.whatsapp.net",
"quotedMessage": {
"conversation": "Original message text being replied to"
}
}
}
```
Without `quotedMessage`, replies will work but may not show the original message preview correctly on devices.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/MessageText"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Sent",
"Id": "90B2F8B13FAC8A9CF6B06E99C7834DC5",
"Timestamp": "2022-04-20T12:49:08-03:00",
},
"success": true,
}
/chat/send/link:
post:
tags:
- Send
summary: Send a link message with automatic preview from metadata.
description: Send a link message with automatic preview from metadata.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/MessageLink"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Sent",
"Id": "90B2F8B13FAC8A9CF6B06E99C7834DC5",
"Timestamp": "2022-04-20T12:49:08-03:00",
},
"success": true,
}
/chat/send/edit:
post:
tags:
- Send
summary: Edit an existing message
description: |
Edits the content of a previously sent message.
Only text messages can be edited and only within 15 minutes of sending.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/MessageEdit"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Message edited successfully",
"Id": "90B2F8B13FAC8A9CF6B06E99C7834DC5",
},
"success": true,
}
/chat/send/image:
post:
tags:
- Send
summary: Sends an image/picture message
description: Sends an image message. Supports both base64 encoded data (image/png or image/jpeg formats) and HTTP(S) URLs pointing to image files.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/MessageImage"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Sent",
"Id": "90B2F8B13FAC8A9CF6B06E99C7834DC5",
"Timestamp": "2022-04-20T12:49:08-03:00",
},
"success": true,
}
/chat/send/audio:
post:
tags:
- Send
summary: Sends an audio message
description: Sends an audio message. Supports both base64 encoded data (opus format, mime type audio/ogg) and HTTP(S) URLs pointing to audio files.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/MessageAudio"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Sent",
"Id": "90B2F8B13FAC8A9CF6B06E99C7834DC5",
"Timestamp": "2022-04-20T12:49:08-03:00",
},
"success": true,
}
/chat/send/document:
post:
tags:
- Send
summary: Sends a document message
description: Sends any document. Supports both base64 encoded data (application/octet-stream mime) and HTTP(S) URLs pointing to document files.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/MessageDocument"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Sent",
"Id": "90B2F8B13FAC8A9CF6B06E99C7834DC5",
"Timestamp": "2022-04-20T12:49:08-03:00",
},
"success": true,
}
/chat/send/video:
post:
tags:
- Send
summary: Sends a video message
description: Sends a video message. Supports both base64 encoded data (video/mp4 or video/3gpp format) and HTTP(S) URLs pointing to video files. Only H.264 video codec and AAC audio codec is supported.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/MessageVideo"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Sent",
"Id": "90B2F8B13FAC8A9CF6B06E99C7834DC5",
"Timestamp": "2022-04-20T12:49:08-03:00",
},
"success": true,
}
/chat/send/ptv:
post:
tags:
- Send
summary: Send PTV (Pre-Recorded Transfer Video)
description: Send a PTV by link or base64 (data URL). Only requires phone and video. PTV messages are sent as pre-recorded video.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/MessagePTV"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Sent",
"Id": "90B2F8B13FAC8A9CF6B06E99C7834DC5",
"Timestamp": "2022-04-20T12:49:08-03:00",
},
"success": true,
}
/chat/send/sticker:
post:
tags:
- Send
summary: Sends a sticker message
description: Sends a sticker message. Supports both base64 encoded data (image/webp format) and HTTP(S) URLs pointing to sticker files.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/MessageSticker"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Sent",
"Id": "90B2F8B13FAC8A9CF6B06E99C7834DC5",
"Timestamp": "2022-04-20T12:49:08-03:00",
},
"success": true,
}
/chat/send/location:
post:
tags:
- Send
summary: Sends a location message
description: Sends a location message
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/MessageLocation"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Sent",
"Id": "90B2F8B13FAC8A9CF6B06E99C7834DC5",
"Timestamp": "2022-04-20T12:49:08-03:00",
},
"success": true,
}
/chat/send/contact:
post:
tags:
- Send
summary: Sends a contact message
description: Sends a contact message in VCARD format
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/MessageContact"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Sent",
"Id": "90B2F8B13FAC8A9CF6B06E99C7834DC5",
"Timestamp": "2022-04-20T12:49:08-03:00",
},
"success": true,
}
/chat/send/list:
post:
tags:
- Send
summary: Sends a List message
description: Sends a List message
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/MessageList"
examples:
product_menu:
summary: "Catálogo de Produtos"
description: "Lista interativa com seções e itens"
value:
Phone: "5521979232690"
Title: "Catálogo 2024"
Text: "Confira nossos destaques do mês"
Footer: "Escolha uma opção abaixo"
ButtonText: "Ver opções"
Sections:
- Title: "Planos Disponíveis"
Rows:
- RowId: "plan_basic"
Title: "Plano Basic"
Description: "Ideal para pequenas equipes"
- RowId: "plan_pro"
Title: "Plano Pro"
Description: "Recursos avançados e suporte prioritário"
- Title: "Serviços Adicionais"
Rows:
- RowId: "service_consulting"
Title: "Consultoria"
Description: "Sessões 1:1 com especialistas"
- RowId: "service_training"
Title: "Treinamentos"
Description: "Workshops personalizados para equipes"
restaurant_menu:
summary: "Lista de Restaurante"
description: "Exemplo com seções de menu e itens"
value:
Phone: "120363312246943103@g.us"
Title: "Menu Especial da Semana"
Text: "Selecione a opção desejada abaixo"
Footer: "Atendimento das 11h às 23h"
ButtonText: "Escolher prato"
Sections:
- Title: "Entradas"
Rows:
- RowId: "entrada_01"
Title: "Bruschetta"
Description: "Tomate, manjericão e azeite"
- RowId: "entrada_02"
Title: "Carpaccio"
Description: "Finas lâminas de carne ao molho"
- Title: "Pratos Principais"
Rows:
- RowId: "principal_01"
Title: "Risoto de Camarão"
Description: "Arroz arbóreo e camarões grelhados"
- RowId: "principal_02"
Title: "Filé ao Molho Madeira"
Description: "Acompanhado de batatas gratinadas"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Sent",
"Id": "90B2F8B13FAC8A9CF6B06E99C7834DC5",
"Timestamp": "2022-04-20T12:49:08-03:00",
},
"success": true,
}
/chat/send/poll:
post:
tags:
- Send
summary: Sends a Poll to some group
description: Sends a Poll message. Group should contain the gid (group id), similar to 120363312246943103@g.us.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/MessagePoll"
examples:
group_poll:
summary: "Enquete em Grupo"
description: "Exemplo com envio para grupo"
value:
Group: "120363312246943103@g.us"
Header: "Qual o melhor horário?"
Options:
- "09:00"
- "14:00"
- "19:00"
MaxAnswer: 2
Presence: 2000
NumberCheck: true
direct_poll:
summary: "Enquete 1:1"
description: "Envio direto para um contato com pergunta personalizada"
value:
Phone: "5521979232690"
Question: "Você recomenda nosso atendimento?"
Options:
- "Sim"
- "Talvez"
- "Não"
MaxAnswer: 1
Duration: 86400
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Poll sent successfully",
"Id": "90B2F8B13FAC8A9CF6B06E99C7834DC5",
},
"success": true,
}
/chat/send/event:
post:
tags:
- Send
summary: Send event message
description: |
Send calendar event invitation with date, time, location, and description to a WhatsApp contact or group.
Recipients can add the event to their calendar. Perfect for meetings, appointments, conferences, and scheduled calls.
**Features:**
- **Event Details**: Name, description, start/end times
- **Location Support**: GPS coordinates and address
- **Call Integration**: Schedule video/voice meetings
- **Guest Management**: Allow additional guests
- **Cancellation**: Mark events as cancelled
- **Message Enhancements**: Replies, forwarding, mentions, expiration
**Use Cases:**
- 📅 Meeting invitations
- 🎉 Event planning (parties, conferences)
- 📞 Scheduled calls
- 🏢 Location-based events
- ❌ Event cancellations
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/MessageEvent"
examples:
business_meeting:
summary: "Business Meeting"
description: "Schedule a business meeting with location"
value:
Phone: "5521971532700"
Name: "Weekly Team Sync 📅"
Description: "Discussion of project updates, blockers, and next steps"
StartTime: 2524608000
EndTime: 2556143999
ExtraGuestsAllowed: true
IsScheduleCall: true
Location:
Name: "Conference Room A, Main Office"
DegreesLatitude: -23.5505
DegreesLongitude: -46.6333
NumberCheck: true
ContextInfo:
MentionedJID: ["5521971532700@s.whatsapp.net"]
virtual_event:
summary: "Virtual Event"
description: "Online event without physical location"
value:
Phone: "120363312246943103@g.us"
Name: "Product Launch Event 🚀"
Description: "Join us for the launch of our new product line"
StartTime: 1703184000
EndTime: 1703191200
ExtraGuestsAllowed: true
IsScheduleCall: true
MentionInfo:
MentionAll: true
responses:
200:
description: Event message sent successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Sent",
"Id": "EVENT_90B2F8B13FAC8A9CF6B06E99C7834DC5",
"Timestamp": "2022-04-20T12:49:08-03:00",
},
"success": true,
}
/chat/send/buttons:
post:
tags:
- Send
summary: Send interactive buttons message
description: |
Send an interactive message with buttons to a WhatsApp contact or group. Supports multiple button types and media headers.
**⚠️ IMPORTANTE - Campos de Texto (case canonical):**
- Payloads devem usar `lowerCamelCase` (ex.: `buttonId`, `displayText`) e, quando aplicável, campos snake_case opcionais como `pix_key`.
- Quando usar **media header** (`image`/`video`/`document`): forneça o conteúdo principal no campo `caption` ou `text`.
- Quando **não** houver media: utilize `text` ou `body`. Os handlers fazem mirror automático entre ambos.
- Exemplos com media usam `text` para manter compatibilidade com o backend.
**Supported Button Types:**
- 🔘 **reply/quick_reply** – botão de resposta rápida (retorna `buttonId`)
- 🔗 **url/cta_url** – abre um link HTTP(S) (`url` ou `merchant_url`)
- 📞 **call/cta_call** – inicia uma chamada de voz (`phone` em formato E.164)
- 📋 **copy/cta_copy** – copia um código (`code`)
- 💰 **pix/payment_info** – botão de pagamento PIX (`pix_key`, `merchant_name`, `pix_type`, ...)
- 💳 **review_and_pay** – revisão/pagamento com lista de itens (`items[]`)
**Media Header Support:**
- 🖼️ `image` – exibe imagem acima dos botões (`image.url` obrigatório)
- 🎥 `video` – exibe vídeo curto (`video.url`)
- 📄 `document` – exibe documento (`document.url`)
**Button Configuration:**
Cada botão requer `buttonId`, `buttonText.displayText` e `type`.
Campos adicionais variam conforme o tipo:
- **url/cta_url**: `url` ou `merchant_url`
- **call/cta_call**: `phone`
- **copy/cta_copy**: `code`
- **pix/payment_info**: `pix_key`, `merchant_name`, `pix_type`, `currency`, `total_value`, `total_offset`
- **review_and_pay**: `reference_id` e `items[]` com `name`, `quantity`, `amount_value`, `amount_offset`
**Payment Items Structure** (`review_and_pay`):
Cada item deve informar `name`, `quantity`, `amount_value`, `amount_offset`.
**Text Fields:**
- **title**: Título principal (opcional)
- **text/body**: Conteúdo da mensagem (obrigatório quando não há media)
- **footer**: Texto secundário (opcional)
- **caption**: Usado como corpo ao enviar media
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/ButtonsMessage"
examples:
pix_payment:
summary: "PIX"
description: "Botão PIX usando payload camelCase/snake_case compatível com a API."
value:
phone: "5521979232690"
title: "Pagamento PIX"
body: "Escaneie o QR Code para pagar via PIX"
footer: "Pagamento seguro e instantâneo"
buttons:
- buttonId: "pix_btn_1"
buttonText:
displayText: "Pagar com PIX"
type: "pix"
pix_key: "11999999999"
merchant_name: "Minha Loja"
pix_type: "PHONE"
review_and_pay:
summary: "Review and Pay"
description: "Exemplo completo com lista de itens, utilizando os campos esperados pelo backend."
value:
phone: "5521979232690"
title: "Revise seu pedido"
text: "Confirme os itens antes de pagar"
footer: "Envio em até 24h após confirmação"
buttons:
- buttonId: "review_pay_btn"
buttonText:
displayText: "Revisar e pagar"
type: "review_and_pay"
pix_key: "11999999999"
merchant_name: "Minha Loja"
pix_type: "PHONE"
currency: "BRL"
total_value: 10990
total_offset: 100
reference_id: "ORDER-2024-001"
items:
- name: "Fone de ouvido"
quantity: 1
amount_value: 7990
amount_offset: 100
- name: "Cabo USB-C"
quantity: 1
amount_value: 1990
amount_offset: 100
- name: "Frete expresso"
quantity: 1
amount_value: 1000
amount_offset: 100
pix_with_pdf:
summary: "PIX com Fatura PDF"
description: |
Botão review_and_pay com documento PDF no header - ideal para faturas, boletos e cobranças.
O PDF aparece como anexo e o botão permite pagamento instantâneo via PIX.
Tipos de pix_type suportados: CPF, CNPJ, EMAIL, PHONE, EVP (chave aleatória).
value:
phone: "5521979232690"
title: "Fatura Mensal"
text: "Sua fatura está disponível. Pague via PIX."
footer: "Vencimento: 15/01/2025"
document:
url: "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
buttons:
- buttonId: "pix_invoice_1"
buttonText:
displayText: "Pagar Fatura"
type: "review_and_pay"
pix_key: "empresa@dominio.com.br"
merchant_name: "Empresa LTDA"
pix_type: "EMAIL"
currency: "BRL"
total_value: 29990
total_offset: 100
reference_id: "FAT-2025-01-001"
items:
- name: "Mensalidade Janeiro/2025"
quantity: 1
amount_value: 24990
amount_offset: 100
- name: "Taxa de serviço"
quantity: 1
amount_value: 5000
amount_offset: 100
pix_evp:
summary: "PIX com Chave Aleatória (EVP)"
description: |
Botão PIX payment_info com chave aleatória EVP - ideal para pagamentos únicos.
EVP (End-to-End Virtual Payment Address) é a chave aleatória gerada pelo banco.
value:
phone: "5521979232690"
title: "Pagamento PIX"
body: "Copie a chave PIX e pague no app do seu banco"
footer: "Pagamento seguro e instantâneo"
buttons:
- buttonId: "pix_evp_1"
buttonText:
displayText: "Copiar Chave PIX"
type: "pix"
pix_key: "123e4567-e89b-12d3-a456-426614174000"
merchant_name: "Minha Loja"
pix_type: "EVP"
video_cta_url:
summary: "Vídeo com botão CTA"
description: "Equivalente ao cURL de demonstração de produto."
value:
phone: "5521979232690"
title: "Demonstração do Produto"
text: "Assista ao vídeo e compre!"
footer: "Pagamento instantâneo"
video:
url: "https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4"
buttons:
- buttonId: "cta_url_1"
buttonText:
displayText: "Abrir Site"
type: "cta_url"
url: "https://exemplo.com/oferta"
document_cta_url:
summary: "Catálogo em PDF"
description: "Download de catálogo com botão CTA URL."
value:
phone: "5521979232690"
title: "Catálogo de Produtos"
text: "Baixe nosso catálogo"
footer: "PDF com todos os produtos"
document:
url: "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
buttons:
- buttonId: "cta_url_1"
buttonText:
displayText: "Abrir Site"
type: "cta_url"
url: "https://exemplo.com/oferta"
image_quick_reply:
summary: "Imagem com resposta rápida"
description: "Confirmação de presença usando quick reply."
value:
phone: "5521979232690"
title: "Confirme sua presença"
text: "Evento VIP em 12/10 às 20h"
footer: "Responda abaixo"
image:
url: "https://picsum.photos/600/400.jpg"
buttons:
- buttonId: "reply_talvez"
buttonText:
displayText: "Talvez"
type: "quick_reply"
multi_action:
summary: "Copy + URL + Call"
description: "Mescla de diferentes tipos de botões interativos."
value:
phone: "5521979232690"
title: "Ofertas do Dia"
text: "Escolha uma ação abaixo:"
footer: "Equipe ZuckZapGo"
buttons:
- buttonId: "cta_copy_1"
buttonText:
displayText: "Copiar Cupom"
type: "cta_copy"
code: "CUPOM123"
- buttonId: "cta_url_1"
buttonText:
displayText: "Abrir Site"
type: "cta_url"
url: "https://exemplo.com/oferta"
- buttonId: "cta_call_1"
buttonText:
displayText: "Falar com Vendas"
type: "cta_call"
phone: "+5511988888888"
responses:
200:
description: Buttons message sent successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Sent",
"Id": "BUTTONS_8A7B9C2D1E3F4A5B6C7D8E9F0A1B2C3D",
"Timestamp": "2022-04-20T12:49:08-03:00",
},
"success": true,
}
/chat/send/flow:
post:
tags:
- Send
summary: Send native flow interactive message
description: |
Send a native WhatsApp Flow interactive message with custom parameters and flow versioning support.
**What are WhatsApp Flows:**
Native interactive forms and experiences within WhatsApp chat. Flows allow collecting structured data,
multi-step processes, and rich interactive experiences without leaving WhatsApp.
**Flow Message Structure:**
- **Body/Text/Message**: Main message text (required, at least one of these fields)
- **Header**: Optional header with title, subtitle, and media
- **Footer**: Optional footer text
- **Buttons**: Array of flow buttons with parameters
**Header Configuration:**
- **Title**: Main header title
- **Subtitle**: Secondary header text
- **Media**: Media object with type (image/video/document), Url, Caption, Filename, MimeType
**Button Configuration:**
Each button requires:
- **Name**: Button name/identifier
- **ButtonParams** or **ButtonParamsJSON**: Button parameters as object or JSON string
- **Params** or **ParamsJSON**: Flow parameters as object or JSON string
**Flow Parameters:**
- **MessageVersion**: Flow message format version (1, 2, 3, etc.)
- **MessageParams** or **MessageParamsJSON**: Flow-specific parameters
**Common Use Cases:**
- 📋 Data collection forms (surveys, registrations)
- 🛒 Product catalogs with selections
- 📅 Appointment booking flows
- 💳 Payment collection forms
- 📝 Multi-step applications
- ✅ Order confirmations with options
**Advanced Features:**
- Context info for replying to messages
- Mention support for tagging users
- Forward info for message forwarding
- Presence and duration control
- Number validation before sending
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/FlowMessage"
examples:
simple_flow:
summary: "Simple Flow Message"
description: "Basic flow with single button"
value:
Phone: "5521971532700"
Body: "Complete your profile to get started"
Footer: "Powered by FlowAPI"
Buttons:
- Name: "complete_profile"
ButtonParams:
display_text: "Complete Profile"
flow_id: "123456789"
flow_token: "ABC123XYZ"
Params:
mode: "draft"
version: "3.0"
flow_with_header:
summary: "Flow with Media Header"
description: "Flow message with image header"
value:
Phone: "5521971532700"
Header:
Title: "Customer Survey 📊"
Subtitle: "Help us improve"
Media:
Type: "image"
Url: "https://example.com/survey-banner.jpg"
Caption: "Your feedback matters"
Body: "Take 2 minutes to share your experience"
Footer: "All responses are confidential"
Buttons:
- Name: "start_survey"
ButtonParams:
display_text: "Start Survey"
flow_id: "987654321"
flow_token: "SURVEY2024"
Params:
mode: "published"
version: "3.0"
appointment_flow:
summary: "Appointment Booking Flow"
description: "Multi-step appointment booking"
value:
Phone: "120363312246943103@g.us"
Body: "Book your appointment with our specialist team"
Footer: "Available slots updated in real-time"
MessageVersion: 3
Buttons:
- Name: "book_appointment"
ButtonParamsJSON: '{"display_text":"📅 Book Now","flow_id":"555111222","flow_token":"APPT2024"}'
ParamsJSON: '{"mode":"published","flow_name":"Appointment Booking","version":"3.0"}'
data_collection:
summary: "Data Collection Form"
description: "Structured data collection flow"
value:
Phone: "5521971532700"
Header:
Title: "Registration Form 📝"
Subtitle: "Quick and easy signup"
Body: "Complete your registration in just a few steps"
Footer: "Your data is encrypted and secure"
MessageVersion: 3
MessageParams:
flow_type: "registration"
required_fields: ["name", "email", "phone"]
optional_fields: ["company", "role"]
Buttons:
- Name: "start_registration"
ButtonParams:
display_text: "Start Registration"
flow_id: "REG123456"
flow_token: "TOKEN_REG_2024"
Params:
mode: "published"
version: "3.0"
data_schema: "registration_v1"
responses:
200:
description: Flow message sent successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Sent",
"Id": "FLOW_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P",
"Timestamp": "2022-04-20T12:49:08-03:00",
},
"success": true,
}
/chat/send/carousel:
post:
tags:
- Send
summary: Send carousel message with multiple cards
description: |
Send a carousel message containing multiple scrollable cards. Each card can include media (image, video, document),
text content, and interactive buttons. Perfect for product showcases, service catalogs, and multi-option presentations.
**Carousel Structure:**
- **Phone**: Recipient phone number or group JID (required)
- **Message**: Introductory message text before carousel (required)
- **Carousel**: Array of card objects (required, at least 1 card)
**Card Structure:**
Each card can contain:
- **Text**: Card body text (required)
- **MediaUrl**: URL or base64 data URL for media (optional)
- **MediaType**: Type of media - image, video, or document (required if MediaUrl provided)
- **Filename**: Document filename (optional, for documents)
- **Caption**: Media caption text (optional)
- **Buttons**: Array of button objects (required)
**Button Types:**
- 🔘 **reply** - Quick reply button (id + label)
- 🔗 **url** - Opens web link (url + label)
- 📋 **copy** - Copies code to clipboard (id as code + label)
- 📞 **call** - Initiates phone call (id as phone + label)
**Button Structure:**
- **Id**: Button identifier (for reply/copy) or phone number (for call)
- **Label**: Button display text
- **Url**: Destination URL (for url type buttons)
- **Type**: Button type (reply, url, copy, call)
**Media Support:**
- **Images**: JPEG, PNG, WebP (recommended max 5MB)
- **Videos**: MP4, 3GP (recommended max 16MB, max 90 seconds)
- **Documents**: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT
**Common Use Cases:**
- 🛍️ Product catalogs with images and buy buttons
- 🏨 Hotel room options with photos and booking links
- 🍕 Restaurant menu with dishes and order buttons
- 🎓 Course offerings with descriptions and enrollment
- 🏢 Service packages with pricing and contact options
- 📱 Feature comparisons with specifications
**Best Practices:**
- Use 2-10 cards per carousel (optimal user experience)
- Keep card text concise (50-100 characters recommended)
- Use high-quality images (at least 800x600px)
- Limit to 1-3 buttons per card
- Maintain consistent card structure throughout carousel
**Advanced Features:**
- Context info for replying to messages
- Mention support for tagging users
- Forward info for message forwarding
- Presence and duration control
- Number validation before sending
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/CarouselMessage"
examples:
product_catalog:
summary: "Product Catalog"
description: "E-commerce product showcase with images"
value:
Phone: "5521971532700"
Message: "Check out our featured products! 🛍️"
Carousel:
- Text: "Premium Wireless Headphones 🎧\n\n• Noise cancellation\n• 30h battery\n• Premium sound\n\n$299.99"
MediaUrl: "https://picsum.photos/600/400.jpg"
MediaType: "image"
Caption: "Best Seller!"
Buttons:
- Id: "buy_headphones"
Label: "🛒 Buy Now"
Url: "https://store.example.com/headphones"
Type: "url"
- Id: "headphones_details"
Label: "ℹ️ Details"
Type: "reply"
- Text: "Smart Watch Pro ⌚\n\n• Fitness tracking\n• Heart rate monitor\n• Water resistant\n\n$199.99"
MediaUrl: "https://picsum.photos/600/400.jpg"
MediaType: "image"
Caption: "New Arrival!"
Buttons:
- Id: "buy_watch"
Label: "🛒 Buy Now"
Url: "https://store.example.com/watch"
Type: "url"
- Id: "watch_details"
Label: "ℹ️ Details"
Type: "reply"
- Text: "Bluetooth Speaker 🔊\n\n• 360° sound\n• 12h battery\n• Portable design\n\n$79.99"
MediaUrl: "https://picsum.photos/600/400.jpg"
MediaType: "image"
Caption: "Hot Deal!"
Buttons:
- Id: "buy_speaker"
Label: "🛒 Buy Now"
Url: "https://store.example.com/speaker"
Type: "url"
- Id: "speaker_details"
Label: "ℹ️ Details"
Type: "reply"
video_carousel:
summary: "Video Carousel"
description: "Product demos with video previews"
value:
Phone: "5521971532700"
Message: "Watch our product demonstrations! 🎥"
Carousel:
- Text: "Product Setup Tutorial\n\nLearn how to set up your new device in under 5 minutes"
MediaUrl: "https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4"
MediaType: "video"
Caption: "Quick Setup Guide"
Buttons:
- Id: "PDF_MANUAL_123"
Label: "📋 Copy Manual Code"
Type: "copy"
- Id: "full_tutorial"
Label: "🎬 Full Tutorial"
Url: "https://youtube.com/watch?v=example"
Type: "url"
- Text: "Advanced Features Demo\n\nDiscover pro tips and hidden features"
MediaUrl: "https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4"
MediaType: "video"
Caption: "Pro Tips"
Buttons:
- Id: "features_guide"
Label: "📖 Feature Guide"
Type: "reply"
responses:
200:
description: Carousel message sent successfully
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Sent",
"Id": "CAROUSEL_7C8D9E0F1A2B3C4D5E6F7G8H9I0J1K2L",
"Timestamp": "2022-04-20T12:49:08-03:00",
},
"success": true,
}
400:
description: Bad request - invalid input
content:
application/json:
schema:
example:
{
"code": 400,
"error": "Missing required field: Name or StartTime",
"success": false,
}
500:
description: Internal server error
content:
application/json:
schema:
example:
{ "code": 500, "error": "no session", "success": false }
/chat/downloadimage:
post:
tags:
- Chat
summary: Downloads Image from message
description: Downloads an Image from a message and returns it Base64 media encoded
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/DownloadImage"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Data": "data:image/jpeg;base64,iVBORw0KGgoA5CYII...=",
"Mimetype": "image/jpeg",
},
"success": true,
}
/chat/downloadvideo:
post:
tags:
- Chat
summary: Downloads Video from message
description: Downloads a Video from a message and returns it Base64 media encoded
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/DownloadImage"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Data": "data:video/mp4;base64,iVBORw0KGgoA5CYII...=",
"Mimetype": "video/mp4",
},
"success": true,
}
/chat/downloaddocument:
post:
tags:
- Chat
summary: Downloads Document from message
description: Downloads a Document from a message and returns it Base64 media encoded
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/DownloadImage"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Data": "data:application/pdf;base64,iVBORw0KGgoA5CYII...=",
"Mimetype": "application/pdf",
},
"success": true,
}
/chat/downloadaudio:
post:
tags:
- Chat
summary: Downloads Audio from message
description: Downloads an Audio file from a message and returns it Base64 media encoded
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/DownloadImage"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Data": "data:audio/ogg;base64,T2dnUwACAAAAAAA...=",
"Mimetype": "audio/ogg",
},
"success": true,
}
/chat/downloadsticker:
post:
tags:
- Chat
summary: Downloads Sticker from message
description: Downloads a Sticker from a message and returns it Base64 media encoded
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/DownloadImage"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Data": "data:image/webp;base64,UklGRroBAABXRUJQVlA4TBEAAAAvAAAAAAfQ//73v/+BiOh/AAA=",
"Mimetype": "image/webp",
},
"success": true,
}
/chat/presence:
post:
tags:
- Chat
summary: Sets chat presence
description: Sends indication if you are writing or not (state could be either "composing" or "paused"). Optional Media can be set to "audio" for indicating recording a message
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/ChatPresence"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data": { "Details": "Chat presence set successfuly" },
"success": true,
}
/chat/pin:
post:
tags:
- Chat
summary: Pin or unpin a chat
description: Pins or unpins a chat in the conversation list. Pinned chats appear at the top of the chat list.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- phone
- pin
properties:
phone:
type: string
description: Phone number or group JID
example: "5491155553333"
pin:
type: boolean
description: True to pin, false to unpin
example: true
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"success": true,
"message": "Chat pinned successfully",
"jid": "5491155553333@s.whatsapp.net",
"pinned": true,
},
"success": true,
}
/chat/archive:
post:
tags:
- Chat
summary: Archive or unarchive a chat
description: Archives or unarchives a chat. Archived chats are hidden from the main chat list. When archiving, the chat is automatically unpinned.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- phone
- archive
properties:
phone:
type: string
description: Phone number or group JID
example: "5491155553333"
archive:
type: boolean
description: True to archive, false to unarchive
example: true
last_message_timestamp:
type: integer
description: Unix timestamp of last message (optional)
example: 1703123456
last_message_id:
type: string
description: ID of the last message (optional)
example: "3EB0794DCEFA60"
last_message_from_me:
type: boolean
description: Whether last message was sent by you (optional)
example: false
last_message_remote_jid:
type: string
description: Remote JID of last message (optional)
example: "5491155553333@s.whatsapp.net"
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"success": true,
"message": "Chat archived successfully",
"jid": "5491155553333@s.whatsapp.net",
"archived": true,
},
"success": true,
}
/chat/mute:
post:
tags:
- Chat
summary: Mute or unmute a chat
description: Mutes or unmutes notifications for a specific chat. Mute duration can be specified.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- phone
- mute
properties:
phone:
type: string
description: Phone number or group JID
example: "5491155553333"
mute:
type: boolean
description: True to mute, false to unmute
example: true
mute_duration:
type: string
description: Mute duration - "8h", "1w", or "always" (default is "always")
example: "8h"
enum: ["8h", "1w", "always"]
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"success": true,
"message": "Chat muted successfully",
"jid": "5491155553333@s.whatsapp.net",
"muted": true,
"duration": "8h",
},
"success": true,
}
/chat/star:
post:
tags:
- Chat
summary: Star or unstar a message
description: Stars or unstars a specific message. Starred messages can be easily found later.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- chat_jid
- message_id
- star
properties:
chat_jid:
type: string
description: JID of the chat containing the message
example: "5491155553333@s.whatsapp.net"
sender_jid:
type: string
description: JID of message sender (optional, required for group messages)
example: "5491155554444@s.whatsapp.net"
message_id:
type: string
description: ID of the message to star/unstar
example: "3EB0794DCEFA60"
from_me:
type: boolean
description: Whether the message was sent by you
example: false
star:
type: boolean
description: True to star, false to unstar
example: true
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"success": true,
"message": "Message starred successfully",
"chat_jid": "5491155553333@s.whatsapp.net",
"message_id": "3EB0794DCEFA60",
"starred": true,
},
"success": true,
}
/chat/delete-chat:
post:
tags:
- Chat
summary: Delete chat from chat list
description: |
Delete a chat entirely from the chat list. This is different from clearing chat history - it removes the chat from your chat list completely.
**Important differences:**
- **Delete Chat**: Removes chat from list (this endpoint)
- **Clear Chat**: Only clears message history but keeps chat in list
The chat will reappear in your list if you receive a new message from this contact.
Optionally provide last message details for more precise deletion and better synchronization across devices.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- phone
properties:
phone:
type: string
description: Phone number or JID of the chat to delete
example: "5521979232690"
last_message_timestamp:
type: integer
format: int64
description: Unix timestamp of the last message (optional, improves sync)
example: 1703123456
last_message_id:
type: string
description: ID of the last message (optional, improves sync)
example: "3EB0794DCEFA60ABC123"
last_message_from_me:
type: boolean
description: Whether the last message was sent by you (optional)
example: false
last_message_sender_jid:
type: string
description: JID of last message sender - required for group chats if providing message details (optional)
example: "5521988887777@s.whatsapp.net"
examples:
simple:
summary: "Simple delete (individual chat)"
description: "Delete an individual chat without message details"
value:
phone: "5521979232690"
complete_individual:
summary: "Complete delete (individual chat with details)"
description: "Delete individual chat with last message information for better sync"
value:
phone: "5521979232690"
last_message_timestamp: 1703123456
last_message_id: "3EB0794DCEFA60ABC123"
last_message_from_me: false
complete_group:
summary: "Complete delete (group chat)"
description: "Delete group chat with last message details including sender"
value:
phone: "120363321748594524@g.us"
last_message_timestamp: 1703123456
last_message_id: "3EB0794DCEFA60ABC123"
last_message_from_me: false
last_message_sender_jid: "5521988887777@s.whatsapp.net"
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"success": true,
"message": "Chat deleted successfully",
"jid": "5521979232690@s.whatsapp.net",
},
"success": true,
}
400:
description: Bad Request
content:
application/json:
schema:
example:
{
"code": 400,
"data": "missing phone in payload",
"success": false,
}
500:
description: Internal Server Error
content:
application/json:
schema:
example:
{
"code": 500,
"data": "failed to delete chat",
"success": false,
}
/chat/list:
get:
tags:
- Sync
summary: List synchronized chats from local storage
description: |
Returns a list of chats that have already been synchronized to the local database. This endpoint queries the `whatsmeow_chat_settings` table directly.
**Important Notes:**
- Only returns chats that have been previously synchronized or modified
- Does NOT include read/unread status (not stored locally)
- Does NOT trigger new synchronization
- Returns pinned, archived, and muted status
**Use Cases:**
- Display list of active chats
- Show pinned/archived chats
- Quick access to chat settings
**For full synchronization:** Use `POST /sync/app-state` or `POST /sync/full-history`
security:
- ApiKeyAuth: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
chats:
type: array
items:
type: object
properties:
chat_jid:
type: string
description: Full JID of the chat
example: "5521979232690@s.whatsapp.net"
phone_number:
type: string
description: Extracted phone number from JID
example: "5521979232690"
muted_until:
type: integer
format: int64
description: Unix timestamp when mute expires (0 if not muted)
example: 1735689600
pinned:
type: boolean
description: Whether chat is pinned
example: true
archived:
type: boolean
description: Whether chat is archived
example: false
stats:
type: object
properties:
total:
type: integer
description: Total number of synchronized chats
example: 45
pinned_count:
type: integer
description: Number of pinned chats
example: 3
archived_count:
type: integer
description: Number of archived chats
example: 12
muted_count:
type: integer
description: Number of muted chats
example: 5
404:
description: Client not found
500:
description: Database query failed
/sync/app-state:
post:
tags:
- Sync
summary: Force complete app state synchronization
description: |
Forces a complete synchronization of all 5 app state patch types without needing to reconnect to WhatsApp. This updates chat settings, blocks, and other WhatsApp configurations.
**What this syncs:**
- `critical_block`: Critical blocking data
- `critical_unblock_low`: Critical unblocking (low priority)
- `regular_low`: Regular patches (low priority)
- `regular_high`: Regular patches (high priority)
- `regular`: Standard patches
**How it works:**
1. Calls `FetchAppState()` for each patch type
2. If `full_sync=true`, deletes local version to force complete resync
3. Updates local database automatically
4. No reconnection required
**Auto Recovery Feature:**
When `auto_recovery=true` (default), if a sync fails for any patch type, the system will automatically request a recovery from the primary device using `BuildAppStateRecoveryRequest()`. This requests an unencrypted snapshot of the app state from your phone, which helps recover from corrupted or incomplete sync data.
**Use Cases:**
- After device settings change
- Periodic sync to ensure data consistency
- Recover from sync issues (auto_recovery helps here)
- Update chat settings (muted, pinned, archived)
**Response Time:** Typically 2-5 seconds for all 5 patch types
security:
- ApiKeyAuth: []
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
full_sync:
type: boolean
description: Whether to force full resync (deletes local version first)
default: true
example: true
auto_recovery:
type: boolean
description: Whether to automatically request recovery from primary device if sync fails. Uses BuildAppStateRecoveryRequest to request unencrypted snapshot from phone.
default: true
example: true
example:
full_sync: true
auto_recovery: true
responses:
200:
description: Sync completed (may contain partial errors)
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: True if all patches synced successfully
example: true
message:
type: string
example: "App state synchronized successfully. All 5 patch types updated."
results:
type: array
items:
type: object
properties:
name:
type: string
description: Patch type name
example: "critical_block"
success:
type: boolean
description: Whether this patch synced successfully
example: true
error:
type: string
description: Error message if sync failed (omitted on success)
example: "timeout waiting for patches"
duration:
type: string
description: Time taken to sync this patch
example: "1.234s"
recovery_requested:
type: boolean
description: Whether recovery was requested for this patch (only present if auto_recovery enabled and sync failed)
example: false
auto_recovery_enabled:
type: boolean
description: Whether auto recovery was enabled for this sync request
example: true
example:
success: true
message: "App state synchronized successfully. All 5 patch types updated."
auto_recovery_enabled: true
results:
- name: "critical_block"
success: true
duration: "1.234s"
recovery_requested: false
- name: "critical_unblock_low"
success: true
duration: "0.856s"
recovery_requested: false
- name: "regular_low"
success: true
duration: "0.523s"
recovery_requested: false
- name: "regular_high"
success: true
duration: "0.412s"
recovery_requested: false
- name: "regular"
success: true
duration: "0.678s"
recovery_requested: false
400:
description: Client not connected
404:
description: Client not found
/sync/history-request:
post:
tags:
- Sync
summary: Request history sync for specific chat (ON_DEMAND)
description: |
Sends an ON_DEMAND history sync request for a specific chat. The history arrives asynchronously via HistorySync events through your configured webhook or websocket.
**How it works:**
1. You provide the oldest known message details
2. Request is sent to your primary device
3. Primary device sends history chunks asynchronously
4. History arrives via `HistorySync` events in webhook/websocket
5. Local database is updated automatically when events are processed
**Requirements:**
- Primary device must be online
- Must have `oldest_message_id` from that chat
- Message timestamp must be accurate
**Use Cases:**
- Load older messages for a specific chat
- Recover missing messages
- Pagination of chat history
**Important:**
- History does NOT arrive in HTTP response
- Check webhook/websocket for `HistorySync` events
- May take a few seconds to minutes depending on history size
- Respects WhatsApp's rate limits
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- phone
- oldest_message_id
- oldest_message_timestamp
properties:
phone:
type: string
description: Phone number or JID of the chat
example: "5521979232690"
oldest_message_id:
type: string
description: Message ID of the oldest message you have
example: "3EB0ABCD1234567890"
oldest_message_timestamp:
type: integer
format: int64
description: Unix timestamp in milliseconds of the oldest message
example: 1704067200000
oldest_from_me:
type: boolean
description: Whether the oldest message was sent by you
example: false
count:
type: integer
format: int32
description: Number of messages to request (default 50, max depends on WhatsApp limits)
default: 50
example: 100
examples:
basic:
summary: "Request 50 messages"
value:
phone: "5521979232690"
oldest_message_id: "3EB0ABCD1234567890"
oldest_message_timestamp: 1704067200000
oldest_from_me: false
batch:
summary: "Request 100 messages for pagination"
value:
phone: "5521979232690"
oldest_message_id: "3EB0ABCD1234567890"
oldest_message_timestamp: 1704067200000
oldest_from_me: true
count: 100
responses:
200:
description: Request sent successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "History sync request sent successfully. History will arrive asynchronously via HistorySync events (webhook/websocket)."
request_id:
type: string
description: Request ID for tracking (same as oldest_message_id)
example: "3EB0ABCD1234567890"
chat:
type: string
description: Full JID of the chat
example: "5521979232690@s.whatsapp.net"
count:
type: integer
description: Number of messages requested
example: 100
400:
description: Invalid request (missing parameters or invalid JID)
404:
description: Client not found
500:
description: Failed to send request
/sync/full-history:
post:
tags:
- Sync
summary: Request FULL history sync for ALL chats (FULL_HISTORY_SYNC_ON_DEMAND)
description: |
**REVOLUTIONARY FEATURE:** Requests a complete history synchronization for ALL chats, just like the initial connection sync. This is the first public implementation of WhatsApp's `FULL_HISTORY_SYNC_ON_DEMAND` protocol feature!
**How it works:**
1. Configures sync period (days) and size limit (MB)
2. Sends `FULL_HISTORY_SYNC_ON_DEMAND` request to primary device
3. Primary device processes ALL chats within the specified period
4. History arrives asynchronously via multiple `HistorySync` events
5. Local database updates automatically as events are received
6. Works EXACTLY like initial WhatsApp connection sync
**Configuration Options:**
- **days_limit**: How far back to sync (7, 30, 90 days, etc.)
- **size_mb_limit**: Maximum total size to prevent overload
- **include_groups**: Whether to include group chat history
- **include_calls**: Whether to include call history
**Capabilities Enabled:**
- Group history with full participant info
- Bot/business message history
- Reactions and polls
- Message associations (replies, forwards)
- Call logs (if enabled)
- Guest chat history
**Requirements:**
- Primary device must be online
- Primary device must have history available
- Sufficient storage quota
- No reconnection needed!
**Use Cases:**
- Periodic full backup of recent conversations
- Recover all chats after data loss
- Sync new secondary device
- Get complete conversation history for reporting
- Migrate chat data between systems
**Performance:**
- Request is immediate (< 1 second)
- History arrives over minutes/hours depending on volume
- Multiple `HistorySync` events will arrive
- Watch webhook/websocket for events with matching `request_id`
**Important Notes:**
- History does NOT arrive in HTTP response
- Monitor webhook/websocket for `HistorySync` events
- Events contain `fullHistorySyncOnDemandRequestMetadata` with your `request_id`
- Respects WhatsApp's quotas and limits
- Primary device controls actual days/size based on availability
security:
- ApiKeyAuth: []
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
days_limit:
type: integer
format: uint32
description: Number of days of history to sync (default 30)
default: 30
example: 30
size_mb_limit:
type: integer
format: uint32
description: Maximum size in MB to download (default 1000 = 1GB)
default: 1000
example: 1000
include_groups:
type: boolean
description: Include group chat history (default true)
default: true
example: true
include_calls:
type: boolean
description: Include call log history (default false)
default: false
example: false
examples:
last_week:
summary: "Sync last 7 days"
description: "Quick sync of recent conversations"
value:
days_limit: 7
size_mb_limit: 500
include_groups: true
include_calls: false
last_month:
summary: "Sync last 30 days (default)"
description: "Standard monthly backup"
value:
days_limit: 30
size_mb_limit: 1000
include_groups: true
include_calls: false
last_quarter:
summary: "Sync last 90 days"
description: "Quarterly full backup"
value:
days_limit: 90
size_mb_limit: 2000
include_groups: true
include_calls: true
full_year:
summary: "Sync last 365 days"
description: "Complete annual history"
value:
days_limit: 365
size_mb_limit: 5000
include_groups: true
include_calls: true
responses:
200:
description: Full history sync request sent successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "Full history sync requested successfully. History will arrive asynchronously via HistorySync events (webhook/websocket). This works exactly like the initial connection sync."
request_id:
type: string
description: Unique request ID for tracking (16-byte hex string)
example: "A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6"
config:
type: object
description: Confirmed configuration used for the request
properties:
days_limit:
type: integer
example: 30
size_mb_limit:
type: integer
example: 1000
include_groups:
type: boolean
example: true
include_calls:
type: boolean
example: false
400:
description: Client not connected to WhatsApp
404:
description: Client not found
500:
description: Failed to send full history sync request
/label/manage:
post:
tags:
- Label
summary: Create, edit or delete labels
description: |
Manages labels that can be applied to chats and messages for organization.
**Label ID Format:**
- Label IDs are **strings** in the format: `"label_" + unix_timestamp`
- Example: `"label_1703123456"` (NOT a UUID or plain number)
- When creating a new label, you can omit `label_id` and it will be auto-generated
- When updating or deleting, you must provide the exact `label_id` string
**Operations:**
- **Create**: Omit `label_id` (auto-generated) or provide custom one, include `label_name` and `label_color`
- **Update**: Provide `label_id`, `label_name`, and `label_color`
- **Delete**: Provide `label_id` and set `delete: true`
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- label_name
- label_color
properties:
label_id:
type: string
description: |
Label ID in format "label_" + unix_timestamp (e.g., "label_1703123456").
- **Auto-generated if omitted** when creating new labels
- **Required when deleting** (set delete: true)
- **Optional when updating** existing labels
example: "label_1703123456"
label_name:
type: string
description: Name of the label (required for create/update, ignored for delete)
example: "Important"
label_color:
type: integer
description: Color code for the label (0-19, required for create/update, ignored for delete)
example: 1
minimum: 0
maximum: 19
delete:
type: boolean
description: Set to true to delete the label (requires label_id)
example: false
default: false
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"success": true,
"message": "Label created successfully",
"label_id": "label_1703123456",
"label_name": "Important",
"label_color": 1,
},
"success": true,
}
/label/chat:
post:
tags:
- Label
summary: Apply or remove label from chat
description: Applies or removes a label from a specific chat.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- phone
- label_id
- apply
properties:
phone:
type: string
description: Phone number or group JID
example: "5491155553333"
label_id:
type: string
description: ID of the label to apply/remove
example: "label_1703123456"
apply:
type: boolean
description: True to apply label, false to remove
example: true
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"success": true,
"message": "Label applied successfully",
"jid": "5491155553333@s.whatsapp.net",
"label_id": "label_1703123456",
"applied": true,
},
"success": true,
}
/label/message:
post:
tags:
- Label
summary: Apply or remove label from message
description: Applies or removes a label from a specific message.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- phone
- message_id
- label_id
- apply
properties:
phone:
type: string
description: Phone number or group JID
example: "5491155553333"
message_id:
type: string
description: ID of the message
example: "3EB0794DCEFA60"
label_id:
type: string
description: ID of the label to apply/remove
example: "label_1703123456"
apply:
type: boolean
description: True to apply label, false to remove
example: true
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"success": true,
"message": "Label applied successfully",
"jid": "5491155553333@s.whatsapp.net",
"message_id": "3EB0794DCEFA60",
"label_id": "label_1703123456",
"applied": true,
},
"success": true,
}
/group/create:
post:
tags:
- Group
summary: Create a new WhatsApp group
description: Creates a new WhatsApp group with the specified name and participants.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/CreateGroup"
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"AnnounceVersionID": "1234567890",
"DisappearingTimer": 0,
"GroupCreated": "2023-12-01T10:00:00Z",
"IsAnnounce": false,
"IsEphemeral": false,
"IsLocked": false,
"JID": "120363123456789@g.us",
"Name": "My New Group",
"NameSetAt": "2023-12-01T10:00:00Z",
"NameSetBy": "5491155554444@s.whatsapp.net",
"OwnerJID": "5491155554444@s.whatsapp.net",
"ParticipantVersionID": "1234567890",
"Participants":
[
{
"IsAdmin": true,
"IsSuperAdmin": true,
"JID": "5491155554444@s.whatsapp.net",
},
{
"IsAdmin": false,
"IsSuperAdmin": false,
"JID": "5491155553333@s.whatsapp.net",
},
],
},
"success": true,
}
/group/locked:
post:
tags:
- Group
summary: Set group locked status
description: Configures whether only admins can modify group info (locked) or all participants can modify (unlocked).
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/GroupLocked"
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Group locked setting updated successfully",
},
"success": true,
}
/group/ephemeral:
post:
tags:
- Group
summary: Set disappearing timer for group messages
description: Configures ephemeral/disappearing messages for the group. Messages will automatically disappear after the specified duration.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/GroupEphemeral"
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{ "Details": "Disappearing timer set successfully" },
"success": true,
}
/group/photo/remove:
post:
tags:
- Group
summary: Remove group photo
description: Removes the current photo/image from the specified WhatsApp group.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/RemoveGroupPhoto"
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data": { "Details": "Group photo removed successfully" },
"success": true,
}
/group/list:
get:
tags:
- Group
summary: List subscribed groups
description: Returns complete list of subscribed groups. By default includes participant information. Use ignoreParticipants=true to exclude participants for better performance.
security:
- ApiKeyAuth: []
parameters:
- in: query
name: ignoreParticipants
schema:
type: boolean
required: false
description: Set to 'true' to exclude participants data from response for better performance (default is false)
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Groups":
[
{
"AnnounceVersionID": "1650572126123738",
"DisappearingTimer": 0,
"GroupCreated": "2022-04-21T17:15:26-03:00",
"IsAnnounce": false,
"IsEphemeral": false,
"IsLocked": false,
"JID": "120362023605733675@g.us",
"Name": "Super Group",
"NameSetAt": "2022-04-21T17:15:26-03:00",
"NameSetBy": "5491155554444@s.whatsapp.net",
"OwnerJID": "5491155554444@s.whatsapp.net",
"ParticipantVersionID": "1650234126145738",
"Participants":
[
{
"IsAdmin": true,
"IsSuperAdmin": true,
"JID": "5491155554444@s.whatsapp.net",
},
{
"IsAdmin": false,
"IsSuperAdmin": false,
"JID": "5491155553333@s.whatsapp.net",
},
{
"IsAdmin": false,
"IsSuperAdmin": false,
"JID": "5491155552222@s.whatsapp.net",
},
],
"Topic": "",
"TopicID": "",
"TopicSetAt": "0001-01-01T00:00:00Z",
"TopicSetBy": "",
},
],
},
"success": true,
}
/group/invitelink:
get:
tags:
- Group
summary: Get Group Invite Link
description: Gets the invite link for a group, optionally resetting it to create a new/different one
security:
- ApiKeyAuth: []
parameters:
- in: query
name: groupJID
schema:
type: string
required: true
description: The JID of the group to retrieve information from
- in: query
name: reset
schema:
type: boolean
required: false
description: Whether to revoke the old invite link and generate a new one (default is false)
responses:
200:
description: Successfull response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"InviteLink": "https://chat.whatsapp.com/HffXhYmzzyJGec61oqMXiz",
},
"success": true,
}
/group/info:
get:
tags:
- Group
summary: Gets group information
description: Retrieves information about a specific group
security:
- ApiKeyAuth: []
parameters:
- in: query
name: groupJID
schema:
type: string
required: true
description: The JID of the group to retrieve information from
responses:
200:
description: Successful response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"AnnounceVersionID": "1650572126123738",
"DisappearingTimer": 0,
"GroupCreated": "2022-04-21T17:15:26-03:00",
"IsAnnounce": false,
"IsEphemeral": false,
"IsLocked": false,
"JID": "120362023605733675@g.us",
"Name": "Super Group",
"NameSetAt": "2022-04-21T17:15:26-03:00",
"NameSetBy": "5491155554444@s.whatsapp.net",
"OwnerJID": "5491155554444@s.whatsapp.net",
"ParticipantVersionID": "1650234126145738",
"Participants":
[
{
"IsAdmin": true,
"IsSuperAdmin": true,
"JID": "5491155554444@s.whatsapp.net",
},
{
"IsAdmin": false,
"IsSuperAdmin": false,
"JID": "5491155553333@s.whatsapp.net",
},
{
"IsAdmin": false,
"IsSuperAdmin": false,
"JID": "5491155552222@s.whatsapp.net",
},
],
"Topic": "",
"TopicID": "",
"TopicSetAt": "0001-01-01T00:00:00Z",
"TopicSetBy": "",
},
"success": true,
}
/group/photo:
post:
tags:
- Group
summary: Changes group photo
description: Allows you to change a group photo/image. Returns the Picture ID number
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/GroupPhoto"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"Details": "Group Photo set successfully",
"PictureID": "1222332123",
},
"success": true,
}
/group/leave:
post:
tags:
- Group
summary: Leave a WhatsApp group
description: Removes the authenticated user from the specified group.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/GroupLeave"
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data": { "Details": "Left group successfully" },
"success": true,
}
/group/name:
post:
tags:
- Group
summary: Change group name
description: Updates the name of the specified WhatsApp group.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/GroupName"
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data": { "Details": "Group Name set successfully" },
"success": true,
}
/group/topic:
post:
tags:
- Group
summary: Set group topic/description
description: Updates the topic or description of the specified WhatsApp group.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/GroupTopic"
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data": { "Details": "Group Topic set successfully" },
"success": true,
}
/group/announce:
post:
tags:
- Group
summary: Set group announce mode
description: Enables or disables "announce" mode (admin-only messages) for the specified group.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/GroupAnnounce"
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{ "Details": "Group Announce mode set successfully" },
"success": true,
}
/group/join:
post:
tags:
- Group
summary: Join a WhatsApp group via invite code
description: Joins the WhatsApp group using the given invite code.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/GroupJoin"
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data": { "Details": "Joined group successfully" },
"success": true,
}
/group/inviteinfo:
post:
tags:
- Group
summary: Get information about a group invite code
description: Returns details about a WhatsApp group given an invite code.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/GroupInviteInfo"
responses:
200:
description: Success
content:
application/json:
schema:
example:
{
"code": 200,
"data":
{
"InviteInfo":
{
"GroupName": "Test Group",
"GroupJID": "120363312246943103@g.us",
},
},
"success": true,
}
/group/updateparticipants:
post:
tags:
- Group
summary: Add, Remove, Promote or Demote members in group
description: Manage group members
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/UpdateGroupParticipants"
responses:
200:
description: Response
content:
application/json:
schema:
example:
{
"code": 200,
"data": { "Details": "Added to the group" },
"success": true,
}
/admin/global/stats:
get:
tags:
- Admin Global
summary: Get global system statistics
description: |
Returns comprehensive statistics for global webhook and RabbitMQ systems including:
- Connection status and health
- Active requests and performance metrics
- Configuration details with masked sensitive data
- System uptime and availability
Requires admin token authentication.
security:
- AdminAuth: []
responses:
200:
description: Global system statistics
content:
application/json:
schema:
example:
{
"enabled": true,
"webhook":
{
"enabled": true,
"url": "https://your-global-webhook.com/events",
"events": ["All"],
"timeout": "30s",
"maxRetries": 3,
"maxConcurrency": 50,
"activeRequests": 5,
"availableSlots": 45,
},
"rabbitmq":
{
"enabled": true,
"connected": true,
"url": "amqp://user:***@rabbitmq:5672/",
"exchange": "zuckzapgo.global",
"queue": "zuckzapgo.events",
"events": ["All"],
},
}
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
/admin/global/test:
post:
tags:
- Admin Global
summary: Test global systems connectivity
description: |
Tests connectivity and functionality of global webhook and RabbitMQ systems.
This endpoint performs live connectivity tests and returns detailed results.
Requires admin token authentication.
security:
- AdminAuth: []
responses:
200:
description: Test results for global systems
content:
application/json:
schema:
example:
{
"webhook":
{
"enabled": true,
"success": true,
"error": null,
"responseTime": "150ms",
"httpStatus": 200,
},
"rabbitmq":
{
"enabled": true,
"success": true,
"error": null,
"connectionStatus": "connected",
"exchangeExists": true,
"queueExists": true,
},
}
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
/admin/global/config:
get:
tags:
- Admin Global
summary: Get global system configuration
description: |
Returns current global system configuration and available environment variables.
Sensitive values like passwords and tokens are masked for security.
Requires admin token authentication.
security:
- AdminAuth: []
responses:
200:
description: Global system configuration
content:
application/json:
schema:
example:
{
"webhook":
{
"enabled": true,
"url": "https://your-global-webhook.com/events",
"events": ["All"],
"timeout": "30s",
"retryCount": 3,
"maxConcurrency": 50,
},
"rabbitmq":
{
"enabled": true,
"url": "amqp://user:***@rabbitmq:5672/",
"events": ["All"],
"exchange": "zuckzapgo.global",
"queue": "zuckzapgo.events",
"exchange_type": "topic",
"queue_type": "classic",
"routing_key": "events.#",
"durable": true,
"auto_delete": false,
"delivery_mode": 2,
},
"environment_variables":
{
"GLOBAL_WEBHOOK_ENABLED": "Set to 'true' to enable global webhook",
"GLOBAL_WEBHOOK_URL": "URL for global webhook endpoint",
"GLOBAL_WEBHOOK_EVENTS": "Comma-separated list of events (or 'All')",
"GLOBAL_RABBITMQ_ENABLED": "Set to 'true' to enable global RabbitMQ",
"GLOBAL_RABBITMQ_URL": "RabbitMQ connection URL",
"GLOBAL_RABBITMQ_EVENTS": "Comma-separated list of events (or 'All')",
},
}
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
/admin/global/config/reload:
post:
tags:
- Admin Global
summary: Reload global configuration
description: |
Reloads global webhook and RabbitMQ configurations from environment variables
without restarting the service. This allows for dynamic configuration updates
in production environments.
Requires admin token authentication.
security:
- AdminAuth: []
responses:
200:
description: Configuration reloaded successfully
content:
application/json:
schema:
example:
{
"success": true,
"message": "Global configurations reloaded successfully",
"stats":
{
"enabled": true,
"webhook":
{
"enabled": true,
"url": "https://your-global-webhook.com/events",
"events": ["All"],
},
"rabbitmq":
{
"enabled": true,
"connected": true,
"url": "amqp://user:***@rabbitmq:5672/",
"exchange": "zuckzapgo.global",
"queue": "zuckzapgo.events",
},
},
}
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
/admin/global/s3-retention/stats:
get:
tags:
- Admin Global
summary: Get S3 retention cleanup statistics
operationId: getS3RetentionStats
description: |
Retrieves comprehensive statistics about the S3 retention cleanup system including:
- Objects deleted and bytes reclaimed
- Cycle count and last run information
- Users processed and error counts
- Current configuration settings
The S3 retention system is a GLOBAL worker that periodically cleans expired objects
from S3 storage based on each user's individual `s3_retention_days` configuration.
Requires admin token authentication.
security:
- AdminAuth: []
responses:
200:
description: S3 retention statistics retrieved successfully
content:
application/json:
schema:
example:
{
"code": 200,
"success": true,
"data":
{
"enabled": true,
"running": true,
"currently_running": false,
"last_run_time": "2025-01-15T10:30:00Z",
"last_run_duration": "2m30s",
"objects_deleted": 15420,
"bytes_reclaimed": 1073741824,
"error_count": 2,
"users_processed": 45,
"cycle_count": 24,
"config":
{
"interval": "1h0m0s",
"max_concurrency": 5,
"batch_size": 1000,
"objects_per_cycle": 10000,
},
},
}
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
503:
description: S3 retention manager not initialized or not running
content:
application/json:
schema:
example:
{
"code": 503,
"error": "S3 retention manager not initialized",
"success": false,
}
/admin/global/s3-retention/trigger:
post:
tags:
- Admin Global
summary: Trigger S3 retention cleanup cycle
operationId: triggerS3RetentionCycle
description: |
Manually triggers an S3 retention cleanup cycle. This is useful for:
- Testing the cleanup process
- Forcing immediate cleanup after configuration changes
- Running cleanup outside the scheduled interval
The cycle runs in the background. Use `/admin/global/s3-retention/stats`
to monitor progress.
Requires admin token authentication.
security:
- AdminAuth: []
responses:
200:
description: Cleanup cycle triggered successfully
content:
application/json:
schema:
example:
{
"code": 200,
"success": true,
"message": "S3 retention cycle triggered. Check /admin/global/s3-retention/stats for progress.",
}
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
503:
description: S3 retention manager not initialized or not running
content:
application/json:
schema:
example:
{
"code": 503,
"error": "S3 retention manager is not running",
"success": false,
}
/admin/global/event/test:
post:
tags:
- Admin Global
summary: Send test event through global systems
description: |
Sends a test event through the global webhook and RabbitMQ systems to verify
end-to-end functionality. This is useful for testing integrations and
troubleshooting event delivery.
Requires admin token authentication.
security:
- AdminAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/GlobalTestEvent"
responses:
200:
description: Test event dispatched successfully
content:
application/json:
schema:
example:
{
"success": true,
"message": "Test event dispatched to global systems",
"eventType": "AdminTest",
"userID": "admin-test",
"userToken": "admin-test",
"data":
{
"test": true,
"timestamp": 1705312845,
"message": "This is a test event sent from the admin panel",
},
}
400:
description: Invalid request body
content:
application/json:
schema:
example: { "error": "invalid JSON" }
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
# Monitoring Endpoints
/admin/events/stream:
get:
tags:
- Admin Monitoring
summary: Stream real-time monitoring events (SSE)
description: |
Streams live observability events as Server-Sent Events (SSE) for dashboards, incident tooling, and automation workflows.
**Authentication**
- Send Authorization: Bearer <admin_token> to receive the full firehose.
- Or reuse a short-lived session token issued by POST /admin/events/session via the session query parameter.
**Event Delivery**
- Responses use the SSE framing (`id`, `event`, `data`) with text/event-stream content type.
- The data field carries a JSON-encoded MonitoringEvent.
- SSE clients should keep the TCP connection open and handle periodic heartbeats.
**Filters**
Combine query parameters to scope the stream by user, event type, status, or to replay backlog events using since_id / since_time.
security:
- AdminAuth: []
parameters:
- name: session
in: query
description: Optional monitoring session token issued by POST /admin/events/session. When present, the Authorization header is not required.
required: false
schema:
type: string
example: "session_1720408476123456_abcd1234"
- name: user_id
in: query
description: Filter events to a single user. Required when connecting with a non-admin session token.
required: false
schema:
type: string
example: "acct-01"
- name: event_type
in: query
description: Filter by event type (e.g., message.sent, group.update)
required: false
schema:
type: string
example: "message.sent"
- name: status
in: query
description: Filter by processing status (pending, processing, delivered, failed)
required: false
schema:
type: string
example: "failed"
- name: since_id
in: query
description: Resume the stream after the specified event ID (useful for catch-up on reconnect).
required: false
schema:
type: integer
format: int64
example: 4500
- name: since_time
in: query
description: Only stream events created after this timestamp (RFC3339).
required: false
schema:
type: string
format: date-time
example: "2024-05-12T15:04:05Z"
- name: limit
in: query
description: Maximum number of cached events to send immediately on connect when since_id or since_time is provided (default 50, max 1000).
required: false
schema:
type: integer
minimum: 1
maximum: 1000
default: 50
example: 100
- name: only_failed
in: query
description: Set to true to only stream failed events (ignores other statuses unless explicitly set).
required: false
schema:
type: boolean
example: true
responses:
200:
description: Server-Sent Events stream containing monitoring events
content:
text/event-stream:
schema:
type: string
description: Stream of SSE frames. Each data line contains a JSON encoded MonitoringEvent.
example: |
id: 4521
event: message.sent
data: {"id":4521,"user_id":"acct-01","event_type":"message.sent","status":"delivered","attempts":1,"payload":{"raw":"{\"body\":\"Hello\"}"},"created_at":"2024-05-12T15:05:01Z","updated_at":"2024-05-12T15:05:04Z"}
id: 4522
event: message.failed
data: {"id":4522,"user_id":"acct-02","event_type":"message.failed","status":"failed","attempts":3,"payload":{"raw":"{\"body\":\"Hi\"}"},"created_at":"2024-05-12T15:05:15Z","updated_at":"2024-05-12T15:05:15Z"}
400:
description: Invalid filter or malformed query parameters
content:
application/json:
schema:
example:
{
"error": 'Invalid filter: invalid limit: strconv.Atoi: parsing "abc": invalid syntax',
}
401:
description: Unauthorized - missing or invalid admin/session token
content:
application/json:
schema:
example: { "error": "Unauthorized" }
403:
description: Forbidden - non-admin session must filter by user_id
content:
application/json:
schema:
example: { "error": "User token requires user_id filter" }
503:
description: Monitoring system disabled
content:
application/json:
schema:
example: { "error": "Event monitoring is disabled" }
/admin/events/history:
get:
tags:
- Admin Monitoring
summary: Query monitoring event history
description: |
Returns paginated monitoring events using the same filters available for the live stream. Useful for dashboards that need historical context or to backfill after downtime.
Accepts the same authentication methods as the SSE stream (admin token or monitoring session token).
security:
- AdminAuth: []
parameters:
- name: session
in: query
description: Optional monitoring session token issued by POST /admin/events/session.
required: false
schema:
type: string
example: "session_1720408476123456_abcd1234"
- name: user_id
in: query
description: Filter events to a specific user. Required for non-admin session tokens.
required: false
schema:
type: string
example: "acct-01"
- name: event_type
in: query
description: Filter by event type (e.g., message.sent, message.failed)
required: false
schema:
type: string
example: "message.failed"
- name: status
in: query
description: Filter by processing status (pending, processing, delivered, failed)
required: false
schema:
type: string
example: "failed"
- name: since_id
in: query
description: Return events with IDs greater than the provided value (forward pagination).
required: false
schema:
type: integer
format: int64
example: 4400
- name: since_time
in: query
description: Return events created after this timestamp (RFC3339).
required: false
schema:
type: string
format: date-time
example: "2024-05-01T00:00:00Z"
- name: limit
in: query
description: Maximum number of events to return per page (default 50, max 1000).
required: false
schema:
type: integer
minimum: 1
maximum: 1000
default: 50
example: 100
- name: only_failed
in: query
description: Set to true to only include failed events.
required: false
schema:
type: boolean
example: false
responses:
200:
description: Successfully retrieved monitoring events
content:
application/json:
schema:
type: object
properties:
events:
type: array
items:
$ref: "#/definitions/MonitoringEvent"
has_more:
type: boolean
description: Indicates if more events are available with the current filters.
next_id:
type: integer
format: int64
description: Use as since_id to continue pagination.
count:
type: integer
description: Number of events returned in this response.
example:
events:
- id: 4521
user_id: "acct-01"
event_type: "message.sent"
status: "delivered"
attempts: 1
payload:
raw: '{"body":"Hello"}'
created_at: "2024-05-12T15:05:01Z"
updated_at: "2024-05-12T15:05:04Z"
- id: 4522
user_id: "acct-02"
event_type: "message.failed"
status: "failed"
attempts: 3
payload:
raw: '{"body":"Hi"}'
created_at: "2024-05-12T15:05:15Z"
updated_at: "2024-05-12T15:05:15Z"
has_more: false
next_id: 0
count: 2
400:
description: Invalid filter or malformed query parameters
content:
application/json:
schema:
example:
{
"error": 'Invalid filter: invalid since_id: strconv.ParseInt: parsing "abc": invalid syntax',
}
401:
description: Unauthorized - missing or invalid admin/session token
content:
application/json:
schema:
example: { "error": "Unauthorized" }
503:
description: Monitoring system disabled
content:
application/json:
schema:
example: { "error": "Event monitoring is disabled" }
/admin/events/stats:
get:
tags:
- Admin Monitoring
summary: Retrieve monitoring system statistics
description: |
Provides a snapshot of the monitoring subsystem including hub metrics, notifier status, aggregated event counts, and connected SSE clients.
This endpoint always requires an admin token because it exposes system-wide state.
security:
- AdminAuth: []
responses:
200:
description: Monitoring statistics retrieved successfully
content:
application/json:
schema:
$ref: "#/definitions/MonitoringStatistics"
example:
hub:
connected_clients: 3
total_events_broadcast: 1284
total_events_delivered: 1279
cache_hits: 542
cache_misses: 38
cache_hit_rate: 0.9345
uptime_seconds: 86400
start_time: "2024-05-11T15:00:00Z"
last_broadcast_at: "2024-05-12T15:07:32Z"
notifier:
enabled: true
workers: 4
queue_size: 2
queue_capacity: 1000
queue_utilization: 0.002
events:
by_status:
delivered: 1200
failed: 54
pending: 30
by_type:
message.sent: 890
message.failed: 54
message.received: 320
clients:
- id: "client_1720454855123456_ab12cd34"
session_token: "session_1720454855123456_abcd1234"
user_id: "acct-01"
is_admin: false
connected: true
connected_at: "2024-05-12T15:03:00Z"
last_event_id: 4522
last_heartbeat: "2024-05-12T15:07:31Z"
connection_time: 270.5
filter:
user_id: "acct-01"
event_type: ""
status: ""
since_id: 0
limit: 50
only_failed: false
- id: "client_1720454700123456_ef56ab78"
session_token: "session_1720454700123456_dcba4321"
user_id: ""
is_admin: true
connected: true
connected_at: "2024-05-12T15:00:00Z"
last_event_id: 4522
last_heartbeat: "2024-05-12T15:07:30Z"
connection_time: 450.1
filter: null
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "Unauthorized" }
503:
description: Monitoring system disabled
content:
application/json:
schema:
example: { "error": "Event monitoring is disabled" }
/admin/events/prune:
post:
tags:
- Admin Monitoring
summary: Manually prune persisted monitoring events
description: |
Deletes historic monitoring records older than the configured retention window. Useful for manual cleanup or before changing retention policies.
When MONITORING_STORAGE_ENABLED is false the endpoint returns an error.
security:
- AdminAuth: []
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
retention_hours:
type: integer
description: Optional cutoff in hours. Overrides the configured MONITORING_RETENTION_DAYS value for this request only.
minimum: 1
additionalProperties: false
example:
retention_hours: 48
responses:
200:
description: Prune executed successfully
content:
application/json:
schema:
type: object
properties:
deleted:
type: integer
description: Number of rows removed from monitoring_events.
retention_h:
type: number
description: Retention window applied (hours).
threshold:
type: string
format: date-time
description: Events older than this timestamp were deleted.
required:
- deleted
- retention_h
- threshold
example:
deleted: 124
retention_h: 168
threshold: "2025-10-24T18:00:00Z"
400:
description: Invalid request body (e.g. negative retention)
content:
application/json:
schema:
example: { "error": "Invalid body" }
401:
description: Unauthorized - admin token required
content:
application/json:
schema:
example: { "error": "Unauthorized" }
503:
description: Monitoring system disabled or persistence not enabled
content:
application/json:
schema:
example: { "error": "Event monitoring is disabled" }
/admin/events/session:
post:
tags:
- Admin Monitoring
summary: Issue short-lived monitoring session token
description: |
Creates a temporary session token that can be used to authenticate SSE clients via the session query parameter.
**Typical flow**
1. Admin dashboard calls this endpoint with an optional filter.
2. Use the returned session_token when connecting to /admin/events/stream.
3. Non-admin tokens are limited to the user_id included in the request filter.
Accepts admin tokens or existing admin monitoring sessions for authentication.
security:
- AdminAuth: []
parameters:
- name: session
in: query
description: Optional existing monitoring session token. Allows session renewal without re-supplying the admin token.
required: false
schema:
type: string
example: "session_1720408476123456_abcd1234"
requestBody:
required: false
content:
application/json:
schema:
$ref: "#/definitions/MonitoringSessionTokenRequest"
example:
filters:
user_id: "acct-01"
event_type: "message.failed"
status: ""
since_id: 0
limit: 50
only_failed: true
responses:
200:
description: Session token created successfully
content:
application/json:
schema:
$ref: "#/definitions/MonitoringSessionToken"
example:
session_token: "session_1720455000123456_90ab12cd"
expires_at: "2024-05-12T15:10:00Z"
stream_url: "/api/admin/events/stream?session=session_1720455000123456_90ab12cd&user_id=acct-01&event_type=message.failed"
ttl_seconds: 300
400:
description: Invalid request payload
content:
application/json:
schema:
example:
{
"error": 'Invalid filter: invalid limit: strconv.Atoi: parsing "-1": invalid syntax',
}
401:
description: Unauthorized - missing or invalid admin/session token
content:
application/json:
schema:
example: { "error": "Unauthorized" }
503:
description: Monitoring system disabled
content:
application/json:
schema:
example: { "error": "Event monitoring is disabled" }
# Dead Letter Queue (DLQ) Management Endpoints
/admin/dlq:
get:
tags:
- Admin DLQ
summary: List Dead Letter Queue events
description: |
Retrieves all events stored in the Dead Letter Queue (DLQ) with advanced filtering capabilities.
**Use Cases:**
- Monitor failed events that exceeded MaxAttempts retry limit
- Identify patterns in delivery failures across transports
- Audit event processing issues for specific users or event types
- Filter by time range to investigate incidents
**Pagination:**
- Default limit: 50 events (max: 1000)
- Use offset for pagination through large result sets
**Filters:**
All filters are optional and can be combined for precise queries.
Requires admin token authentication.
security:
- AdminAuth: []
parameters:
- name: transport
in: query
description: Filter by transport name (e.g., "whatsapp", "rabbitmq", "webhook")
required: false
schema:
type: string
example: "whatsapp"
- name: user_id
in: query
description: Filter by user ID who owns the failed event
required: false
schema:
type: string
example: "user123"
- name: event_type
in: query
description: Filter by event type (e.g., "Message", "MessageUpdate", "Receipt")
required: false
schema:
type: string
example: "Message"
- name: from_date
in: query
description: Filter events archived on or after this date (RFC3339 format)
required: false
schema:
type: string
format: date-time
example: "2024-01-01T00:00:00Z"
- name: to_date
in: query
description: Filter events archived on or before this date (RFC3339 format)
required: false
schema:
type: string
format: date-time
example: "2024-01-31T23:59:59Z"
- name: limit
in: query
description: Maximum number of events to return (default 50, max 1000)
required: false
schema:
type: integer
minimum: 1
maximum: 1000
default: 50
example: 100
- name: offset
in: query
description: Number of events to skip for pagination (default 0)
required: false
schema:
type: integer
minimum: 0
default: 0
example: 0
responses:
200:
description: Successfully retrieved DLQ events
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
total:
type: integer
description: Total number of matching events
example: 245
count:
type: integer
description: Number of events in current response
example: 50
events:
type: array
items:
$ref: "#/definitions/DLQEvent"
example:
success: true
total: 245
count: 2
events:
- id: 1234
transport: "whatsapp"
user_id: "user123"
event_type: "Message"
payload: '{"body":"Hello","from":"5521971532700"}'
attempts: 5
last_error: "network timeout after 30s"
failed_at: "2024-01-15T10:30:00Z"
archived_at: "2024-01-15T10:35:00Z"
replay_count: 0
last_replay_at: null
- id: 1235
transport: "rabbitmq"
user_id: "user456"
event_type: "MessageUpdate"
payload: '{"status":"delivered"}'
attempts: 3
last_error: "connection refused"
failed_at: "2024-01-15T11:00:00Z"
archived_at: "2024-01-15T11:05:00Z"
replay_count: 1
last_replay_at: "2024-01-15T12:00:00Z"
400:
description: Invalid query parameters
content:
application/json:
schema:
example: { "error": "invalid date format for from_date" }
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "database error" }
delete:
tags:
- Admin DLQ
summary: Bulk delete DLQ events with filters
description: |
Permanently deletes multiple events from the Dead Letter Queue based on filter criteria.
**⚠️ WARNING: This operation is irreversible!**
**Use Cases:**
- Clean up old failed events after investigation
- Remove events for deactivated users
- Purge events for deprecated transports
- Archive events after manual processing
**Safety Features:**
- Dry-run mode available to preview deletion (use dry_run=true)
- Requires explicit confirmation (use confirm=true)
- Returns count of events that will be/were deleted
- Filters required to prevent accidental mass deletion
**Best Practices:**
1. Always use dry_run=true first to preview
2. Verify the count matches expectations
3. Add specific filters to limit scope
4. Use confirm=true only after verification
Requires admin token authentication.
security:
- AdminAuth: []
parameters:
- name: transport
in: query
description: Filter by transport name
required: false
schema:
type: string
example: "whatsapp"
- name: user_id
in: query
description: Filter by user ID
required: false
schema:
type: string
example: "user123"
- name: event_type
in: query
description: Filter by event type
required: false
schema:
type: string
example: "Message"
- name: from_date
in: query
description: Filter events archived on or after this date
required: false
schema:
type: string
format: date-time
example: "2024-01-01T00:00:00Z"
- name: to_date
in: query
description: Filter events archived on or before this date
required: false
schema:
type: string
format: date-time
example: "2024-01-31T23:59:59Z"
- name: dry_run
in: query
description: Preview deletion without executing (returns count)
required: false
schema:
type: boolean
default: false
example: true
- name: confirm
in: query
description: Explicit confirmation required for actual deletion
required: false
schema:
type: boolean
default: false
example: true
responses:
200:
description: Deletion completed or dry-run preview
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
deleted:
type: integer
description: Number of events deleted (or would be deleted in dry-run)
dry_run:
type: boolean
description: Whether this was a dry-run
message:
type: string
example:
success: true
deleted: 15
dry_run: false
message: "Successfully deleted 15 DLQ events"
400:
description: Invalid parameters or missing confirmation
content:
application/json:
schema:
example:
{ "error": "confirm=true required for actual deletion" }
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "database error" }
/admin/dlq/stats:
get:
tags:
- Admin DLQ
summary: Get Dead Letter Queue statistics
description: |
Retrieves comprehensive statistics about the Dead Letter Queue for monitoring and analysis.
**Provides:**
- Total count of events in DLQ
- Oldest and newest event timestamps
- Breakdown by transport (whatsapp, rabbitmq, webhook, etc.)
- Breakdown by event type (Message, Receipt, etc.)
**Use Cases:**
- Monitor DLQ growth trends
- Identify problematic transports or event types
- Plan cleanup or replay operations
- Generate operational dashboards
Requires admin token authentication.
security:
- AdminAuth: []
responses:
200:
description: Successfully retrieved DLQ statistics
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
stats:
$ref: "#/definitions/DLQStats"
example:
success: true
stats:
total_count: 1247
oldest_event: "2024-01-01T10:00:00Z"
newest_event: "2024-01-15T14:30:00Z"
by_transport:
whatsapp: 856
rabbitmq: 234
webhook: 157
by_event_type:
Message: 923
MessageUpdate: 187
Receipt: 98
Connected: 39
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "database error" }
/admin/dlq/{id}:
get:
tags:
- Admin DLQ
summary: Get specific DLQ event details
description: |
Retrieves complete details for a single event in the Dead Letter Queue by its ID.
**Includes:**
- Full event metadata (transport, user, type, timestamps)
- Complete payload (original event data)
- Failure details (attempts, last error message)
- Replay history (count, last replay time)
**Use Cases:**
- Investigate specific failed events
- Verify payload data before replay
- Analyze error messages for debugging
- Audit event processing history
Requires admin token authentication.
security:
- AdminAuth: []
parameters:
- name: id
in: path
description: Unique DLQ event ID
required: true
schema:
type: integer
format: int64
example: 1234
responses:
200:
description: Successfully retrieved DLQ event
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
event:
$ref: "#/definitions/DLQEvent"
example:
success: true
event:
id: 1234
transport: "whatsapp"
user_id: "user123"
event_type: "Message"
payload: '{"body":"Hello World","from":"5521971532700","to":"5491155553934@s.whatsapp.net","timestamp":1705312845}'
attempts: 5
last_error: "network timeout after 30s - remote server unreachable"
failed_at: "2024-01-15T10:30:00Z"
archived_at: "2024-01-15T10:35:00Z"
replay_count: 0
last_replay_at: null
404:
description: DLQ event not found
content:
application/json:
schema:
example: { "error": "event not found in DLQ" }
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "database error" }
delete:
tags:
- Admin DLQ
summary: Delete specific DLQ event
description: |
Permanently deletes a single event from the Dead Letter Queue by its ID.
**⚠️ WARNING: This operation is irreversible!**
**Use Cases:**
- Remove events after manual processing
- Clean up obsolete or invalid events
- Free up storage space
- Remove sensitive data from DLQ
**Best Practices:**
1. Retrieve event details first (GET /admin/dlq/{id})
2. Verify it's the correct event to delete
3. Consider replay if event should be reprocessed
4. Document reason for deletion for audit trail
Requires admin token authentication.
security:
- AdminAuth: []
parameters:
- name: id
in: path
description: Unique DLQ event ID to delete
required: true
schema:
type: integer
format: int64
example: 1234
responses:
200:
description: Successfully deleted DLQ event
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "DLQ event 1234 deleted successfully"
404:
description: DLQ event not found
content:
application/json:
schema:
example: { "error": "event not found in DLQ" }
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "database error" }
/admin/dlq/replay:
post:
tags:
- Admin DLQ
summary: Replay DLQ event back to buffer
description: |
Re-enqueues a failed event from the Dead Letter Queue back to the persistent buffer for retry.
**Process:**
1. Retrieves event from DLQ by ID
2. Reconstructs original EventEnvelope from archived payload
3. Enqueues to persistent buffer with original transport
4. Updates replay statistics (replay_count, last_replay_at)
5. Optionally removes from DLQ after successful replay
**Use Cases:**
- Retry failed events after fixing underlying issues
- Reprocess events after system recovery
- Manually trigger event delivery
- Test event processing pipeline
**Safety Features:**
- Dry-run mode available to preview replay
- Original event data preserved
- Replay history tracked
- Automatic duplicate detection
**Best Practices:**
1. Verify root cause is fixed before replay
2. Use dry_run=true to preview first
3. Monitor replay success in logs
4. Check event delivery confirmation
Requires admin token authentication.
security:
- AdminAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- id
properties:
id:
type: integer
format: int64
description: DLQ event ID to replay
example: 1234
dry_run:
type: boolean
description: Preview replay without executing
default: false
example: false
remove_after:
type: boolean
description: Remove from DLQ after successful replay
default: false
example: true
responses:
200:
description: Replay completed or dry-run preview
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
event_id:
type: integer
description: ID of the replayed event
transport:
type: string
description: Transport where event was replayed
dry_run:
type: boolean
description: Whether this was a dry-run
replay_count:
type: integer
description: Total number of times this event has been replayed
example:
success: true
message: "Event 1234 replayed successfully to whatsapp transport"
event_id: 1234
transport: "whatsapp"
dry_run: false
replay_count: 1
400:
description: Invalid request body
content:
application/json:
schema:
example: { "error": "id is required" }
404:
description: DLQ event not found
content:
application/json:
schema:
example: { "error": "event not found in DLQ" }
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
500:
description: Internal server error
content:
application/json:
schema:
example: { "error": "failed to replay event" }
/admin/dlq/prune:
post:
tags:
- Admin DLQ
summary: Force event buffer prune
description: |
Triggers the event buffer pruning routine immediately, removing completed and DLQ items that exceed retention policies without waiting for the scheduled interval.
Useful during maintenance windows or before deployments to ensure the buffer is clean. Requires admin authentication.
security:
- AdminAuth: []
responses:
200:
description: Prune triggered successfully
content:
application/json:
schema:
example:
{
"success": true,
"message": "prune triggered successfully",
"pruner_stats":
{
"total_pruned": 1280,
"total_archive_pruned": 430,
"last_prune_time": "2025-10-15T02:10:21Z",
"next_prune_time": "2025-10-15T03:10:21Z",
},
}
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
500:
description: Failed to execute prune
content:
application/json:
schema:
example:
{ "success": false, "error": "failed to execute prune" }
501:
description: Manual prune not supported for current buffer
content:
application/json:
schema:
example:
{
"success": false,
"error": "manual prune not supported for current buffer",
}
/admin/archive:
get:
tags:
- Admin Event Archive
summary: List Event Archive
description: |
Retrieve all archived events including both DLQ (failed after max retries) and successfully delivered events.
**Archive Types:**
- **DLQ Events**: Events that failed after exceeding max retry attempts
- **Success Events**: Events that were successfully delivered
**Use Cases:**
- Monitor complete event delivery history
- Analyze success vs failure rates
- Audit event processing for compliance
- Investigate historical delivery patterns
- Track replay history for events
**Filtering:**
- Filter by status (dlq, success, or all)
- Filter by transport, user, event type
- Date range filtering for temporal analysis
- Combine filters for precise queries
**Pagination:**
- Default limit: 50 events (max: 1000)
- Use offset for pagination through large result sets
Requires admin token authentication.
security:
- AdminAuth: []
parameters:
- name: status
in: query
description: Filter by archive status - 'dlq' for failed events, 'success' for successful events, or empty for all
required: false
schema:
type: string
enum: ["", "dlq", "success"]
example: "success"
- name: transport
in: query
description: Filter by transport name (webhook, rabbitmq, sqs, redis, websocket)
required: false
schema:
type: string
example: "webhook"
- name: user_id
in: query
description: Filter by user ID who owns the archived event
required: false
schema:
type: string
example: "abc123"
- name: event_type
in: query
description: Filter by event type (Message, MessageUpdate, Receipt, Connected, etc.)
required: false
schema:
type: string
example: "Message"
- name: from_date
in: query
description: Filter events archived on or after this date (RFC3339 format)
required: false
schema:
type: string
format: date-time
example: "2024-01-01T00:00:00Z"
- name: to_date
in: query
description: Filter events archived on or before this date (RFC3339 format)
required: false
schema:
type: string
format: date-time
example: "2024-12-31T23:59:59Z"
- name: limit
in: query
description: Maximum number of events to return (default 50, max 1000)
required: false
schema:
type: integer
minimum: 1
maximum: 1000
default: 50
example: 50
- name: offset
in: query
description: Number of events to skip for pagination (default 0)
required: false
schema:
type: integer
minimum: 0
default: 0
example: 0
responses:
200:
description: Successfully retrieved archive events
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
data:
type: array
items:
$ref: "#/definitions/ArchiveEvent"
count:
type: integer
description: Number of events in current response
example: 50
filter:
$ref: "#/definitions/ArchiveFilter"
success:
type: boolean
example: true
example:
code: 200
data:
- id: 12345
status: "success"
transport: "webhook"
user_id: "abc123"
event_type: "Message"
payload: '{"body":"Hello World","from":"5521971532700"}'
attempts: 1
last_error: null
created_at: "2024-10-31T10:30:00Z"
archived_at: "2024-10-31T15:45:00Z"
replay_count: 0
last_replay_at: null
- id: 12346
status: "dlq"
transport: "rabbitmq"
user_id: "xyz789"
event_type: "MessageUpdate"
payload: '{"status":"delivered"}'
attempts: 5
last_error: "connection timeout"
created_at: "2024-10-31T11:00:00Z"
archived_at: "2024-10-31T14:30:00Z"
replay_count: 1
last_replay_at: "2024-10-31T16:00:00Z"
count: 2
filter:
status: ""
transport: ""
user_id: ""
event_type: ""
limit: 50
offset: 0
success: true
400:
description: Invalid query parameters
content:
application/json:
schema:
example:
{
"code": 400,
"error": "invalid status filter",
"success": false,
"details": "status must be 'dlq', 'success', or empty for all",
}
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
500:
description: Internal server error
content:
application/json:
schema:
example:
{
"code": 500,
"error": "failed to retrieve archive events",
"success": false,
}
delete:
tags:
- Admin Event Archive
summary: Bulk delete Event Archive entries
description: |
Permanently remove multiple events from the archive based on filter criteria.
**⚠️ WARNING: This operation is irreversible!**
**Use Cases:**
- Clean up old archived events after analysis
- Remove events for deactivated users
- Purge events for deprecated transports
- Maintain archive size and performance
**Safety Features:**
- Requires at least one filter to prevent accidental mass deletion
- Returns count of deleted and failed events
- Supports bulk deletion with configurable limits
**Best Practices:**
1. Always specify precise filters
2. Use reasonable limit values
3. Monitor deletion results
4. Verify filter matches expectations before deletion
Requires admin token authentication.
security:
- AdminAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/DeleteBulkRequest"
example:
status: "success"
transport: "webhook"
user_id: "abc123"
limit: 100
responses:
200:
description: Bulk deletion completed
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
deleted:
type: integer
description: Number of events successfully deleted
example: 95
failed:
type: integer
description: Number of events that failed to delete
example: 5
total:
type: integer
description: Total number of events processed
example: 100
filter:
$ref: "#/definitions/ArchiveFilter"
success:
type: boolean
example: true
errors:
type: array
items:
type: string
description: Array of error messages for failed deletions (if any)
example:
code: 200
deleted: 95
failed: 5
total: 100
filter:
status: "success"
transport: "webhook"
user_id: "abc123"
limit: 100
success: true
errors:
- "Event ID 12350: database lock timeout"
- "Event ID 12355: event not found"
400:
description: Invalid request or missing required filters
content:
application/json:
schema:
example:
{
"code": 400,
"error": "bulk deletion requires at least one filter (status, transport, user_id, or event_type)",
"success": false,
"details": "To delete all archive events, please use the admin interface with confirmation",
}
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
500:
description: Internal server error
content:
application/json:
schema:
example:
{
"code": 500,
"error": "failed to retrieve archive events",
"success": false,
}
/admin/archive/stats:
get:
tags:
- Admin Event Archive
summary: Get Event Archive statistics
description: |
Retrieve comprehensive statistics about the Event Archive including total count, success/DLQ breakdown, oldest/newest events by status, and distributions by transport and event type.
**Statistics Included:**
- Total archive count (DLQ + Success)
- Success vs DLQ breakdown
- Oldest and newest events by status
- Distribution by transport name
- Distribution by event type
- Distribution by status
- Cross-tabulation by transport and status
**Use Cases:**
- Monitor system health and delivery rates
- Track archive growth over time
- Identify problematic transports or event types
- Generate compliance and audit reports
- Capacity planning for archive storage
Requires admin token authentication.
security:
- AdminAuth: []
responses:
200:
description: Successfully retrieved archive statistics
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
data:
$ref: "#/definitions/ArchiveStats"
success:
type: boolean
example: true
example:
code: 200
data:
total_count: 15234
success_count: 14890
dlq_count: 344
oldest_success: "2024-01-15T10:30:00Z"
newest_success: "2024-10-31T15:45:00Z"
oldest_dlq: "2024-01-16T08:20:00Z"
newest_dlq: "2024-10-31T14:30:00Z"
by_transport:
webhook: 10000
rabbitmq: 5234
by_event_type:
Message: 12000
Receipt: 3234
by_status:
success: 14890
dlq: 344
by_transport_status:
webhook:
success: 9800
dlq: 200
rabbitmq:
success: 5090
dlq: 144
success: true
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
500:
description: Internal server error
content:
application/json:
schema:
example:
{
"code": 500,
"error": "failed to retrieve archive statistics",
"success": false,
}
/admin/archive/{id}:
get:
tags:
- Admin Event Archive
summary: Get specific Event Archive entry
description: |
Retrieve detailed information about a specific archived event (DLQ or Success) by ID.
**Includes:**
- Complete event payload
- Archive status (dlq or success)
- Delivery attempt history
- Replay history
- Timestamps (created, archived, last replay)
- Error information (for DLQ events)
**Use Cases:**
- Investigate specific event delivery
- Debug failed event details
- Audit event processing history
- Verify replay results
- Extract event payload for reprocessing
Requires admin token authentication.
security:
- AdminAuth: []
parameters:
- name: id
in: path
required: true
description: Archive event ID
schema:
type: integer
format: int64
example: 12345
responses:
200:
description: Successfully retrieved archive event
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
data:
$ref: "#/definitions/ArchiveEvent"
success:
type: boolean
example: true
example:
code: 200
data:
id: 12345
status: "success"
transport: "webhook"
user_id: "abc123"
event_type: "Message"
payload: '{"body":"Hello World","from":"5521971532700","to":"5491155553934@s.whatsapp.net","timestamp":1705312845}'
attempts: 1
last_error: null
created_at: "2024-10-31T10:30:00Z"
archived_at: "2024-10-31T15:45:00Z"
replay_count: 0
last_replay_at: null
success: true
400:
description: Invalid event ID
content:
application/json:
schema:
example:
{
"code": 400,
"error": "invalid event ID",
"success": false,
"details": "event ID must be a valid number",
}
404:
description: Archive event not found
content:
application/json:
schema:
example:
{
"code": 404,
"error": "archive event not found",
"success": false,
"details": "No archive event found with the specified ID",
}
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
500:
description: Internal server error
content:
application/json:
schema:
example:
{
"code": 500,
"error": "failed to retrieve archive event",
"success": false,
}
delete:
tags:
- Admin Event Archive
summary: Delete Event Archive entry
description: |
Permanently remove a specific event from the archive by ID.
**⚠️ WARNING: This operation is irreversible!**
**Use Cases:**
- Remove specific problematic event
- Clean up after manual investigation
- Delete sensitive event data
- Remove duplicate entries
**Best Practices:**
1. Verify event ID before deletion
2. Export event data if needed for records
3. Use GET endpoint first to confirm event details
Requires admin token authentication.
security:
- AdminAuth: []
parameters:
- name: id
in: path
required: true
description: Archive event ID to delete
schema:
type: integer
format: int64
example: 12345
responses:
200:
description: Event deleted successfully
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
event_id:
type: integer
format: int64
example: 12345
message:
type: string
example: "Event deleted successfully"
success:
type: boolean
example: true
deleted:
type: integer
example: 1
400:
description: Invalid event ID
content:
application/json:
schema:
example:
{
"code": 400,
"error": "invalid event ID",
"success": false,
"details": "event ID must be a valid number",
}
404:
description: Archive event not found
content:
application/json:
schema:
example:
{
"code": 404,
"error": "archive event not found",
"success": false,
}
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
500:
description: Internal server error
content:
application/json:
schema:
example:
{
"code": 500,
"error": "failed to delete archive event",
"success": false,
}
/admin/archive/replay:
post:
tags:
- Admin Event Archive
summary: Replay Event Archive entries
description: |
Re-enqueue one or more archived events (DLQ or Success) back into the processing pipeline for retry.
**Process:**
1. Retrieves event(s) from archive
2. Reconstructs original EventEnvelope from archived payload
3. Enqueues to persistent buffer with original transport
4. Updates replay statistics (replay_count, last_replay_at)
5. Event remains in archive for audit trail
**Modes:**
- **Single Replay**: Specify event_id to replay one event
- **Bulk Replay**: Use filters to replay multiple events
- **Dry Run**: Preview affected events without replaying
**Use Cases:**
- Retry failed events after fixing underlying issues
- Reprocess successful events for testing
- Re-deliver events after system recovery
- Validate event processing pipeline
**Safety Features:**
- Dry-run mode available to preview replay
- Original event data preserved in archive
- Replay history tracked
- Configurable bulk limits (max 1000)
**Best Practices:**
1. Always use dry_run=true first to preview
2. Verify root cause is fixed before replay
3. Monitor replay success in logs
4. Check event delivery confirmation
Requires admin token authentication.
security:
- AdminAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/ReplayRequest"
examples:
single_replay:
summary: Single event replay
value:
event_id: 12345
dry_run: false
bulk_replay:
summary: Bulk replay with filters
value:
status: "dlq"
transport: "webhook"
limit: 50
dry_run: false
dry_run:
summary: Dry run preview
value:
status: "success"
user_id: "abc123"
dry_run: true
responses:
200:
description: Replay completed or dry-run preview
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
replayed:
type: integer
description: Number of events successfully replayed
example: 45
failed:
type: integer
description: Number of events that failed to replay
example: 5
total:
type: integer
description: Total number of events processed
example: 50
dry_run:
type: boolean
description: Whether this was a dry-run
example: false
event_id:
type: integer
description: Event ID (for single replay)
example: 12345
message:
type: string
example: "Event replayed successfully"
filter:
$ref: "#/definitions/ArchiveFilter"
events:
type: array
items:
$ref: "#/definitions/ArchiveEvent"
description: Events that would be replayed (dry-run only)
success:
type: boolean
example: true
errors:
type: array
items:
type: string
description: Array of error messages for failed replays (if any)
examples:
single_success:
summary: Single replay success
value:
code: 200
event_id: 12345
message: "Event replayed successfully"
success: true
replayed: 1
bulk_success:
summary: Bulk replay success
value:
code: 200
replayed: 45
failed: 5
total: 50
filter:
status: "dlq"
transport: "webhook"
limit: 50
success: true
errors:
- "Event ID 12350: buffer full"
- "Event ID 12355: invalid payload"
dry_run_preview:
summary: Dry run preview
value:
code: 200
dry_run: true
count: 10
filter:
status: "success"
user_id: "abc123"
message: "Dry run - these events would be replayed"
success: true
replayed: 0
events:
- id: 12345
status: "success"
transport: "webhook"
event_type: "Message"
400:
description: Invalid request parameters
content:
application/json:
schema:
example:
{
"code": 400,
"error": "invalid status filter",
"success": false,
"details": "status must be 'dlq', 'success', or empty for all",
}
404:
description: Archive event not found (single replay)
content:
application/json:
schema:
example:
{
"code": 404,
"error": "archive event not found",
"success": false,
}
401:
description: Unauthorized - Admin token required
content:
application/json:
schema:
example: { "error": "unauthorized - admin token required" }
500:
description: Internal server error
content:
application/json:
schema:
example:
{
"code": 500,
"error": "failed to replay archive event",
"success": false,
}
/status/send/text:
post:
tags:
- Status
summary: Send a text status
description: |
Sends a text status to WhatsApp. Text status can include background colors and custom fonts.
**Important Notes:**
- Maximum text length: 650 characters
- Background color and text color must be in ARGB format (decimal)
- Use this ARGB generator: https://argb-int-calculator.netlify.app/
**Available Fonts:**
- 0: SYSTEM
- 1: SYSTEM_TEXT
- 2: FB_SCRIPT
- 6: SYSTEM_BOLD
- 7: MORNINGBREEZE_REGULAR
- 8: CALISTOGA_REGULAR
- 9: EXO2_EXTRABOLD
- 10: COURIERPRIME_BOLD
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/StatusText"
responses:
200:
description: Text status sent successfully
content:
application/json:
schema:
example:
{
"message_id": "3EB06F9067F80BAB89FF",
"timestamp": "2024-01-15T10:30:00Z",
"status": "sent",
"type": "text_status",
}
/status/send/image:
post:
tags:
- Status
summary: Send an image status
description: |
Sends an image status to WhatsApp. Supports both base64 encoded data and HTTP(S) URLs.
**Supported formats:** JPEG, PNG, GIF, WebP
**Caption:** Optional text caption can be added
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/StatusImage"
responses:
200:
description: Image status sent successfully
content:
application/json:
schema:
example:
{
"message_id": "3EB06F9067F80BAB89FF",
"timestamp": "2024-01-15T10:30:00Z",
"status": "sent",
"type": "image_status",
}
/status/send/video:
post:
tags:
- Status
summary: Send a video status
description: |
Sends a video status to WhatsApp. Supports both base64 encoded data and HTTP(S) URLs.
**Supported formats:** MP4, 3GPP
**Codec requirements:** H.264 video codec and AAC audio codec
**Caption:** Optional text caption can be added
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/StatusVideo"
responses:
200:
description: Video status sent successfully
content:
application/json:
schema:
example:
{
"message_id": "3EB06F9067F80BAB89FF",
"timestamp": "2024-01-15T10:30:00Z",
"status": "sent",
"type": "video_status",
}
/status/send/audio:
post:
tags:
- Status
summary: Send an audio status
description: |
Sends an audio status to WhatsApp. Supports both base64 encoded data and HTTP(S) URLs.
**Supported formats:** OGG with Opus codec, MP3, M4A
**PTT option:** Set `ptt: true` to send as voice note
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/StatusAudio"
responses:
200:
description: Audio status sent successfully
content:
application/json:
schema:
example:
{
"message_id": "3EB06F9067F80BAB89FF",
"timestamp": "2024-01-15T10:30:00Z",
"status": "sent",
"type": "audio_status",
"ptt": false,
}
/call/reject/send:
post:
tags:
- Call
summary: Reject a call and send custom message
description: Rejects an incoming call with a specific rejection type and optionally sends a custom message to the caller
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/CallRejectRequest"
responses:
200:
description: Call rejected successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
call_id:
type: string
example: "call_12345_abcd"
call_from:
type: string
example: "5521971532700@s.whatsapp.net"
reject_type:
type: string
example: "busy"
action:
type: string
example: "rejected"
message_sent:
type: boolean
example: true
example:
success: true
call_id: "call_12345_abcd"
call_from: "5521971532700@s.whatsapp.net"
reject_type: "busy"
action: "rejected"
message_sent: true
400:
description: Bad request - Invalid input or missing required fields
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
missing_fields:
value:
error: "call_id and call_from are required"
invalid_reject_type:
value:
error: "invalid reject_type, must be: busy, declined, or unavailable"
invalid_jid:
value:
error: "invalid call_from JID: invalid format"
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
client_not_initialized:
value:
error: "client not initialized"
client_not_connected:
value:
error: "client not connected"
call_reject_failed:
value:
error: "failed to reject call: network error"
/community/link:
post:
tags:
- Community
summary: Link group to community
description: Links a child group to a parent community. The authenticated user must be an admin of both the parent community and the child group to perform this operation.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/LinkGroupRequest"
responses:
200:
description: Group successfully linked to community
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "Group linked to community successfully"
parent_jid:
type: string
example: "120363025246487852@newsletter"
child_jid:
type: string
example: "120363312246943103@g.us"
400:
description: Bad request - Invalid JID format or missing required fields
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "invalid parent JID format"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "no session"
/community/unlink:
post:
tags:
- Community
summary: Unlink group from community
description: Unlinks a child group from a parent community. The authenticated user must be an admin of the parent community to perform this operation.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/UnlinkGroupRequest"
responses:
200:
description: Group successfully unlinked from community
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "Group unlinked from community successfully"
parent_jid:
type: string
example: "120363025246487852@newsletter"
child_jid:
type: string
example: "120363312246943103@g.us"
400:
description: Bad request - Invalid JID format or missing required fields
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "invalid parent JID format"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
/community/linked-groups:
post:
tags:
- Community
summary: Get linked groups in community
description: Retrieves all groups (sub-groups) linked to a parent community. Returns an array of group JIDs that are currently linked to the specified community.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/LinkedGroupsRequest"
responses:
200:
description: Linked groups retrieved successfully
content:
application/json:
schema:
$ref: "#/definitions/LinkedGroupsResponse"
400:
description: Bad request - Invalid JID format or missing required fields
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "invalid community JID format"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
/community/sub-groups:
post:
tags:
- Community
summary: Get sub-groups in community
description: Alias for /community/linked-groups. Retrieves all sub-groups linked to a parent community. Returns the same result as linked-groups endpoint.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/LinkedGroupsRequest"
responses:
200:
description: Sub-groups retrieved successfully
content:
application/json:
schema:
$ref: "#/definitions/LinkedGroupsResponse"
400:
description: Bad request - Invalid JID format or missing required fields
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "invalid community JID format"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
/community/requests:
post:
tags:
- Community
summary: Get pending join requests
description: Retrieves a list of participants who have requested to join the specified community group. Only available for communities/groups that require approval to join.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/GroupRequestsRequest"
responses:
200:
description: Join requests retrieved successfully
content:
application/json:
schema:
$ref: "#/definitions/GroupRequestsResponse"
400:
description: Bad request - Invalid JID format or missing required fields
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "invalid group JID format"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
/community/requests/update:
post:
tags:
- Community
summary: Approve or reject join requests
description: Approves or rejects pending join requests for a community group. The authenticated user must be an admin of the group to perform this operation. Supports bulk approval/rejection of multiple requests.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/UpdateGroupRequestsRequest"
responses:
200:
description: Join requests processed successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "Successfully approved 3 join request(s)"
group_jid:
type: string
example: "120363312246943103@g.us"
action:
type: string
enum: [approve, reject]
example: "approve"
processed_count:
type: integer
example: 3
participants:
type: array
items:
type: string
example:
[
"5491155553934@s.whatsapp.net",
"5521971532700@s.whatsapp.net",
]
400:
description: Bad request - Invalid JID format, missing required fields, or invalid action
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
invalid_group_jid:
value:
error: "invalid group JID format"
invalid_action:
value:
error: "invalid action. Use 'approve' or 'reject'"
missing_participants:
value:
error: "participants list is required"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
/community/create:
post:
tags:
- Community
summary: Create new community
description: Creates a new WhatsApp community with an initial set of linked groups. The community name is required, and you can optionally provide a list of existing group JIDs to link immediately upon creation. The authenticated user becomes the community admin.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/CreateCommunityRequest"
responses:
200:
description: Community created successfully
content:
application/json:
schema:
$ref: "#/definitions/CreateCommunityResponse"
400:
description: Bad request - Invalid input or missing required fields
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
missing_name:
value:
error: "community name is required"
invalid_group_jid:
value:
error: "invalid group JID format in initial_groups"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "failed to create community"
/community/announcement:
post:
tags:
- Community
summary: Send community announcement
description: Sends an announcement message to all members of a community. The message will be delivered to all linked groups within the community. Only community admins can send announcements.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/CommunityAnnouncementRequest"
responses:
200:
description: Announcement sent successfully
content:
application/json:
schema:
$ref: "#/definitions/CommunityAnnouncementResponse"
400:
description: Bad request - Invalid JID format or missing required fields
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
missing_community_jid:
value:
error: "community JID is required"
missing_message:
value:
error: "message text is required"
invalid_jid:
value:
error: "invalid community JID format"
401:
description: Unauthorized - Valid user token required
403:
description: Forbidden - User is not a community admin
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "only community admins can send announcements"
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "failed to send announcement"
/business/resolve-link:
post:
tags:
- Business
summary: Resolve business message link
description: Resolves a WhatsApp Business message link to retrieve detailed information about the business, including business name, category, description, website, email, address, and verification status. This is useful for validating business links before interacting with them.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/ResolveBusinessLinkRequest"
responses:
200:
description: Business link resolved successfully
content:
application/json:
schema:
$ref: "#/definitions/BusinessLinkInfo"
400:
description: Bad request - Invalid or missing business link
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "business link is required"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "failed to resolve business link"
/business/contact-qr:
post:
tags:
- Business
summary: Get contact QR link
description: Generates a QR code link for a WhatsApp contact. The QR code can be used to quickly add the contact or start a conversation. Optionally, you can revoke existing QR codes before generating a new one.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/ContactQRRequest"
responses:
200:
description: Contact QR link generated successfully
content:
application/json:
schema:
$ref: "#/definitions/ContactQRResponse"
400:
description: Bad request - Invalid or missing phone number
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "phone number is required"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "failed to generate QR link"
/business/bots:
get:
tags:
- Business
summary: Get available bots list
description: Retrieves a list of all available WhatsApp Business bots that the authenticated user can interact with. Returns bot IDs, names, and basic information about each bot.
security:
- ApiKeyAuth: []
responses:
200:
description: Bot list retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
bots:
type: array
items:
$ref: "#/definitions/BotInfo"
count:
type: integer
example: 5
description: Total number of available bots
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "failed to retrieve bots list"
/business/bot-profiles:
post:
tags:
- Business
summary: Get detailed bot profiles
description: Retrieves detailed profile information for one or more WhatsApp Business bots. Returns comprehensive information including bot capabilities, commands, description, avatar, and configuration. Useful for displaying bot information in a user interface or for bot discovery.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/BotProfilesRequest"
responses:
200:
description: Bot profiles retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
profiles:
type: array
items:
$ref: "#/definitions/BotProfileInfo"
count:
type: integer
example: 2
description: Number of bot profiles returned
400:
description: Bad request - Invalid or missing bot JIDs
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "bot JIDs are required"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "failed to retrieve bot profiles"
/business/order/send:
post:
tags:
- Business
summary: Send order message to business
description: Sends an order message to a WhatsApp Business account. The order message includes product details, quantities, prices, and can include multiple items. This is used for e-commerce and shopping interactions with business accounts. The business must support order messages.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/SendOrderRequest"
responses:
200:
description: Order message sent successfully
content:
application/json:
schema:
$ref: "#/definitions/OrderResponse"
400:
description: Bad request - Invalid input, missing required fields, or invalid order items
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
missing_phone:
value:
error: "phone number is required"
missing_items:
value:
error: "order must contain at least one item"
invalid_item:
value:
error: "invalid order item format"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "failed to send order message"
/device/users:
post:
tags:
- Device
summary: Get user devices
description: Retrieves device information for one or more WhatsApp user JIDs. Returns details about all devices associated with each user, including device IDs and platform types (CHROME, SAFARI, DESKTOP, etc.). Useful for understanding which devices a user is using WhatsApp on.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/UserDevicesRequest"
responses:
200:
description: User devices retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
devices:
type: array
items:
$ref: "#/definitions/DeviceInfo"
description: Array of device information for all requested users
total_users:
type: integer
example: 2
description: Number of users queried
total_devices:
type: integer
example: 4
description: Total number of devices found
400:
description: Bad request - Invalid or missing user JIDs
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "user JIDs are required"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "failed to retrieve user devices"
/device/users/context:
post:
tags:
- Device
summary: Get user devices with timeout context
description: Retrieves device information for one or more WhatsApp user JIDs with a timeout context. This is similar to /device/users but includes timeout handling for better control over long-running requests. Returns details about all devices associated with each user.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/UserDevicesRequest"
responses:
200:
description: User devices retrieved successfully with timeout context
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
devices:
type: array
items:
$ref: "#/definitions/DeviceInfo"
description: Array of device information for all requested users
total_users:
type: integer
example: 2
description: Number of users queried
total_devices:
type: integer
example: 4
description: Total number of devices found
timeout_used:
type: boolean
example: false
description: Whether the request timed out
400:
description: Bad request - Invalid or missing user JIDs
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "user JIDs are required"
401:
description: Unauthorized - Valid user token required
408:
description: Request timeout - Operation took too long
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "request timeout while retrieving devices"
500:
description: Internal server error
/device/linked:
get:
tags:
- Device
summary: Get linked devices for current user
description: Retrieves a list of all devices linked to the authenticated user's WhatsApp account. Returns information about each linked device including device ID, platform type, and connection status. This shows the multi-device configuration for the current session.
security:
- ApiKeyAuth: []
responses:
200:
description: Linked devices retrieved successfully
content:
application/json:
schema:
$ref: "#/definitions/LinkedDevicesResponse"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
no_session:
value:
error: "no session"
not_connected:
value:
error: "client not connected"
retrieval_failed:
value:
error: "failed to retrieve linked devices"
/device/platform:
post:
tags:
- Device
summary: Get device platform name
description: Retrieves the platform name (CHROME, SAFARI, FIREFOX, EDGE, DESKTOP, etc.) for a specific device based on its device ID. Useful for displaying device information in a user-friendly format or for device-specific logic.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/DevicePlatformRequest"
responses:
200:
description: Device platform retrieved successfully
content:
application/json:
schema:
$ref: "#/definitions/DevicePlatformResponse"
400:
description: Bad request - Invalid or missing device ID
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "device ID is required"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "failed to retrieve device platform"
/privacy/settings:
get:
tags:
- Privacy
summary: Get current privacy settings
description: Retrieves all current privacy settings for the authenticated user including group_add, last_seen, status, profile, read_receipts, online, and call_add settings. Each setting shows who can see or interact with that feature (all, contacts, contact_blacklist, or none).
security:
- ApiKeyAuth: []
responses:
200:
description: Privacy settings retrieved successfully
content:
application/json:
schema:
$ref: "#/definitions/PrivacySettingsResponse"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "no session"
post:
tags:
- Privacy
summary: Update a specific privacy setting
description: Updates a specific privacy setting for the authenticated user. You can configure who can see your last seen, profile photo, status, who can add you to groups or calls, whether to send read receipts, and online status visibility. Each setting can be set to 'all' (everyone), 'contacts' (contacts only), 'contact_blacklist' (contacts except), or 'none' (nobody).
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/SetPrivacySettingRequest"
responses:
200:
description: Privacy setting updated successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "Privacy setting last_seen updated to contacts"
setting:
type: string
example: "last_seen"
value:
type: string
example: "contacts"
400:
description: Bad request - Invalid setting type or value
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
missing_fields:
value:
error: "missing setting or value in payload"
invalid_setting:
value:
error: "invalid setting type"
invalid_value:
value:
error: "invalid privacy value"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "failed to update privacy setting"
/privacy/disappearing-timer:
post:
tags:
- Privacy
summary: Set default disappearing message timer
description: Sets the default disappearing message timer for new chats. Messages will automatically disappear after the specified duration. Valid options are 24h (24 hours), 7d (7 days), 90d (90 days), or 'off' to disable. This setting applies to new chats created after this configuration.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/DisappearingTimerRequest"
responses:
200:
description: Default disappearing timer set successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "Default disappearing timer set to 24h"
timer:
type: string
example: "24h"
400:
description: Bad request - Invalid timer value
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
missing_timer:
value:
error: "missing timer in payload"
invalid_timer:
value:
error: "invalid timer value. Use: 24h, 7d, 90d, or off"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "failed to set disappearing timer"
/privacy/blocklist:
get:
tags:
- Privacy
summary: Get blocklist of blocked contacts
description: Retrieves the complete list of all contacts that have been blocked by the authenticated user. Returns an array of JIDs for all blocked contacts along with the total count.
security:
- ApiKeyAuth: []
responses:
200:
description: Blocklist retrieved successfully
content:
application/json:
schema:
$ref: "#/definitions/BlocklistResponse"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "failed to get blocklist"
post:
tags:
- Privacy
summary: Block or unblock contacts
description: Blocks or unblocks one or more contacts. When blocking a contact, they will not be able to call you or send you messages. When unblocking, normal communication is restored. Supports bulk operations for multiple contacts at once.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/UpdateBlocklistRequest"
responses:
200:
description: Blocklist updated successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "Successfully blocked 2 contact(s)"
action:
type: string
enum: [block, unblock]
example: "block"
users:
type: array
items:
type: string
example: ["5491155553934", "5521971532700"]
400:
description: Bad request - Invalid action or JID format
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
missing_fields:
value:
error: "missing action or users in payload"
invalid_action:
value:
error: "invalid action. Use: block or unblock"
invalid_jid:
value:
error: "invalid JID: 5491155553934"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "failed to update blocklist"
/privacy/status:
get:
tags:
- Privacy
summary: Get status privacy setting
description: Retrieves the current status privacy configuration for the authenticated user. This shows who can see your WhatsApp status updates. Possible values are 'all' (everyone), 'contacts' (contacts only), 'contact_blacklist' (contacts except specific ones), or 'none' (nobody).
security:
- ApiKeyAuth: []
responses:
200:
description: Status privacy setting retrieved successfully
content:
application/json:
schema:
$ref: "#/definitions/StatusPrivacyResponse"
401:
description: Unauthorized - Valid user token required
500:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "no session"
definitions:
ContextInfo:
type: object
description: "Optional context info for replies. When replying to a message, provide stanzaID, participant, and optionally quotedMessage for full reply preview support on all devices."
properties:
stanzaID:
type: string
example: "3EB06F9067F80BAB89FF"
description: "Message ID to reply to (required for replies)"
participant:
type: string
example: "5521971532700@s.whatsapp.net"
description: "JID of original message sender (required for replies)"
quotedMessage:
$ref: "#/definitions/QuotedMessage"
isForwarded:
type: boolean
example: true
description: "Set to true to mark the message as forwarded. This is the preferred method for forwarding messages."
mentionedJID:
type: array
items:
type: string
example:
["5521971532700@s.whatsapp.net", "5491155553934@s.whatsapp.net"]
description: "Array of JIDs to mention in the message. Use full WhatsApp JID format (number@s.whatsapp.net)."
mentionAll:
type: boolean
example: true
description: "Set to true to mention all group members"
QuotedMessage:
type: object
description: "The original message content being replied to. Providing this ensures proper reply preview display on all devices, especially iPhone. Without this field, replies will work but may not show the original message preview correctly on iOS devices."
properties:
conversation:
type: string
example: "Hello, how are you?"
description: "The text content of the original message being replied to. Use this for simple text messages."
example:
conversation: "This is the original message text being replied to"
DLQEvent:
type: object
description: "Represents an event stored in the Dead Letter Queue after exceeding MaxAttempts retry limit"
properties:
id:
type: integer
format: int64
description: "Unique identifier for the DLQ event"
example: 1234
transport:
type: string
description: "Transport where the event failed (whatsapp, rabbitmq, webhook, etc.)"
example: "whatsapp"
user_id:
type: string
description: "ID of the user who owns this failed event"
example: "user123"
event_type:
type: string
description: "Type of the failed event (Message, MessageUpdate, Receipt, Connected, etc.)"
example: "Message"
payload:
type: string
description: "JSON string containing the complete original event data"
example: '{"body":"Hello World","from":"5521971532700","to":"5491155553934@s.whatsapp.net","timestamp":1705312845}'
attempts:
type: integer
description: "Number of delivery attempts made before archiving to DLQ"
example: 5
last_error:
type: string
description: "Error message from the final failed delivery attempt"
example: "network timeout after 30s - remote server unreachable"
failed_at:
type: string
format: date-time
description: "Timestamp when the event finally failed (RFC3339 format)"
example: "2024-01-15T10:30:00Z"
archived_at:
type: string
format: date-time
description: "Timestamp when the event was archived to DLQ (RFC3339 format)"
example: "2024-01-15T10:35:00Z"
replay_count:
type: integer
description: "Number of times this event has been replayed from DLQ"
example: 0
last_replay_at:
type: string
format: date-time
nullable: true
description: "Timestamp of the most recent replay attempt (null if never replayed)"
example: null
DLQStats:
type: object
description: "Statistical information about events in the Dead Letter Queue"
properties:
total_count:
type: integer
format: int64
description: "Total number of events currently in the DLQ"
example: 1247
oldest_event:
type: string
format: date-time
nullable: true
description: "Timestamp of the oldest event in DLQ (null if DLQ is empty)"
example: "2024-01-01T10:00:00Z"
newest_event:
type: string
format: date-time
nullable: true
description: "Timestamp of the newest event in DLQ (null if DLQ is empty)"
example: "2024-01-15T14:30:00Z"
by_transport:
type: object
description: "Breakdown of event counts by transport name"
additionalProperties:
type: integer
example:
whatsapp: 856
rabbitmq: 234
webhook: 157
by_event_type:
type: object
description: "Breakdown of event counts by event type"
additionalProperties:
type: integer
example:
Message: 923
MessageUpdate: 187
Receipt: 98
Connected: 39
ArchiveEvent:
type: object
description: "Represents an archived event (DLQ or Successfully Delivered)"
properties:
id:
type: integer
format: int64
description: "Unique identifier for the archived event"
example: 12345
status:
type: string
enum: ["dlq", "success"]
description: "Archive status - 'dlq' for failed events after max retries, 'success' for successfully delivered events"
example: "success"
transport:
type: string
description: "Transport name where the event was processed (webhook, rabbitmq, sqs, redis, websocket)"
example: "webhook"
user_id:
type: string
description: "ID of the user who owns this archived event"
example: "abc123"
event_type:
type: string
description: "Type of the archived event (Message, MessageUpdate, Receipt, Connected, etc.)"
example: "Message"
payload:
type: string
description: "JSON string containing the complete original event data"
example: '{"body":"Hello World","from":"5521971532700","to":"5491155553934@s.whatsapp.net","timestamp":1705312845}'
attempts:
type: integer
description: "Number of delivery attempts made before archiving"
example: 1
last_error:
type: string
nullable: true
description: "Error message from the final failed delivery attempt (null for success status)"
example: null
created_at:
type: string
format: date-time
description: "Timestamp when the event was originally created (RFC3339 format)"
example: "2024-10-31T10:30:00Z"
archived_at:
type: string
format: date-time
description: "Timestamp when the event was archived (RFC3339 format)"
example: "2024-10-31T15:45:00Z"
replay_count:
type: integer
description: "Number of times this event has been replayed from archive"
example: 0
last_replay_at:
type: string
format: date-time
nullable: true
description: "Timestamp of the most recent replay attempt (null if never replayed)"
example: null
ArchiveFilter:
type: object
description: "Filter parameters for querying archived events"
properties:
status:
type: string
enum: ["", "dlq", "success"]
description: "Filter by status - 'dlq' for failed events, 'success' for successful events, empty for all"
example: "success"
transport:
type: string
description: "Filter by transport name"
example: "webhook"
user_id:
type: string
description: "Filter by user ID"
example: "abc123"
event_type:
type: string
description: "Filter by event type"
example: "Message"
from_date:
type: string
format: date-time
description: "Filter events archived from this date onwards (RFC3339 format)"
example: "2024-01-01T00:00:00Z"
to_date:
type: string
format: date-time
description: "Filter events archived up to this date (RFC3339 format)"
example: "2024-12-31T23:59:59Z"
limit:
type: integer
minimum: 1
maximum: 1000
default: 50
description: "Maximum number of events to return"
example: 50
offset:
type: integer
minimum: 0
default: 0
description: "Number of events to skip for pagination"
example: 0
ArchiveStats:
type: object
description: "Comprehensive statistics about the Event Archive"
properties:
total_count:
type: integer
format: int64
description: "Total number of archived events (DLQ + Success)"
example: 15234
success_count:
type: integer
format: int64
description: "Number of successfully delivered archived events"
example: 14890
dlq_count:
type: integer
format: int64
description: "Number of DLQ (failed) archived events"
example: 344
oldest_success:
type: string
format: date-time
nullable: true
description: "Timestamp of the oldest success event (null if no success events)"
example: "2024-01-15T10:30:00Z"
newest_success:
type: string
format: date-time
nullable: true
description: "Timestamp of the newest success event (null if no success events)"
example: "2024-10-31T15:45:00Z"
oldest_dlq:
type: string
format: date-time
nullable: true
description: "Timestamp of the oldest DLQ event (null if no DLQ events)"
example: "2024-01-16T08:20:00Z"
newest_dlq:
type: string
format: date-time
nullable: true
description: "Timestamp of the newest DLQ event (null if no DLQ events)"
example: "2024-10-31T14:30:00Z"
by_transport:
type: object
description: "Breakdown of event counts by transport name"
additionalProperties:
type: integer
example:
webhook: 10000
rabbitmq: 5234
by_event_type:
type: object
description: "Breakdown of event counts by event type"
additionalProperties:
type: integer
example:
Message: 12000
Receipt: 3234
by_status:
type: object
description: "Breakdown of event counts by status"
additionalProperties:
type: integer
example:
success: 14890
dlq: 344
by_transport_status:
type: object
description: "Breakdown of event counts by transport and status"
additionalProperties:
type: object
additionalProperties:
type: integer
example:
webhook:
success: 9800
dlq: 200
rabbitmq:
success: 5090
dlq: 144
MonitoringEvent:
type: object
description: "Real-time monitoring event emitted by the observability pipeline"
properties:
id:
type: integer
format: int64
description: "Sequential identifier of the monitoring event"
example: 4521
user_id:
type: string
description: "User associated with the event (empty for system-wide events)"
example: "acct-01"
event_type:
type: string
description: "Event topic emitted by the monitoring subsystem"
example: "message.sent"
payload:
type: object
description: "Structured payload captured for the event. Raw data is nested under the raw field when stored in SQL."
additionalProperties: true
example:
raw: '{"body":"Hello"}'
status:
type: string
description: "Processing status of the event"
enum: [pending, processing, delivered, failed]
example: "delivered"
attempts:
type: integer
description: "Number of delivery attempts performed for this event"
example: 1
created_at:
type: string
format: date-time
description: "Timestamp when the event was created"
example: "2024-05-12T15:05:01Z"
updated_at:
type: string
format: date-time
description: "Timestamp of the most recent update to the event"
example: "2024-05-12T15:05:04Z"
MonitoringEventFilter:
type: object
description: "Filter parameters available for monitoring streams and history queries"
properties:
user_id:
type: string
description: "Return events for a specific user ID"
example: "acct-01"
event_type:
type: string
description: "Return only events that match the provided event type"
example: "message.failed"
status:
type: string
description: "Filter events by processing status"
enum: [pending, processing, delivered, failed]
example: "failed"
since_id:
type: integer
format: int64
description: "Return events with ID greater than this value"
example: 4400
since_time:
type: string
format: date-time
description: "Return events created after this timestamp (RFC3339)"
example: "2024-05-01T00:00:00Z"
limit:
type: integer
minimum: 1
maximum: 1000
default: 50
description: "Maximum number of events to return when querying history or issuing a session token"
example: 50
only_failed:
type: boolean
description: "Restrict results to events whose status is failed"
example: false
MonitoringClientInfo:
type: object
description: "Metadata about a connected SSE monitoring client"
properties:
id:
type: string
description: "Unique identifier assigned to the SSE client connection"
example: "client_1720454855123456_ab12cd34"
session_token:
type: string
description: "Session token used by the client"
example: "session_1720454855123456_abcd1234"
user_id:
type: string
description: "User scope applied to the client (blank when connected as admin)"
example: "acct-01"
is_admin:
type: boolean
description: "Indicates whether the connection has admin privileges"
example: false
connected:
type: boolean
description: "Whether the client is actively connected"
example: true
connected_at:
type: string
format: date-time
description: "Connection timestamp"
example: "2024-05-12T15:03:00Z"
last_event_id:
type: integer
format: int64
description: "Identifier of the last event delivered to the client"
example: 4522
last_heartbeat:
type: string
format: date-time
description: "Timestamp of the most recent heartbeat received from the client"
example: "2024-05-12T15:07:31Z"
connection_time:
type: number
format: float
description: "Duration in seconds since the client connected"
example: 270.5
filter:
$ref: "#/definitions/MonitoringEventFilter"
nullable: true
description: "Filters currently applied to the client stream"
MonitoringHubStats:
type: object
description: "Runtime metrics captured by the monitoring SSE hub"
properties:
connected_clients:
type: integer
description: "Number of clients currently connected to the hub"
example: 3
total_events_broadcast:
type: integer
format: int64
description: "Total events broadcast to clients since startup"
example: 1284
total_events_delivered:
type: integer
format: int64
description: "Total number of event deliveries performed"
example: 1279
cache_hits:
type: integer
format: int64
description: "Number of cache hits when resolving queries"
example: 542
cache_misses:
type: integer
format: int64
description: "Number of cache misses when resolving queries"
example: 38
cache_hit_rate:
type: number
format: float
description: "Ratio of cache hits versus total lookups (0.0 - 1.0)"
example: 0.9345
uptime_seconds:
type: integer
format: int64
description: "Number of seconds the monitoring hub has been running"
example: 86400
start_time:
type: string
format: date-time
description: "Timestamp when the monitoring hub started"
example: "2024-05-11T15:00:00Z"
last_broadcast_at:
type: string
format: date-time
nullable: true
description: "Timestamp of the most recent broadcast"
example: "2024-05-12T15:07:32Z"
MonitoringNotifierStats:
type: object
description: "Operational metrics for the monitoring notifier workers"
properties:
enabled:
type: boolean
description: "Indicates if the notifier is currently dispatching events"
example: true
workers:
type: integer
description: "Number of concurrent notifier workers"
example: 4
queue_size:
type: integer
description: "Current number of events waiting in the notifier queue"
example: 2
queue_capacity:
type: integer
description: "Total capacity of the notifier queue"
example: 1000
queue_utilization:
type: number
format: float
description: "Queue utilization ratio (0.0 - 1.0)"
example: 0.002
MonitoringStatistics:
type: object
description: "Aggregated telemetry exposed by the monitoring endpoints"
properties:
hub:
$ref: "#/definitions/MonitoringHubStats"
notifier:
$ref: "#/definitions/MonitoringNotifierStats"
events:
type: object
properties:
by_status:
type: object
description: "Aggregated count of events by processing status"
additionalProperties:
type: integer
example:
delivered: 1200
failed: 54
by_type:
type: object
description: "Aggregated count of events by event type"
additionalProperties:
type: integer
example:
message.sent: 890
message.failed: 54
clients:
type: array
description: "Snapshot of currently connected SSE clients"
items:
$ref: "#/definitions/MonitoringClientInfo"
MonitoringSessionTokenRequest:
type: object
description: "Payload for requesting a monitoring session token"
properties:
filters:
$ref: "#/definitions/MonitoringEventFilter"
description: "Optional filters to bake into the issued session token"
MonitoringSessionToken:
type: object
description: "Response returned when issuing a monitoring session token"
properties:
session_token:
type: string
description: "Short-lived token to authenticate SSE connections"
example: "session_1720455000123456_90ab12cd"
expires_at:
type: string
format: date-time
description: "Timestamp when the session token expires"
example: "2024-05-12T15:10:00Z"
stream_url:
type: string
description: "Pre-built stream URL including the session token and any requested filters"
example: "/api/admin/events/stream?session=session_1720455000123456_90ab12cd&user_id=acct-01"
ttl_seconds:
type: integer
description: "Time-to-live of the session token, in seconds"
example: 300
ReplayRequest:
type: object
description: "Request parameters for replaying archived events"
properties:
event_id:
type: integer
format: int64
description: "Single event ID to replay (for single event replay)"
example: 12345
dry_run:
type: boolean
default: false
description: "Preview mode - returns events that would be replayed without actually replaying them"
example: false
status:
type: string
enum: ["", "dlq", "success"]
description: "Filter by status for bulk replay"
example: "dlq"
transport:
type: string
description: "Filter by transport for bulk replay"
example: "webhook"
user_id:
type: string
description: "Filter by user ID for bulk replay"
example: "abc123"
event_type:
type: string
description: "Filter by event type for bulk replay"
example: "Message"
limit:
type: integer
minimum: 1
maximum: 1000
default: 50
description: "Maximum number of events to replay in bulk operation"
example: 50
DeleteBulkRequest:
type: object
description: "Request parameters for bulk deletion of archived events"
required:
- status
properties:
status:
type: string
enum: ["dlq", "success"]
description: "Filter by status for bulk deletion (required to prevent accidental delete all)"
example: "dlq"
transport:
type: string
description: "Filter by transport for bulk deletion"
example: "webhook"
user_id:
type: string
description: "Filter by user ID for bulk deletion"
example: "abc123"
event_type:
type: string
description: "Filter by event type for bulk deletion"
example: "Message"
limit:
type: integer
minimum: 1
maximum: 1000
default: 50
description: "Maximum number of events to delete in bulk operation"
example: 50
User:
type: object
properties:
id:
type: string
example: 4e4942c7dee1deef99ab8fd9f7350de5
name:
type: string
example: John Doe
avatar_url:
type: string
example: "https://example.com/avatar.jpg"
description: "URL of the user's WhatsApp profile avatar"
token:
type: string
example: "1234ABCD"
webhook:
type: string
example: "https://webhook.site/1234567890"
jid:
type: string
example: "5491155551122:12@s.whatsapp.net"
description: "WhatsApp JID (Jabber ID) of the connected account"
qrcode:
type: string
example: ""
description: "QR code data for pairing (empty when connected)"
connected:
type: boolean
example: true
description: "Whether the WhatsApp client is currently connected"
loggedIn:
type: boolean
example: true
description: "Whether the user is logged into WhatsApp"
expiration:
type: integer
example: 0
description: "Account expiration timestamp (0 for no expiration)"
events:
type: string
example: "All"
skip_media_download:
type: boolean
example: false
description: "Whether media download is skipped for this user"
skip_groups:
type: boolean
example: false
description: "Whether group messages are skipped for this user"
skip_newsletters:
type: boolean
example: false
description: "Whether newsletter messages are skipped for this user"
skip_broadcasts:
type: boolean
example: false
description: "Whether broadcast messages are skipped for this user"
skip_own_messages:
type: boolean
example: false
description: "Whether own messages are skipped for this user"
echo_api_messages:
type: boolean
example: false
description: "When true and global ECHO_API_MESSAGES_ENABLED is true, messages sent via API emit synthetic Message events flagged via Info.IsFromAPI."
skip_calls:
type: boolean
example: false
description: "Whether call events are skipped for this user"
call_reject_message:
type: string
example: "Sorry, I cannot take calls at the moment."
description: "Custom message sent when rejecting calls"
call_reject_type:
type: string
example: "busy"
description: "Type of call rejection (busy, decline or unavailable)"
globalTransportSkips:
$ref: "#/definitions/GlobalTransportSkipFlags"
description: "Snapshot of the global dispatcher skip flags (webhook, RabbitMQ, SQS, Redis, WebSocket, S3)."
isFromAPI:
type: boolean
example: false
description: "Reflects the Echo API configuration. When true, API sends emit events with Info.IsFromAPI=true."
proxy_config:
type: object
properties:
enabled:
type: boolean
example: true
proxy_url:
type: string
example: "https://serverproxy.com:9080"
s3_config:
type: object
properties:
enabled:
type: boolean
example: true
endpoint:
type: string
example: "https://s3.amazonaws.com"
region:
type: string
example: "us-east-1"
bucket:
type: string
example: "my-bucket"
access_key:
type: string
example: "***"
path_style:
type: boolean
example: true
public_url:
type: string
example: "https://s3.amazonaws.com"
media_delivery:
type: string
example: "both"
retention_days:
type: integer
example: 30
disable_acl:
type: boolean
example: true
description: "Set to true for AWS S3 buckets with 'Bucket owner enforced' Object Ownership"
rabbitmq_config:
type: object
properties:
enabled:
type: boolean
example: true
url:
type: string
example: "amqp://user:***@localhost:5672/"
description: "RabbitMQ connection URL (password masked)"
exchange:
type: string
example: "whatsapp.events"
exchange_type:
type: string
example: "topic"
queue:
type: string
example: "whatsapp.user.{user_id}"
queue_type:
type: string
example: "classic"
routing_key:
type: string
example: "whatsapp.{event_type}"
events:
type: string
example: "Message,ReadReceipt,All"
durable:
type: boolean
example: true
auto_delete:
type: boolean
example: false
exclusive:
type: boolean
example: false
no_wait:
type: boolean
example: false
delivery_mode:
type: integer
example: 2
dead_letter_exchange:
type: string
example: "dlx.whatsapp"
dead_letter_routing_key:
type: string
example: "dlq.events"
message_ttl:
type: integer
format: int64
example: 86400000
max_length:
type: integer
format: int64
example: 100000
max_length_bytes:
type: integer
format: int64
example: 104857600
queue_arguments:
type: string
example: '{"x-overflow":"reject-publish"}'
exchange_arguments:
type: string
example: "{}"
whatsapp_config:
type: object
properties:
wa_version:
type: string
example: "2.3000.1026436087"
description: "WhatsApp version string to emulate. This affects how the client identifies itself to WhatsApp servers."
wa_platform:
type: string
example: "WEB"
description: "WhatsApp platform being emulated"
wa_release_channel:
type: string
example: "RELEASE"
description: "WhatsApp release channel"
wa_web_sub_platform:
type: string
example: "WEB_BROWSER"
description: "WhatsApp web sub-platform"
wa_os_name:
type: string
example: "Mac OS 10"
description: "Operating system name"
wa_os_version:
type: string
example: "10.15.7"
description: "Operating system version"
wa_device_name:
type: string
example: "Desktop"
description: "Device name"
wa_manufacturer:
type: string
example: "Apple"
description: "Device manufacturer"
wa_device_board:
type: string
example: "Mac-123456"
description: "Device board identifier"
wa_locale_language:
type: string
example: "en"
description: "Locale language code"
wa_locale_country:
type: string
example: "US"
description: "Locale country code"
wa_mcc:
type: string
example: "000"
description: "Mobile Country Code"
wa_mnc:
type: string
example: "000"
description: "Mobile Network Code"
wa_connect_type:
type: string
example: "WIFI_UNKNOWN"
description: "Connection type"
wa_platform_type:
type: string
example: "DESKTOP"
description: "Platform type"
CreateUser:
type: object
required:
- name
- token
properties:
name:
type: string
example: John Doe
token:
type: string
example: "1234ABCD"
webhook:
type: string
example: "https://webhook.site/1234567890"
description: "Webhook URL to receive events"
events:
type: string
example: "All"
description: "Events to subscribe to. Available events include all 47 event types from Message, UndecryptableMessage, Receipt, MediaRetry, ReadReceipt, GroupInfo, JoinedGroup, Picture, BlocklistChange, Blocklist, Connected, Disconnected, ConnectFailure, KeepAliveRestored, KeepAliveTimeout, LoggedOut, ClientOutdated, TemporaryBan, StreamError, StreamReplaced, PairSuccess, PairError, QR, QRScannedWithoutMultidevice, PrivacySettings, PushNameSetting, UserAbout, AppState, AppStateSyncComplete, HistorySync, OfflineSyncCompleted, OfflineSyncPreview, CallOffer, CallAccept, CallTerminate, CallOfferNotice, CallRelayLatency, Presence, ChatPresence, IdentityChange, CATRefreshError, NewsletterJoin, NewsletterLeave, NewsletterMuteChange, NewsletterLiveUpdate, FBMessage, to All (which subscribes to all events). Ex: 'All', 'Message', 'Presence', 'Message,ReadReceipt,Connected'. Event names are case-sensitive; CSV values with spaces are normalized (for example: 'Message, Disconnected')."
echoApiMessages:
type: boolean
example: false
description: "Enable synthetic Message events for messages sent via API. Requires global ECHO_API_MESSAGES_ENABLED=true."
skipMedia:
type: boolean
example: false
description: "Skip processing messages from WhatsApp media. When enabled, only text messages will be processed, improving performance for applications that don't need media functionality. Default is false."
skipGroups:
type: boolean
example: false
description: "Skip processing messages from WhatsApp groups. When enabled, only direct messages will be processed, improving performance for applications that don't need group functionality. Default is false."
skipNewsletters:
type: boolean
example: false
description: "Skip processing messages from WhatsApp newsletters. When enabled, newsletter messages will be ignored, improving performance for applications that don't need newsletter functionality. Default is false."
skipBroadcasts:
type: boolean
example: false
description: "Skip processing messages from WhatsApp broadcasts and status updates. When enabled, broadcast messages and status updates will be ignored, improving performance for applications that don't need broadcast functionality. Default is false."
skipOwnMessages:
type: boolean
example: false
description: "Skip processing user's own messages. When enabled, messages sent by the user will be ignored, improving performance and avoiding message loops. Default is false."
skipCalls:
type: boolean
example: false
description: "Skip processing call events. When enabled, call offers, accepts, and terminations will be ignored, improving performance for applications that don't need call functionality. Default is false."
callRejectMessage:
type: string
example: "Sorry, I cannot take calls at the moment."
description: "Custom message to send when rejecting incoming calls. This message will be sent automatically when calls are rejected. Default is 'Sorry, I cannot take calls at the moment.'"
callRejectType:
type: string
example: "busy"
description: "Type of call rejection to use. Available options: 'busy' (indicates line is busy) or 'decline' (politely declines the call). Default is 'busy'."
enum: ["busy", "decline", "unavailable"]
globalTransportSkips:
$ref: "#/definitions/GlobalTransportSkipsRequest"
description: "Optional overrides for the global dispatcher skip flags (webhook, RabbitMQ, SQS, Redis, WebSocket, S3). Any flag omitted keeps the current value (defaults to false for new users)."
proxyConfig:
type: object
properties:
enabled:
type: boolean
example: true
description: "Enable proxy for the user, default is false"
proxyURL:
type: string
example: "https://serverproxy.com:9080"
description: "Proxy URL to use for the user. Format: socks5://user:pass@host:port or http://host:port"
s3Config:
type: object
description: "S3 storage configuration. Preferred keys are snake_case. camelCase aliases are also accepted for backward compatibility."
properties:
enabled:
type: boolean
example: true
description: "Enable S3 for the user, default is false"
endpoint:
type: string
example: "https://s3.amazonaws.com"
region:
type: string
example: "us-east-1"
bucket:
type: string
example: "my-bucket"
access_key:
type: string
example: "1234567890"
accessKey:
type: string
example: "1234567890"
description: "camelCase alias for access_key"
secret_key:
type: string
example: "1234567890"
secretKey:
type: string
example: "1234567890"
description: "camelCase alias for secret_key"
path_style:
type: boolean
example: true
description: "Enable path style for the user, default is false"
pathStyle:
type: boolean
example: true
description: "camelCase alias for path_style"
public_url:
type: string
example: "https://s3.amazonaws.com"
description: "Public URL for the user"
publicUrl:
type: string
example: "https://s3.amazonaws.com"
description: "camelCase alias for public_url"
media_delivery:
type: string
example: "both"
description: "Media delivery type for the user, default is both"
mediaDelivery:
type: string
example: "both"
description: "camelCase alias for media_delivery"
retention_days:
type: integer
example: 30
retentionDays:
type: integer
example: 30
description: "camelCase alias for retention_days"
disable_acl:
type: boolean
example: true
description: "Set to true for AWS S3 buckets with 'Bucket owner enforced' Object Ownership"
disableAcl:
type: boolean
example: true
description: "camelCase alias for disable_acl"
rabbitmqConfig:
type: object
properties:
enabled:
type: boolean
example: true
description: "Enable RabbitMQ for the user, default is false"
url:
type: string
example: "amqp://guest:guest@localhost:5672/"
description: "RabbitMQ connection URL"
exchange:
type: string
example: "whatsapp.events"
description: "Exchange name for events"
exchange_type:
type: string
example: "topic"
description: "Exchange type for events (required when enabled)"
enum: ["topic", "direct", "fanout", "headers"]
queue:
type: string
example: "whatsapp.user.{user_id}"
description: "Queue name pattern"
queue_type:
type: string
example: "classic"
description: "Queue type for events (required when enabled)"
enum: ["classic", "quorum", "stream"]
routing_key:
type: string
example: "whatsapp.{event_type}"
description: "Routing key pattern"
events:
type: string
example: "All"
description: "Event types to publish (comma-separated or 'All'). Available events include all 47 event types from Message, UndecryptableMessage, Receipt, MediaRetry, ReadReceipt, GroupInfo, JoinedGroup, Picture, BlocklistChange, Blocklist, Connected, Disconnected, ConnectFailure, KeepAliveRestored, KeepAliveTimeout, LoggedOut, ClientOutdated, TemporaryBan, StreamError, StreamReplaced, PairSuccess, PairError, QR, QRScannedWithoutMultidevice, PrivacySettings, PushNameSetting, UserAbout, AppState, AppStateSyncComplete, HistorySync, OfflineSyncCompleted, OfflineSyncPreview, CallOffer, CallAccept, CallTerminate, CallOfferNotice, CallRelayLatency, Presence, ChatPresence, IdentityChange, CATRefreshError, NewsletterJoin, NewsletterLeave, NewsletterMuteChange, NewsletterLiveUpdate, FBMessage, to All (which subscribes to all events). Event names are case-sensitive; CSV values with spaces are normalized (for example: 'Message, Disconnected')."
durable:
type: boolean
example: true
description: "Whether resources should be durable"
auto_delete:
type: boolean
example: false
description: "Whether resources should auto-delete"
exclusive:
type: boolean
example: false
description: "Whether queue should be exclusive"
no_wait:
type: boolean
example: false
description: "Whether to use no-wait mode"
delivery_mode:
type: integer
example: 2
description: "Message delivery mode (1=non-persistent, 2=persistent)"
dead_letter_exchange:
type: string
example: "dlx.whatsapp"
description: "Dead Letter Exchange name. Rejected or expired messages will be routed to this exchange."
dead_letter_routing_key:
type: string
example: "dlq.events"
description: "Routing key for Dead Letter Exchange. Used when routing rejected/expired messages to DLQ."
message_ttl:
type: integer
format: int64
example: 86400000
description: "Message TTL (Time To Live) in milliseconds. Messages older than this will be discarded or sent to DLX."
max_length:
type: integer
format: int64
example: 100000
description: "Maximum number of messages in the queue. Overflow behavior depends on x-overflow setting."
max_length_bytes:
type: integer
format: int64
example: 104857600
description: "Maximum total size of messages in the queue in bytes."
queue_arguments:
type: object
additionalProperties: true
example: { "x-overflow": "reject-publish" }
description: "Custom queue arguments as JSON object. Supports any RabbitMQ queue argument like x-overflow, x-queue-master-locator, etc."
exchange_arguments:
type: object
additionalProperties: true
example: {}
description: "Custom exchange arguments as JSON object. Supports any RabbitMQ exchange argument."
connection_pool_size:
type: integer
example: 50
description: "Size of the connection pool for RabbitMQ connections. Higher values allow more concurrent operations."
worker_count:
type: integer
example: 100
description: "Number of concurrent workers for message publishing."
queue_buffer_size:
type: integer
example: 100000
description: "In-memory queue buffer size for event batching before publishing."
batch_size:
type: integer
example: 1000
description: "Number of events to batch together before publishing."
batch_timeout_ms:
type: integer
example: 100
description: "Maximum time in milliseconds to wait before publishing a partial batch."
publish_timeout_ms:
type: integer
example: 5000
description: "Timeout in milliseconds for individual publish operations."
max_retries:
type: integer
example: 3
description: "Maximum number of retry attempts for failed publish operations."
retry_delay_ms:
type: integer
example: 1000
description: "Delay in milliseconds between retry attempts."
whatsappConfig:
type: object
properties:
waVersion:
type: string
example: "2.3000.1025473630"
description: "WhatsApp version string to emulate. This affects how the client identifies itself to WhatsApp servers."
waPlatform:
type: string
example: "WEB"
description: "WhatsApp platform type to emulate."
enum: ["WEB", "ANDROID", "IOS"]
waReleaseChannel:
type: string
example: "RELEASE"
description: "WhatsApp release channel to emulate."
enum: ["RELEASE", "BETA"]
waWebSubPlatform:
type: string
example: "WEB_BROWSER"
description: "WhatsApp web sub-platform for web clients."
enum: ["WEB_BROWSER", "DARWIN"]
waOSName:
type: string
example: "Mac OS 10"
description: "Operating system name to report to WhatsApp."
waOSVersion:
type: string
example: "10.15.7"
description: "Operating system version to report to WhatsApp."
waDeviceName:
type: string
example: "Desktop"
description: "Device name to report to WhatsApp."
waManufacturer:
type: string
example: "Apple"
description: "Device manufacturer to report to WhatsApp."
waDeviceBoard:
type: string
example: "Mac-123456"
description: "Device board identifier to report to WhatsApp."
waLocaleLanguage:
type: string
example: "en"
description: "Locale language code (ISO 639-1) for the WhatsApp client."
waLocaleCountry:
type: string
example: "US"
description: "Locale country code (ISO 3166-1 alpha-2) for the WhatsApp client."
waMCC:
type: string
example: "000"
description: "Mobile Country Code for network identification."
waMNC:
type: string
example: "000"
description: "Mobile Network Code for network identification."
waConnectType:
type: string
example: "WIFI_UNKNOWN"
description: "Connection type to report to WhatsApp."
enum: ["WIFI_UNKNOWN", "CELLULAR_LTE", "CELLULAR_3G", "CELLULAR_2G"]
waPlatformType:
type: string
example: "DESKTOP"
description: "Platform type for client identification."
enum: ["DESKTOP", "CHROME", "FIREFOX", "SAFARI", "EDGE"]
GlobalTransportSkipsRequest:
type: object
description: "Partial update payload for per-transport skip flags. Omitted transports keep their existing state."
additionalProperties: false
properties:
skipGlobalWebhook:
type: boolean
example: false
description: "Skip sending events to the global webhook dispatcher."
skipGlobalRabbitMQ:
type: boolean
example: false
description: "Skip sending events to the global RabbitMQ dispatcher."
skipGlobalSQS:
type: boolean
example: false
description: "Skip sending events to the global SQS dispatcher."
skipGlobalRedis:
type: boolean
example: false
description: "Skip emitting events to the global Redis/pub-sub dispatcher."
skipGlobalWebSocket:
type: boolean
example: false
description: "Skip emitting events to the global WebSocket broadcaster."
skipGlobalS3:
type: boolean
example: false
description: "Skip the shared/global S3 enrichment pipeline."
GlobalTransportSkipFlags:
type: object
properties:
skipGlobalWebhook:
type: boolean
example: false
skipGlobalRabbitMQ:
type: boolean
example: false
skipGlobalSQS:
type: boolean
example: false
skipGlobalRedis:
type: boolean
example: false
skipGlobalWebSocket:
type: boolean
example: false
skipGlobalS3:
type: boolean
example: false
GlobalTransportSkipsState:
allOf:
- $ref: "#/definitions/GlobalTransportSkipFlags"
- type: object
properties:
details:
type: string
example: "Global transport skip configuration retrieved successfully"
GlobalTransportSkipsResponse:
type: object
properties:
code:
type: integer
example: 200
data:
$ref: "#/definitions/GlobalTransportSkipsState"
success:
type: boolean
example: true
EchoAPISettingsRequest:
type: object
required:
- enabled
properties:
enabled:
type: boolean
example: true
description: "Enable or disable API message echo. Requires global ECHO_API_MESSAGES_ENABLED=true."
EchoAPISettingsResponse:
type: object
properties:
EchoAPIMessages:
type: boolean
example: true
description: "Indicates if synthetic Message events with Info.IsFromAPI are enabled."
Details:
type: string
example: Echo API messages configuration updated successfully
DeleteUser:
type: object
properties:
id:
type: string
example: 4e4942c7dee1deef99ab8fd9f7350de5
GroupPhoto:
type: object
properties:
GroupJID:
type: string
example: "120362023605733675@g.us"
Image:
type: string
description: "Image data as base64 data URL (data:image/jpeg;base64,xxx) or HTTP(S) URL (https://example.com/image.jpg). Supported format: JPEG!"
example: "data:image/jpeg;base64,Akd9300..."
GroupInfo:
type: object
properties:
GroupJID:
type: string
example: "120362023605733675@g.us"
GroupInviteLink:
type: object
properties:
GroupJID:
type: string
example: "120362023605733675@g.us"
Reset:
type: boolean
example: false
Connect:
type: object
properties:
Subscribe:
type: string
example: ["Message", "ChatPresence", "Connected", "All"]
description: "Array of event types to subscribe to. Available events include all 47 event types from Message, UndecryptableMessage, Receipt, MediaRetry, ReadReceipt, GroupInfo, JoinedGroup, Picture, BlocklistChange, Blocklist, Connected, Disconnected, ConnectFailure, KeepAliveRestored, KeepAliveTimeout, LoggedOut, ClientOutdated, TemporaryBan, StreamError, StreamReplaced, PairSuccess, PairError, QR, QRScannedWithoutMultidevice, PrivacySettings, PushNameSetting, UserAbout, AppState, AppStateSyncComplete, HistorySync, OfflineSyncCompleted, OfflineSyncPreview, CallOffer, CallAccept, CallTerminate, CallOfferNotice, CallRelayLatency, Presence, ChatPresence, IdentityChange, CATRefreshError, NewsletterJoin, NewsletterLeave, NewsletterMuteChange, NewsletterLiveUpdate, FBMessage, to All (which subscribes to all events)"
Immediate:
type: boolean
DownloadImage:
type: object
required:
- Url
- MediaKey
- Mimetype
- FileSHA256
- FileLength
properties:
Url:
type: string
DirectPath:
type: string
MediaKey:
type: string
Mimetype:
type: string
FileEncSHA256:
type: string
FileSHA256:
type: string
FileLength:
type: number
ChatPresence:
type: object
required:
- Phone
- State
properties:
Phone:
type: string
example: "5521971532700"
State:
type: string
example: composing
Media:
type: string
example: audio
UserPresence:
type: object
required:
- type
properties:
type:
type: string
example: available
MessageContact:
type: object
required:
- Phone
- Name
- Vcard
properties:
Phone:
type: string
example: "5521971532700"
description: "Phone number with country code"
Name:
type: string
example: "John Doe"
description: "Contact display name"
Id:
type: string
example: "ABCDABCD1234"
description: "Optional custom message ID"
Vcard:
type: string
example: "BEGIN:VCARD\nVERSION:3.0\nN:Doe;John;;;\nFN:John Doe\nORG:Example.com Inc.;\nTITLE:Imaginary test person\nEMAIL;type=INTERNET;type=WORK;type=pref:johnDoe@example.org\nTEL;type=WORK;type=pref:+1 617 555 1212\nTEL;type=WORK:+1 (617) 555-1234\nTEL;type=CELL:+1 781 555 1212\nTEL;type=HOME:+1 202 555 1212\nitem1.ADR;type=WORK:;;2 Enterprise Avenue;Worktown;NY;01111;USA\nitem1.X-ABADR:us\nitem2.ADR;type=HOME;type=pref:;;3 Acacia Avenue;Hoitem2.X-ABADR:us\nEND:VCARD"
description: "Contact information in vCard format"
NumberCheck:
type: boolean
example: true
description: "Set to true to verify if the phone number is registered on WhatsApp before sending."
Presence:
type: integer
example: 3000
description: "Milliseconds to simulate typing indicator"
Duration:
type: integer
example: 86400
description: "Message expiration time in seconds"
EchoApi:
type: boolean
example: true
description: "Optional. Set to true to force emission of API echo events for this specific message, regardless of global or per-session echo settings. When enabled, a synthetic Message event with Info.IsFromAPI=true will be emitted through your configured transports/webhook after the message is successfully sent. This allows individual message-level control over echo behavior, overriding both ECHO_API_MESSAGES_ENABLED (global) and the per-session echo_api_messages setting. Useful for selectively tracking specific API-sent messages through your event pipeline."
ContextInfo:
$ref: "#/definitions/ContextInfo"
MessageLocation:
type: object
required:
- Phone
- Latitude
- Longitude
properties:
Phone:
type: string
example: "5521971532700"
description: "Phone number with country code"
Name:
type: string
example: "Eiffel Tower"
description: "Optional location name or description"
Id:
type: string
example: "ABCDABCD1234"
description: "Optional custom message ID"
Latitude:
type: number
format: float
example: 48.858370
description: "Location latitude coordinate"
Longitude:
type: number
format: float
example: 2.294481
description: "Location longitude coordinate"
NumberCheck:
type: boolean
example: true
description: "Set to true to verify if the phone number is registered on WhatsApp before sending."
Presence:
type: integer
example: 3000
description: "Milliseconds to simulate typing indicator"
Duration:
type: integer
example: 86400
description: "Message expiration time in seconds"
EchoApi:
type: boolean
example: true
description: "Optional. Set to true to force emission of API echo events for this specific message, regardless of global or per-session echo settings. When enabled, a synthetic Message event with Info.IsFromAPI=true will be emitted through your configured transports/webhook after the message is successfully sent. This allows individual message-level control over echo behavior, overriding both ECHO_API_MESSAGES_ENABLED (global) and the per-session echo_api_messages setting. Useful for selectively tracking specific API-sent messages through your event pipeline."
ContextInfo:
$ref: "#/definitions/ContextInfo"
ReactionText:
type: object
required:
- Phone
- Body
- Id
properties:
Phone:
type: string
example: "5521971532700"
Body:
type: string
example: "❤️"
Id:
type: string
example: "me:3EB06F9067F80BAB89FF"
MessagePoll:
type: object
required:
- Group
- Header
- Options
properties:
Group:
type: string
example: "120363417042313103@g.us"
description: "Group JID where to send the poll"
Header:
type: string
example: "What's your favorite color?"
description: "Poll question/header text"
Options:
type: array
description: "Array of poll options (minimum 2, maximum 12)"
items:
type: string
example: "Red"
minItems: 2
maxItems: 12
MaxAnswer:
type: integer
example: 1
description: "Maximum number of answers per user. If not set to 1, all options will be available for selection (accepts both 'max_answer' and 'MaxAnswer' for compatibility)"
Id:
type: string
example: "3EB06F9067F80BAB89FF"
description: "Optional custom message ID"
NumberCheck:
type: boolean
example: true
description: "Set to true to verify if the phone number is registered on WhatsApp before sending."
Presence:
type: integer
example: 3000
description: "Milliseconds to simulate typing indicator (accepts both 'presence' and 'Presence' for compatibility)"
Duration:
type: integer
example: 86400
description: "Message expiration time in seconds (accepts both 'duration' and 'Duration' for compatibility)"
EchoApi:
type: boolean
example: true
description: "Optional. Set to true to force emission of API echo events for this specific message, regardless of global or per-session echo settings. When enabled, a synthetic Message event with Info.IsFromAPI=true will be emitted through your configured transports/webhook after the message is successfully sent. This allows individual message-level control over echo behavior, overriding both ECHO_API_MESSAGES_ENABLED (global) and the per-session echo_api_messages setting. Useful for selectively tracking specific API-sent messages through your event pipeline."
ContextInfo:
$ref: "#/definitions/ContextInfo"
MessageList:
type: object
required:
- Phone
- Text
- ButtonText
- Sections
properties:
Phone:
type: string
example: "5521971532700"
description: "Phone number with country code. Must include country code without + symbol (e.g., 5521971532700)."
Id:
type: string
example: "LIST_001"
description: "Optional custom message ID. If not provided, a random one will be generated."
NumberCheck:
type: boolean
example: true
description: "Set to true to verify if the phone number is registered on WhatsApp before sending."
Presence:
type: integer
example: 3000
description: "Milliseconds to simulate typing indicator (accepts both 'presence' and 'Presence' for compatibility)"
Text:
type: string
example: "Choose one of the options below"
description: "Main list description text. Maximum 1024 characters. This explains what the list is about."
Title:
type: string
example: "Product Catalog"
description: "Optional list title/header. Maximum 60 characters. Displayed at the top of the list."
Footer:
type: string
example: "Powered by ZuckZapGo API"
description: "Optional footer text. Maximum 60 characters. Displayed at the bottom of the list."
ButtonText:
type: string
example: "View Options"
description: "Text for the main action button that opens the list. Maximum 20 characters."
Sections:
type: array
description: "Array of list sections. Maximum 10 sections allowed."
maxItems: 10
items:
type: object
required:
- Title
- Rows
properties:
Title:
type: string
example: "Main Products"
description: "Section title. Maximum 24 characters."
Rows:
type: array
description: "Array of rows in this section. Maximum 10 rows per section."
maxItems: 10
items:
type: object
required:
- RowId
- Title
- Description
properties:
RowId:
type: string
example: "product_1"
description: "Unique identifier for this row. Used in response callbacks."
Title:
type: string
example: "Premium Package"
description: "Row title/name. Maximum 24 characters."
Description:
type: string
example: "Complete package with all features included"
description: "Row description. Maximum 72 characters."
EchoApi:
type: boolean
example: true
description: "Optional. Set to true to force emission of API echo events for this specific message, regardless of global or per-session echo settings. When enabled, a synthetic Message event with Info.IsFromAPI=true will be emitted through your configured transports/webhook after the message is successfully sent. This allows individual message-level control over echo behavior, overriding both ECHO_API_MESSAGES_ENABLED (global) and the per-session echo_api_messages setting. Useful for selectively tracking specific API-sent messages through your event pipeline."
ContextInfo:
$ref: "#/definitions/ContextInfo"
MessageText:
type: object
required:
- Phone
- Body
properties:
Phone:
type: string
example: "5521971532700"
description: "Phone number with country code. Must include country code without + symbol (e.g., 5521971532700)."
Body:
type: string
example: "How you doin"
description: "Text message content. Supports Unicode, emojis, and formatting. Maximum 4096 characters."
Id:
type: string
example: "ABCDABCD1234"
description: "Optional custom message ID. If not provided, a random one will be generated."
Presence:
type: integer
example: 3000
description: "Milliseconds to simulate typing indicator before sending message. Useful for natural conversation flow."
Duration:
type: integer
example: 86400
description: "Message expiration time in seconds. Valid values: 86400 (24h), 604800 (7 days), 7776000 (90 days)."
LinkPreview:
type: boolean
example: true
description: "Set to true to enable automatic link preview for URLs in the message text."
NumberCheck:
type: boolean
example: true
description: "Set to true to verify if the phone number is registered on WhatsApp before sending."
EchoApi:
type: boolean
example: true
description: "Optional. Set to true to force emission of API echo events for this specific message, regardless of global or per-session echo settings. When enabled, a synthetic Message event with Info.IsFromAPI=true will be emitted through your configured transports/webhook after the message is successfully sent. This allows individual message-level control over echo behavior, overriding both ECHO_API_MESSAGES_ENABLED (global) and the per-session echo_api_messages setting. Useful for selectively tracking specific API-sent messages through your event pipeline."
ContextInfo:
$ref: "#/definitions/ContextInfo"
example:
Phone: "5521971532700"
Body: "This is my reply to your message"
Id: "ABCDABCD1234"
Presence: 3000
Duration: 86400
LinkPreview: true
NumberCheck: true
EchoApi: false
ContextInfo:
stanzaID: "3EB06F9067F80BAB89FF"
participant: "5511888888888@s.whatsapp.net"
quotedMessage:
conversation: "Original message text being replied to"
isForwarded: false
mentionedJID:
- "5521971532700@s.whatsapp.net"
mentionAll: false
MessageLink:
type: object
required:
- Phone
- Link
properties:
Phone:
type: string
example: "5521971532700"
description: "Phone number with country code. Must include country code without + symbol (e.g., 5521971532700)."
Link:
type: string
example: "https://example.com"
description: "Link to send. Must be a valid URL."
Caption:
type: string
example: "Link Description"
description: "Optional caption for the link. Maximum 1024 characters. Supports Unicode and emojis."
Id:
type: string
example: "ABCDABCD1234"
description: "Optional custom message ID. If not provided, a random one will be generated."
NumberCheck:
type: boolean
example: true
description: "Set to true to verify if the phone number is registered on WhatsApp before sending."
EchoApi:
type: boolean
example: true
description: "Optional. Set to true to force emission of API echo events for this specific message, regardless of global or per-session echo settings. When enabled, a synthetic Message event with Info.IsFromAPI=true will be emitted through your configured transports/webhook after the message is successfully sent. This allows individual message-level control over echo behavior, overriding both ECHO_API_MESSAGES_ENABLED (global) and the per-session echo_api_messages setting. Useful for selectively tracking specific API-sent messages through your event pipeline."
ContextInfo:
$ref: "#/definitions/ContextInfo"
MessageImage:
type: object
required:
- Phone
- Image
properties:
Phone:
type: string
example: "5521971532700"
description: "Phone number with country code. Must include country code without + symbol (e.g., 5521971532700)."
Image:
type: string
example: "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg=="
description: "Image data as base64 data URL (data:image/jpeg;base64,xxx) or HTTP(S) URL (https://example.com/image.jpg). Supported formats: JPEG, PNG, GIF, WebP. Maximum size: 5MB."
Caption:
type: string
example: "Image Description"
description: "Optional caption for the image. Maximum 1024 characters. Supports Unicode and emojis."
Id:
type: string
example: "ABCDABCD1234"
description: "Optional custom message ID. If not provided, a random one will be generated."
MimeType:
type: string
example: "image/jpeg"
description: "Optional MIME type override. Supported: image/jpeg, image/png, image/gif, image/webp. Auto-detected if not provided."
Presence:
type: integer
example: 3000
description: "Milliseconds to simulate typing indicator before sending message."
ViewOnce:
type: boolean
example: true
description: "Set to true for disappearing message after viewing (view once). Cannot be combined with Duration."
Duration:
type: integer
example: 86400
description: "Message expiration time in seconds. Valid values: 86400 (24h), 604800 (7 days), 7776000 (90 days)."
NumberCheck:
type: boolean
example: true
description: "Set to true to verify if the phone number is registered on WhatsApp before sending."
EchoApi:
type: boolean
example: true
description: "Optional. Set to true to force emission of API echo events for this specific message, regardless of global or per-session echo settings. When enabled, a synthetic Message event with Info.IsFromAPI=true will be emitted through your configured transports/webhook after the message is successfully sent. This allows individual message-level control over echo behavior, overriding both ECHO_API_MESSAGES_ENABLED (global) and the per-session echo_api_messages setting. Useful for selectively tracking specific API-sent messages through your event pipeline."
ContextInfo:
$ref: "#/definitions/ContextInfo"
MessageAudio:
type: object
required:
- Phone
- Audio
properties:
Phone:
type: string
example: "5521971532700"
description: "Phone number with country code. Must include country code without + symbol (e.g., 5521971532700)."
Audio:
type: string
example: "data:audio/ogg;base64,T2dnUwACAAAAAAAAAABK"
description: "Audio data as base64 data URL (data:audio/ogg;base64,xxx) or HTTP(S) URL (https://example.com/audio.ogg). Supported formats: OGG, MP3, AAC, M4A, WAV. Maximum size: 16MB."
Caption:
type: string
example: "Voice message caption"
description: "Optional caption for the audio. Maximum 1024 characters. Supports Unicode and emojis."
Id:
type: string
example: "ABCDABCD1234"
description: "Optional custom message ID. If not provided, a random one will be generated."
PTT:
type: boolean
example: true
description: "Set to true for voice note (push-to-talk), false for audio file. Voice notes show with different UI and waveform. Default: true."
Presence:
type: integer
example: 3000
description: "Milliseconds to simulate recording indicator before sending message. Useful for natural conversation flow."
ViewOnce:
type: boolean
example: true
description: "Set to true for disappearing message after viewing (view once). Cannot be combined with Duration."
Duration:
type: integer
example: 86400
description: "Message expiration time in seconds. Valid values: 86400 (24h), 604800 (7 days), 7776000 (90 days)."
NumberCheck:
type: boolean
example: true
description: "Set to true to verify if the phone number is registered on WhatsApp before sending."
EchoApi:
type: boolean
example: true
description: "Optional. Set to true to force emission of API echo events for this specific message, regardless of global or per-session echo settings. When enabled, a synthetic Message event with Info.IsFromAPI=true will be emitted through your configured transports/webhook after the message is successfully sent. This allows individual message-level control over echo behavior, overriding both ECHO_API_MESSAGES_ENABLED (global) and the per-session echo_api_messages setting. Useful for selectively tracking specific API-sent messages through your event pipeline."
ContextInfo:
$ref: "#/definitions/ContextInfo"
MessageVideo:
type: object
required:
- Phone
- Video
properties:
Phone:
type: string
example: "5521971532700"
description: "Phone number with country code (accepts both 'phone' and 'Phone' for compatibility)"
Video:
type: string
example: "data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDE="
description: "Video data as base64 data URL (data:video/mp4;base64,xxx) or HTTP(S) URL (https://example.com/video.mp4) (accepts both 'video' and 'Video' for compatibility)"
Caption:
type: string
example: "my video"
description: "Optional caption for the video (accepts both 'caption' and 'Caption' for compatibility)"
Id:
type: string
example: "ABCDABCD1234"
description: "Optional custom message ID (accepts both 'id' and 'Id' for compatibility)"
MimeType:
type: string
example: "video/mp4"
description: "Optional MIME type override (video/mp4, video/3gpp, video/quicktime, video/x-ms-asf) (accepts both 'mimetype' and 'MimeType' for compatibility)"
JPEGThumbnail:
type: string
format: byte
description: "Optional JPEG thumbnail as base64 string (accepts both 'jpegthumbnail' and 'JPEGThumbnail' for compatibility)"
example: "/9j/4AAQSkZJRgABAQEAYABgAAD/..."
Presence:
type: integer
example: 3000
description: "Milliseconds to simulate typing indicator"
ViewOnce:
type: boolean
example: true
description: "Set to true for disappearing message after viewing (accepts both 'view_once' and 'ViewOnce' for compatibility)"
Duration:
type: integer
example: 86400
description: "Message expiration time in seconds (accepts both 'duration' and 'Duration' for compatibility)"
EchoApi:
type: boolean
example: true
description: "Optional. Set to true to force emission of API echo events for this specific message, regardless of global or per-session echo settings. When enabled, a synthetic Message event with Info.IsFromAPI=true will be emitted through your configured transports/webhook after the message is successfully sent. This allows individual message-level control over echo behavior, overriding both ECHO_API_MESSAGES_ENABLED (global) and the per-session echo_api_messages setting. Useful for selectively tracking specific API-sent messages through your event pipeline."
ContextInfo:
$ref: "#/definitions/ContextInfo"
MessagePTV:
type: object
required:
- Phone
- Video
properties:
Phone:
type: string
example: "5521971532700"
description: "Phone number with country code (accepts both 'phone' and 'Phone' for compatibility)"
Video:
type: string
example: "data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDE="
description: "Video data as base64 data URL (data:video/mp4;base64,xxx) or HTTP(S) URL (https://example.com/video.mp4) for PTV message (accepts both 'video' and 'Video' for compatibility)"
MessageEvent:
type: object
required:
- Phone
- Name
- StartTime
properties:
Phone:
type: string
example: "5521971532700"
description: "Phone number with country code. Must include country code without + symbol (e.g., 5521971532700)."
Name:
type: string
example: "Team Meeting"
description: "Event title/name. Maximum 255 characters."
Description:
type: string
example: "Weekly team sync meeting to discuss project updates"
description: "Optional detailed event description. Maximum 1024 characters. Supports Unicode and emojis."
StartTime:
type: integer
format: int64
example: 2524608000
description: "Event start time as Unix timestamp (seconds since epoch). Required field."
EndTime:
type: integer
format: int64
example: 2556143999
description: "Event end time as Unix timestamp (seconds since epoch). Optional, but recommended."
ExtraGuestsAllowed:
type: boolean
example: true
description: "Set to true to allow participants to invite additional guests to the event."
IsCanceled:
type: boolean
example: false
description: "Set to true to mark the event as cancelled. Default: false."
IsScheduleCall:
type: boolean
example: true
description: "Set to true if this is a scheduled call event (video/voice meeting)."
Id:
type: string
example: "EVENT_001"
description: "Optional custom message ID. If not provided, a random one will be generated."
Presence:
type: integer
example: 2000
description: "Milliseconds to simulate typing indicator before sending event."
NumberCheck:
type: boolean
example: true
description: "Set to true to verify if the phone number is registered on WhatsApp before sending."
Location:
type: object
description: "Optional event location details with GPS coordinates."
properties:
Name:
type: string
example: "Conference Room A, Main Office"
description: "Location name or address. Maximum 255 characters."
DegreesLatitude:
type: number
format: float
example: -23.5505
description: "Latitude coordinate for the location (GPS)."
DegreesLongitude:
type: number
format: float
example: -46.6333
description: "Longitude coordinate for the location (GPS)."
EchoApi:
type: boolean
example: true
description: "Optional. Set to true to force emission of API echo events for this specific message, regardless of global or per-session echo settings. When enabled, a synthetic Message event with Info.IsFromAPI=true will be emitted through your configured transports/webhook after the message is successfully sent. This allows individual message-level control over echo behavior, overriding both ECHO_API_MESSAGES_ENABLED (global) and the per-session echo_api_messages setting. Useful for selectively tracking specific API-sent messages through your event pipeline."
ContextInfo:
$ref: "#/definitions/ContextInfo"
ButtonsMessage:
type: object
description: "Interactive message with buttons."
required:
- phone
- buttons
properties:
phone:
type: string
example: "5521971532700"
description: "Recipient phone number with country code (without +) or group JID (e.g., 120363312246943103@g.us)."
title:
type: string
example: "Pagamento PIX"
description: "Optional heading displayed above the body. Recommended maximum of 60 characters."
body:
type: string
example: "Escaneie o QR Code para pagar via PIX"
description: "Primary message text. Use this or text when not sending media headers."
text:
type: string
example: "Escolha uma opção abaixo"
description: "Alternative field for the primary text. When media headers are present, prefer caption/text over body."
footer:
type: string
example: "Equipe ZuckZapGo"
description: "Optional footer text displayed below the buttons."
caption:
type: string
example: "Oferta da semana"
description: "Optional media caption when using image/video/document headers."
image:
type: object
description: "Optional image header."
required:
- url
properties:
url:
type: string
format: uri
example: "https://picsum.photos/600/400.jpg"
description: "HTTP(S) or data URL pointing to the image."
video:
type: object
description: "Optional video header."
required:
- url
properties:
url:
type: string
format: uri
example: "https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4"
description: "HTTP(S) or data URL pointing to the video file."
document:
type: object
description: "Optional document header (PDF, DOC, etc.)."
required:
- url
properties:
url:
type: string
format: uri
example: "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
description: "HTTP(S) or data URL pointing to the document."
buttons:
type: array
description: "Array of interactive buttons."
minItems: 1
maxItems: 10
items:
type: object
required:
- buttonId
- buttonText
- type
properties:
buttonId:
type: string
example: "pix_btn_1"
description: "Unique button identifier returned in callbacks."
buttonText:
type: object
description: "Label configuration for the button."
required:
- displayText
properties:
displayText:
type: string
example: "Pagar com PIX"
description: "Button label shown to end users."
type:
type: string
enum:
[
quick_reply,
reply,
url,
cta_url,
call,
cta_call,
copy,
cta_copy,
pix,
pix_payment,
payment_info,
review_and_pay,
]
example: "pix"
description: "Button action type. Use `pix`/`payment_info` for PIX payments, `review_and_pay` for order payments, and quick_reply/cta_* for interactive actions."
url:
type: string
format: uri
example: "https://exemplo.com/oferta"
description: "Destination URL for url/cta_url buttons."
merchant_url:
type: string
format: uri
example: "https://store.example.com/checkout"
description: "Alternative merchant URL for url buttons."
phone:
type: string
example: "+5511988888888"
description: "Phone number in E.164 format for call/cta_call buttons."
code:
type: string
example: "CUPOM123"
description: "Coupon or code copied when using copy/cta_copy buttons."
pix_key:
type: string
example: "11999999999"
description: "PIX key for pix/payment_info/review_and_pay buttons."
merchant_name:
type: string
example: "Minha Loja"
description: "Merchant name shown on PIX/review_and_pay buttons."
pix_type:
type: string
example: "PHONE"
enum: [PHONE, EMAIL, CPF, CNPJ, EVP]
description: "Type of PIX key provided in pix_key."
currency:
type: string
example: "BRL"
description: "Currency code (ISO 4217) for review_and_pay buttons."
total_value:
type: integer
example: 2599
description: "Total amount in minor units (e.g., cents) for review_and_pay buttons."
total_offset:
type: integer
example: 100
description: "Optional offset or discount amount in minor units."
reference_id:
type: string
example: "ORDER-2024-001"
description: "Reference identifier associated with the payment/order."
items:
type: array
description: "Detailed order items for review_and_pay buttons."
items:
type: object
required:
- name
- quantity
- amount_value
- amount_offset
properties:
name:
type: string
example: "Fone de ouvido"
description: "Item name."
quantity:
type: integer
example: 1
description: "Quantity of the item."
amount_value:
type: integer
example: 7990
description: "Item value in minor units (e.g., cents)."
amount_offset:
type: integer
example: 100
description: "Optional discount/offset in minor units for the item."
id:
type: string
example: "BUTTONS_8A7B9C2D1E3F4A5B6C7D8E9F0A1B2C3D"
description: "Optional custom message ID. If not provided, a random one will be generated."
presence:
type: integer
example: 2000
description: "Milliseconds to simulate typing indicator before sending the message."
duration:
type: integer
example: 10
description: "Ephemeral duration for the message (when applicable)."
number_check:
type: boolean
example: true
description: "Set to true to verify if the phone number is registered on WhatsApp before sending."
context_info:
$ref: "#/definitions/ContextInfo"
FlowMessage:
type: object
description: "Native flow interactive message."
required:
- Phone
- Buttons
properties:
Phone:
type: string
example: "5521971532700"
description: "Recipient phone number with country code (without +) or group JID."
Body:
type: string
example: "Complete your profile to unlock premium features"
description: "Primary message text. Use this or Text/Message."
Text:
type: string
example: "Complete your profile to unlock premium features"
description: "Alternative body text."
Message:
type: string
example: "Complete your profile to unlock premium features"
description: "Legacy body text field."
Caption:
type: string
example: "Let's get started"
description: "Optional caption when using media headers."
Footer:
type: string
example: "Powered by ZuckZapGo"
description: "Optional footer text."
Id:
type: string
example: "FLOW_MSG_001"
description: "Custom message ID. Auto-generated when omitted."
Presence:
type: integer
example: 2000
description: "Typing simulation in milliseconds before sending."
NumberCheck:
type: boolean
example: true
description: "Verify that the recipient is registered on WhatsApp before sending."
MessageVersion:
type: integer
format: int32
example: 3
description: "Native flow message version. Use the latest available version."
MessageParams:
type: object
description: "Flow parameters as an object. Use MessageParams or MessageParamsJSON."
additionalProperties: true
example:
flow_type: "registration"
required_fields: ["name", "email"]
MessageParamsJSON:
type: string
example: '{"flow_type":"registration"}'
description: "Flow parameters represented as a JSON string."
Header:
type: object
description: "Optional header with title, subtitle, and media."
properties:
Title:
type: string
example: "Complete your profile"
Subtitle:
type: string
example: "Only takes 2 minutes"
Media:
type: object
properties:
Type:
type: string
enum: [image, video, document]
example: "image"
description: "Header media type."
Url:
type: string
example: "https://example.com/header.png"
description: "Media URL or base64 data URL."
Caption:
type: string
example: "Preview"
Filename:
type: string
example: "guide.pdf"
MimeType:
type: string
example: "image/png"
Buttons:
type: array
description: "Array of native flow buttons."
minItems: 1
items:
type: object
required:
- Name
properties:
Name:
type: string
example: "complete_profile"
description: "Button identifier."
ButtonParams:
type: object
description: "Button parameters as an object."
additionalProperties: true
example:
display_text: "Complete Profile"
flow_id: "123456789"
ButtonParamsJSON:
type: string
example: '{"display_text":"Complete Profile","flow_id":"123456789"}'
description: "Button parameters as JSON string."
Params:
type: object
description: "Optional flow parameters object."
additionalProperties: true
example:
mode: "draft"
version: "3.0"
ParamsJSON:
type: string
example: '{"mode":"published","version":"3.0"}'
description: "Optional flow parameters JSON string."
ContextInfo:
$ref: "#/definitions/ContextInfo"
CarouselMessage:
type: object
description: "Carousel message with multiple cards."
required:
- Phone
- Message
- Carousel
properties:
Phone:
type: string
example: "5521971532700"
description: "Recipient phone number with country code (without +) or group JID."
Message:
type: string
example: "Check out our featured products!"
description: "Introductory text shown before the carousel cards."
Carousel:
type: array
description: "Array of carousel card objects."
minItems: 1
maxItems: 10
items:
type: object
required:
- Text
- Buttons
properties:
Text:
type: string
example: "Premium Wireless Headphones\n\n• Noise cancellation\n• 30h battery\n• Premium sound\n\n$299.99"
description: "Card body text."
MediaUrl:
type: string
example: "https://picsum.photos/600/400.jpg"
description: "Optional media URL or base64 data URL."
MediaType:
type: string
enum: [image, video, document]
example: "image"
description: "Media type required when MediaUrl is provided."
Filename:
type: string
example: "Product_Guide.pdf"
description: "Optional filename for document media."
Caption:
type: string
example: "Best Seller!"
description: "Optional media caption."
Buttons:
type: array
description: "Card-specific buttons."
minItems: 1
maxItems: 3
items:
type: object
required:
- Label
- Type
properties:
Id:
type: string
example: "buy_headphones"
description: "Button identifier for reply/copy buttons."
Label:
type: string
example: "Buy Now"
description: "Button display text."
Url:
type: string
example: "https://store.example.com/product/123"
description: "Destination URL for url buttons."
Type:
type: string
enum: [reply, url, copy, call]
example: "url"
description: "Button type."
Id:
type: string
example: "CAROUSEL_MSG_001"
description: "Custom message ID. Auto-generated when omitted."
Presence:
type: integer
example: 2000
description: "Typing simulation in milliseconds before sending."
NumberCheck:
type: boolean
example: true
description: "Verify that the recipient is registered on WhatsApp before sending."
ContextInfo:
$ref: "#/definitions/ContextInfo"
MessageSticker:
type: object
required:
- Phone
- Sticker
properties:
Phone:
type: string
example: "5521971532700"
description: "Phone number with country code"
Sticker:
type: string
example: "data:image/webp;base64,UklGRh4AAABXRUJQVlA4TBEAAAAvAAAAAAfQ//73v/+BiOh/AAA="
description: "Sticker data as base64 data URL (data:image/webp;base64,xxx) or HTTP(S) URL (https://example.com/sticker.webp)"
Id:
type: string
example: "ABCDABCD1234"
description: "Optional custom message ID"
MimeType:
type: string
example: "image/webp"
description: "Optional MIME type override (image/webp, image/jpeg, image/png, image/gif)"
PngThumbnail:
type: string
format: byte
description: "Optional PNG thumbnail as base64 string"
example: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
EchoApi:
type: boolean
example: true
description: "Optional. Set to true to force emission of API echo events for this specific message, regardless of global or per-session echo settings. When enabled, a synthetic Message event with Info.IsFromAPI=true will be emitted through your configured transports/webhook after the message is successfully sent. This allows individual message-level control over echo behavior, overriding both ECHO_API_MESSAGES_ENABLED (global) and the per-session echo_api_messages setting. Useful for selectively tracking specific API-sent messages through your event pipeline."
ContextInfo:
$ref: "#/definitions/ContextInfo"
MessageDocument:
type: object
required:
- Phone
- Document
- FileName
properties:
Phone:
type: string
example: "5521971532700"
description: "Phone number with country code"
Document:
type: string
example: "data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsO..."
description: "Document data as base64 data URL (data:application/pdf;base64,xxx) or HTTP(S) URL (https://example.com/document.pdf)"
FileName:
type: string
example: "document.pdf"
description: "Name of the document file with extension"
Caption:
type: string
example: "Important document"
description: "Optional caption for the document"
Id:
type: string
example: "ABCDABCD1234"
description: "Optional custom message ID"
MimeType:
type: string
example: "application/pdf"
description: "Optional MIME type override (application/pdf, application/msword, text/plain, etc.)"
Presence:
type: integer
example: 3000
description: "Milliseconds to simulate typing indicator"
Duration:
type: integer
example: 86400
description: "Message expiration time in seconds"
EchoApi:
type: boolean
example: true
description: "Optional. Set to true to force emission of API echo events for this specific message, regardless of global or per-session echo settings. When enabled, a synthetic Message event with Info.IsFromAPI=true will be emitted through your configured transports/webhook after the message is successfully sent. This allows individual message-level control over echo behavior, overriding both ECHO_API_MESSAGES_ENABLED (global) and the per-session echo_api_messages setting. Useful for selectively tracking specific API-sent messages through your event pipeline."
ContextInfo:
$ref: "#/definitions/ContextInfo"
DeleteMessage:
type: object
required:
- Id
- Phone
properties:
Phone:
type: string
example: "5521971532700"
Id:
type: string
example: "1234-abcd-21234"
Markread:
type: object
required:
- Id
- Chat
properties:
Id:
type: object
example: ["AABBCC11223344", "DDEEFF55667788"]
Chat:
type: string
example: 5491155553934.0:1@s.whatsapp.net
Sender:
type: string
example: 5491155553111.0:1@s.whatsapp.net
Pairphone:
type: object
required:
- Phone
properties:
Phone:
type: string
example: "5491155553934"
Checkuser:
type: object
required:
- Phone
properties:
Phone:
type: object
example: ["5491155553934", "5521971532700"]
Checkavatar:
type: object
required:
- Phone
- Preview
properties:
Phone:
type: string
description: "Phone number or JID to get profile picture for"
example: "5491155553934"
Preview:
type: bool
description: "If true, returns thumbnail/preview version. If false, returns full resolution picture"
example: true
IsCommunity:
type: boolean
description: "Set to true when getting profile picture of a WhatsApp Community (optional)"
example: false
CommonGID:
type: string
description: "Common group JID that you share with the target user. Allows getting profile picture of users through a shared group even if they have privacy settings that would normally prevent it. Format: 120363123456789012@g.us (optional)"
example: "120363123456789012@g.us"
InviteCode:
type: string
description: "Group invite code to query the profile photo of a group you haven't joined yet. Useful for previewing group information before joining (optional)"
example: "ABC123XYZ456"
PersonaID:
type: string
description: "Persona ID for getting profile pictures of Meta AI bots. Required when querying AI bot avatars (optional)"
example: "ai-bot-persona-id"
Webhook:
type: object
required:
- WebhookURL
properties:
WebhookURL:
type: string
example: http://server/webhook
WebhookSet:
type: object
required:
- webhook
- events
properties:
webhookurl:
type: string
description: The URL of the webhook
example: "https://example.net/webhook"
events:
type: array
items:
type: string
description: List of events to subscribe to. Available events include all 47 event types from Message, UndecryptableMessage, Receipt, MediaRetry, ReadReceipt, GroupInfo, JoinedGroup, Picture, BlocklistChange, Blocklist, Connected, Disconnected, ConnectFailure, KeepAliveRestored, KeepAliveTimeout, LoggedOut, ClientOutdated, TemporaryBan, StreamError, StreamReplaced, PairSuccess, PairError, QR, QRScannedWithoutMultidevice, PrivacySettings, PushNameSetting, UserAbout, AppState, AppStateSyncComplete, HistorySync, OfflineSyncCompleted, OfflineSyncPreview, CallOffer, CallAccept, CallTerminate, CallOfferNotice, CallRelayLatency, Presence, ChatPresence, IdentityChange, CATRefreshError, NewsletterJoin, NewsletterLeave, NewsletterMuteChange, NewsletterLiveUpdate, FBMessage, to All (which subscribes to all events)
example: ["Message", "ReadReceipt", "GroupInfo", "Connected", "All"]
WebhookUpdate:
type: object
properties:
webhookurl:
type: string
description: The URL of the webhook
example: "https://example.net/webhook"
events:
type: array
items:
type: string
description: List of events to subscribe to. Available events include all 47 event types from Message, UndecryptableMessage, Receipt, MediaRetry, ReadReceipt, GroupInfo, JoinedGroup, Picture, BlocklistChange, Blocklist, Connected, Disconnected, ConnectFailure, KeepAliveRestored, KeepAliveTimeout, LoggedOut, ClientOutdated, TemporaryBan, StreamError, StreamReplaced, PairSuccess, PairError, QR, QRScannedWithoutMultidevice, PrivacySettings, PushNameSetting, UserAbout, AppState, AppStateSyncComplete, HistorySync, OfflineSyncCompleted, OfflineSyncPreview, CallOffer, CallAccept, CallTerminate, CallOfferNotice, CallRelayLatency, Presence, ChatPresence, IdentityChange, CATRefreshError, NewsletterJoin, NewsletterLeave, NewsletterMuteChange, NewsletterLiveUpdate, FBMessage, to All (which subscribes to all events)
example: ["Message", "ReadReceipt", "GroupInfo", "Connected", "All"]
Active:
type: boolean
description: Whether the webhook should be active or not
example: true
GroupLeave:
type: object
required:
- GroupJID
properties:
GroupJID:
type: string
description: The JID of the group to leave (e.g., 120363312246943103@g.us)
example: 120363312246943103@g.us
GroupName:
type: object
required:
- GroupJID
- Name
properties:
GroupJID:
type: string
description: The JID of the group to rename
example: 120363312246943103@g.us
Name:
type: string
description: The new name for the group
example: My New Group Name
GroupTopic:
type: object
required:
- GroupJID
- Topic
properties:
GroupJID:
type: string
description: The JID of the group to set the topic for
example: 120363312246943103@g.us
Topic:
type: string
description: The new topic/description for the group
example: Welcome to our project group!
GroupAnnounce:
type: object
required:
- GroupJID
- Announce
properties:
GroupJID:
type: string
description: The JID of the group to set announce mode
example: 120363312246943103@g.us
Announce:
type: boolean
description: Whether to enable (true) or disable (false) announce mode
example: true
GroupJoin:
type: object
required:
- Code
properties:
Code:
type: string
description: The invite code or link to join the group
example: HffXhYmzzyJGec61oqMXiz
GroupInviteInfo:
type: object
required:
- Code
properties:
Code:
type: string
description: The group invite code to get information for
example: HffXhYmzzyJGec61oqMXiz
UpdateGroupParticipants:
type: object
required:
- GroupJID
- Action
- Phone
properties:
GroupJID:
type: string
description: The JID of the group
example: 120363312246943103@g.us
Action:
type: string
description: Action to perform ("add" to add participants, "remove" to remove participants, "promote" to promote participants, "demote" to demote participants.)
enum: [add, remove, promote, demote]
example: add
Phone:
type: array
items:
type: string
description: List of participant JIDs (e.g., 5491112345678@s.whatsapp.net or 5491112345678)
example: ["5491112345678", "5491123456789@s.whatsapp.net"]
CreateGroup:
type: object
required:
- Name
- Participants
properties:
Name:
type: string
description: The name for the new group
example: "My New Group"
Participants:
type: array
items:
type: string
description: List of participant phone numbers (without country code prefix symbols)
example: ["5491112345678", "5491123456789"]
GroupLocked:
type: object
required:
- GroupJID
- Locked
properties:
GroupJID:
type: string
description: The JID of the group to configure
example: "120363312246943103@g.us"
Locked:
type: boolean
description: Whether to lock the group (true) or unlock it (false). When locked, only admins can modify group info.
example: true
GroupEphemeral:
type: object
required:
- GroupJID
- Duration
properties:
GroupJID:
type: string
description: The JID of the group to configure ephemeral messages
example: "120363312246943103@g.us"
Duration:
type: string
description: Duration for disappearing messages. Use "24h" for 24 hours, "7d" for 7 days, "90d" for 90 days, or "off" to disable.
enum: ["24h", "7d", "90d", "off"]
example: "24h"
RemoveGroupPhoto:
type: object
required:
- GroupJID
properties:
GroupJID:
type: string
description: The JID of the group to remove the photo from
example: "120363312246943103@g.us"
SessionStatus:
type: object
description: "Current WhatsApp connection, session, and configuration state for the authenticated user"
properties:
id:
type: string
description: Unique identifier of the session/user
example: "bec45bb93cbd24cbec32941ec3c93a12"
name:
type: string
description: Display name associated with the session
example: "Some User"
avatar_url:
type: string
nullable: true
description: Cached avatar URL if available (valid for 24h)
example: "https://example.com/avatar.jpg"
connected:
type: boolean
description: Whether the WhatsApp client currently has an active websocket connection
example: true
loggedIn:
type: boolean
description: Whether the WhatsApp session is authenticated
example: true
hasClient:
type: boolean
description: Whether an active WhatsMeow client instance exists for this session
example: true
connectionHealth:
type: string
description: High-level status indicator of the connection
enum:
[
"unknown",
"no_client",
"disconnected",
"connected_not_logged",
"connected",
]
example: "connected"
lastSuccessfulConnect:
type: integer
format: int64
description: Unix timestamp of the last successful connection event (0 if never connected)
example: 1705312845
autoReconnectErrors:
type: integer
description: Number of automatic reconnect attempts that have failed consecutively
example: 0
enableAutoReconnect:
type: boolean
description: Indicates if automatic reconnect is enabled for this session
example: true
expiration:
type: integer
format: int64
description: Number of seconds remaining until the session token expires
example: 86400
token:
type: string
description: Authentication token for API access
example: "d030sl9aDL39sl3075zz"
jid:
type: string
description: WhatsApp JID currently associated with the session
example: "5491155551122:12@s.whatsapp.net"
webhook:
type: string
description: Configured webhook URL for outbound events
example: "https://some.domain/webhook"
events:
type: string
description: Event subscription filter applied to this session
example: "All"
proxy_url:
type: string
nullable: true
description: Legacy proxy URL string kept for backward compatibility
example: ""
qrcode:
type: string
description: Base64 QR code when an authentication QR is pending
example: ""
skip_media_download:
type: boolean
description: Whether media downloads are disabled for this session
example: false
skip_groups:
type: boolean
description: Whether group messages should be skipped
example: false
skip_newsletters:
type: boolean
description: Whether newsletter messages should be skipped
example: false
skip_broadcasts:
type: boolean
description: Whether broadcast messages should be skipped
example: false
skip_own_messages:
type: boolean
description: Whether messages sent by this account should be skipped
example: false
echo_api_messages:
type: boolean
description: Whether API-sent messages should be echoed back through transports
example: false
skip_calls:
type: boolean
description: Whether call events should be skipped
example: false
call_reject_message:
type: string
description: Optional automated response message when rejecting calls
example: "Sorry, I cannot take calls at the moment."
call_reject_type:
type: string
description: Strategy used to reject calls (e.g. busy, decline)
example: "busy"
globalTransportSkips:
$ref: "#/definitions/GlobalTransportSkipFlags"
description: "Snapshot of the per-transport global dispatcher skip flags."
isFromAPI:
type: boolean
description: "Reflects the Echo API configuration. When true, Info.IsFromAPI markers are emitted for API sends."
example: false
proxy_config:
$ref: "#/definitions/ProxyConfig"
s3_config:
$ref: "#/definitions/S3Config"
rabbitmq_config:
$ref: "#/definitions/RabbitMQConfig"
timestamp:
type: integer
format: int64
description: Unix timestamp when this status snapshot was generated
example: 1705312845
required:
- id
- connected
- loggedIn
- hasClient
- connectionHealth
- timestamp
ProxyConfig:
type: object
properties:
enabled:
type: boolean
description: Whether proxy usage is enabled for this session
example: false
proxy_url:
type: string
nullable: true
description: Proxy URL to be used when enabled (supports http/https/socks5)
example: "http://proxy.example.com:8080"
required:
- enabled
S3Config:
type: object
properties:
enabled:
type: boolean
description: Whether S3 storage is enabled
example: true
endpoint:
type: string
description: S3 endpoint URL (leave empty for AWS S3)
example: "https://s3.amazonaws.com"
region:
type: string
description: S3 region
example: "us-east-1"
bucket:
type: string
description: S3 bucket name
example: "my-whatsapp-media"
access_key:
type: string
description: S3 access key ID
example: "AKIAIOSFODNN7EXAMPLE"
secret_key:
type: string
description: S3 secret access key
example: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
path_style:
type: boolean
description: Use path-style URLs (required for MinIO)
example: false
public_url:
type: string
description: Custom public URL for accessing files (optional, for CDN)
example: "https://cdn.example.com"
media_delivery:
type: string
description: Media delivery method
enum: ["base64", "s3", "both"]
example: "both"
retention_days:
type: integer
description: Number of days to retain files (0 for no expiration)
disable_acl:
type: boolean
description: Set to true for AWS S3 buckets with "Bucket owner enforced" Object Ownership
example: true
RabbitMQConfig:
type: object
properties:
enabled:
type: boolean
description: Whether RabbitMQ publishing is enabled
example: true
url:
type: string
description: RabbitMQ connection URL in format amqp://username:password@host:port/vhost
example: "amqp://guest:guest@localhost:5672/"
exchange:
type: string
description: Exchange name for publishing events
example: "whatsapp.events"
exchange_type:
type: string
description: Exchange type for events (required when enabled)
enum: ["topic", "direct", "fanout", "headers"]
example: "topic"
queue:
type: string
description: "Queue name pattern with dynamic placeholders. Use {user_id} and {event_type} for automatic queue creation per event type. Examples: 'user_{user_id}_main' (static) or 'user_{user_id}_event_{event_type}' (dynamic per event)"
example: "user_{user_id}_event_{event_type}"
queue_type:
type: string
description: Queue type for events (required when enabled)
enum: ["classic", "quorum", "stream"]
example: "classic"
routing_key:
type: string
description: "Routing key pattern with dynamic placeholders. Use {user_id} and {event_type} for event-specific routing. Example: 'whatsapp.{user_id}.{event_type}' creates keys like 'whatsapp.abc123.Message'"
example: "whatsapp.{user_id}.{event_type}"
events:
type: string
description: 'Event types to publish (comma-separated or "All"). Available events include all 47 event types from Message, UndecryptableMessage, Receipt, MediaRetry, ReadReceipt, GroupInfo, JoinedGroup, Picture, BlocklistChange, Blocklist, Connected, Disconnected, ConnectFailure, KeepAliveRestored, KeepAliveTimeout, LoggedOut, ClientOutdated, TemporaryBan, StreamError, StreamReplaced, PairSuccess, PairError, QR, QRScannedWithoutMultidevice, PrivacySettings, PushNameSetting, UserAbout, AppState, AppStateSyncComplete, HistorySync, OfflineSyncCompleted, OfflineSyncPreview, CallOffer, CallAccept, CallTerminate, CallOfferNotice, CallRelayLatency, Presence, ChatPresence, IdentityChange, CATRefreshError, NewsletterJoin, NewsletterLeave, NewsletterMuteChange, NewsletterLiveUpdate, FBMessage, to All (which subscribes to all events). Event names are case-sensitive; CSV values with spaces are normalized (for example: "Message, Disconnected").'
example: "Message,ReadReceipt,Connected,All"
durable:
type: boolean
description: Whether the exchange and queue should be durable
example: true
auto_delete:
type: boolean
description: Whether the exchange and queue should auto-delete when unused
example: false
exclusive:
type: boolean
description: Whether the queue should be exclusive to this connection
example: false
no_wait:
type: boolean
description: Whether to use no-wait flag for faster operations
example: false
delivery_mode:
type: integer
description: Message delivery mode (1=non-persistent, 2=persistent)
enum: [1, 2]
example: 2
dead_letter_exchange:
type: string
description: Dead Letter Exchange name. Rejected or expired messages will be routed to this exchange.
example: "dlx.whatsapp"
dead_letter_routing_key:
type: string
description: Routing key for Dead Letter Exchange. Used when routing rejected/expired messages to DLQ.
example: "dlq.events"
message_ttl:
type: integer
format: int64
description: Message TTL (Time To Live) in milliseconds. Messages older than this will be discarded or sent to DLX if configured.
example: 86400000
max_length:
type: integer
format: int64
description: Maximum number of messages in the queue. Overflow behavior depends on x-overflow setting.
example: 100000
max_length_bytes:
type: integer
format: int64
description: Maximum total size of messages in the queue in bytes.
example: 104857600
queue_arguments:
type: object
additionalProperties: true
description: "Custom queue arguments as JSON object. Supports any RabbitMQ queue argument like x-overflow, x-queue-master-locator, etc."
example:
x-overflow: "reject-publish"
x-queue-master-locator: "min-masters"
exchange_arguments:
type: object
additionalProperties: true
description: "Custom exchange arguments as JSON object. Supports any RabbitMQ exchange argument."
example: {}
connection_pool_size:
type: integer
description: "Size of the connection pool for RabbitMQ connections. Higher values allow more concurrent operations. Default: 50"
example: 50
worker_count:
type: integer
description: "Number of concurrent workers for message publishing. Default: 100"
example: 100
queue_buffer_size:
type: integer
description: "In-memory queue buffer size for event batching before publishing. Default: 100000"
example: 100000
batch_size:
type: integer
description: "Number of events to batch together before publishing. Default: 1000"
example: 1000
batch_timeout_ms:
type: integer
description: "Maximum time in milliseconds to wait before publishing a partial batch. Default: 100"
example: 100
publish_timeout_ms:
type: integer
description: "Timeout in milliseconds for individual publish operations. Default: 5000"
example: 5000
max_retries:
type: integer
description: "Maximum number of retry attempts for failed publish operations. Default: 3"
example: 3
retry_delay_ms:
type: integer
description: "Delay in milliseconds between retry attempts. Default: 1000"
example: 1000
SkipMediaConfig:
type: object
required:
- enabled
properties:
enabled:
type: boolean
description: "Whether to skip downloading media files during WhatsApp events. When enabled, events will only contain metadata without base64 content or S3 uploads, improving performance."
example: true
example:
enabled: true
SkipGroupsConfig:
type: object
required:
- enabled
properties:
enabled:
type: boolean
description: "Whether to skip processing messages from WhatsApp groups. When enabled, the system will ignore all messages from group chats, processing only direct messages. This can improve performance and reduce processing overhead for applications that don't need group functionality."
example: true
example:
enabled: true
SkipNewslettersConfig:
type: object
required:
- enabled
properties:
enabled:
type: boolean
description: "Whether to skip processing messages from WhatsApp newsletters. When enabled, the system will ignore all messages from newsletter channels, processing only direct messages and groups. This can improve performance and reduce processing overhead for applications that don't need newsletter functionality."
example: true
example:
enabled: true
SkipBroadcastsConfig:
type: object
required:
- enabled
properties:
enabled:
type: boolean
description: "Whether to skip processing messages from WhatsApp broadcasts and status updates. When enabled, the system will ignore all messages from broadcast lists and status updates, processing only direct messages, groups, and newsletters. This can improve performance and reduce processing overhead for applications that don't need broadcast functionality."
example: true
example:
enabled: true
SkipCallsConfig:
type: object
required:
- enabled
properties:
enabled:
type: boolean
description: "Whether to automatically reject incoming WhatsApp calls. When enabled, all incoming calls will be automatically rejected and an optional message will be sent to the caller."
example: true
reject_message:
type: string
description: "Optional message to send to the caller after automatically rejecting the call. If not provided, a default message will be used."
example: "Sorry, I cannot take calls at the moment. Please send a message."
reject_type:
type: string
description: "Type of call rejection to use when automatically rejecting calls."
enum: ["busy", "declined", "unavailable"]
example: "busy"
example:
enabled: true
reject_message: "Sorry, I cannot take calls at the moment. Please send a message."
reject_type: "busy"
SkipOwnMessagesConfig:
type: object
required:
- enabled
properties:
enabled:
type: boolean
description: "Whether to skip processing your own sent messages (IsFromMe: true). When enabled, the system will ignore all messages that were sent by you, processing only messages received from others. This can improve performance and reduce processing overhead for applications that don't need to track outgoing messages."
example: true
example:
enabled: true
MessageEdit:
type: object
required:
- Id
- Phone
- Body
properties:
Id:
type: string
example: "90B2F8B13FAC8A9CF6B06E99C7834DC5"
description: "Message ID to edit"
Phone:
type: string
example: "5521971532700"
description: "Phone number with country code"
Body:
type: string
example: "This is the updated message"
description: "New message content"
ContextInfo:
type: object
description: "Optional context info for replies"
properties:
StanzaId:
type: string
example: "3EB06F9067F80BAB89FF"
description: "Message ID to reply to"
Participant:
type: string
example: "5521971532700@s.whatsapp.net"
description: "JID of original message sender"
IsForwarded:
type: boolean
example: true
description: "Set to true to mark the message as forwarded. This is the preferred method for forwarding messages."
MentionedJID:
type: array
items:
type: string
example:
["5521971532700@s.whatsapp.net", "5491155553934@s.whatsapp.net"]
description: "Array of JIDs to mention in the message. Use full WhatsApp JID format (number@s.whatsapp.net)."
MentionAll:
type: boolean
example: true
description: "Set to true to mention all group members"
GlobalTestEvent:
type: object
properties:
event_type:
type: string
description: "Type of test event to send"
example: "AdminTest"
default: "TestEvent"
user_id:
type: string
description: "User ID for the test event"
example: "admin-test"
default: "admin-test"
user_token:
type: string
description: "User token for the test event (optional, defaults to user_id if not provided)"
example: "admin-test-token"
data:
type: object
description: "Custom data to include in the test event"
additionalProperties: true
example:
{
"test": true,
"message": "This is a test event",
"timestamp": 1705312845,
}
example:
event_type: "AdminTest"
user_id: "admin-test"
user_token: "admin-test-token"
data:
test: true
message: "This is a test event sent from the admin panel"
CallRejectRequest:
type: object
required:
- call_id
- call_from
- reject_type
properties:
call_id:
type: string
description: "The unique identifier of the call to reject"
example: "call_12345_abcd"
call_from:
type: string
description: "The JID (phone number) of the caller in WhatsApp format"
example: "5521971532700@s.whatsapp.net"
reject_type:
type: string
description: "The type of rejection to send"
enum: ["busy", "declined", "unavailable"]
example: "busy"
message:
type: string
description: "Optional custom message to send to the caller after rejecting"
example: "Sorry, I'm currently busy and cannot take your call right now. I'll call you back later."
example:
call_id: "call_12345_abcd"
call_from: "5521971532700@s.whatsapp.net"
reject_type: "busy"
message: "Sorry, I'm currently busy and cannot take your call right now. I'll call you back later."
GetLIDRequest:
type: object
required:
- phone
properties:
phone:
type: string
description: "Phone number or JID to convert to LID"
example: "5521971532700@s.whatsapp.net"
GetJIDFromLIDRequest:
type: object
required:
- lid
properties:
lid:
type: string
description: "LID (Link ID) to convert to phone/JID"
example: "2:abcd1234efgh5678@lid"
LIDResponse:
type: object
properties:
success:
type: boolean
example: true
phone:
type: string
description: "Original phone/JID provided"
example: "5521971532700@s.whatsapp.net"
lid:
type: string
description: "Generated LID (Link ID)"
example: "2:abcd1234efgh5678@lid"
created_at:
type: integer
format: int64
description: "Unix timestamp when LID was created"
example: 1640995200
message:
type: string
description: "Success message"
example: "LID retrieved successfully"
JIDFromLIDResponse:
type: object
properties:
success:
type: boolean
example: true
lid:
type: string
description: "Original LID provided"
example: "2:abcd1234efgh5678@lid"
phone:
type: string
description: "Phone/JID corresponding to the LID"
example: "5521971532700@s.whatsapp.net"
created_at:
type: integer
format: int64
description: "Unix timestamp when LID was created"
example: 1640995200
message:
type: string
description: "Success message"
example: "Phone/JID retrieved successfully"
LIDMapping:
type: object
properties:
id:
type: integer
description: "Unique mapping ID"
example: 1
phone:
type: string
description: "Phone number or JID"
example: "5521971532700@s.whatsapp.net"
lid:
type: string
description: "Corresponding LID (Link ID)"
example: "2:abcd1234efgh5678@lid"
created_at:
type: integer
format: int64
description: "Unix timestamp when mapping was created"
example: 1640995200
last_used:
type: integer
format: int64
description: "Unix timestamp when mapping was last used"
example: 1640995500
usage_count:
type: integer
description: "Number of times this mapping has been used"
example: 5
LIDMappingsResponse:
type: object
properties:
success:
type: boolean
example: true
total:
type: integer
description: "Total number of mappings for the user"
example: 150
limit:
type: integer
description: "Maximum number of mappings returned"
example: 100
offset:
type: integer
description: "Number of mappings skipped"
example: 0
mappings:
type: array
items:
$ref: "#/definitions/LIDMapping"
description: "Array of LID mappings"
message:
type: string
description: "Success message"
example: "LID mappings retrieved successfully"
StatusText:
type: object
required:
- text
properties:
text:
type: string
description: "Text content for the status (maximum 650 characters)"
maxLength: 650
example: "Hello World! This is my status update 🌟"
background_color:
type: string
description: "Background color in ARGB decimal format. Use https://argb-int-calculator.netlify.app/ to generate"
example: "4294967295"
text_color:
type: string
description: "Text color in ARGB decimal format. Use https://argb-int-calculator.netlify.app/ to generate"
example: "4278190080"
font:
type: integer
description: "Font type (0: SYSTEM, 1: SYSTEM_TEXT, 2: FB_SCRIPT, 6: SYSTEM_BOLD, 7: MORNINGBREEZE_REGULAR, 8: CALISTOGA_REGULAR, 9: EXO2_EXTRABOLD, 10: COURIERPRIME_BOLD)"
minimum: 0
maximum: 10
example: 0
id:
type: string
description: "Optional custom message ID"
example: "custom-status-id-123"
example:
text: "Hello World! This is my status update 🌟"
background_color: "4294967295"
text_color: "4278190080"
font: 7
id: "custom-status-id-123"
StatusImage:
type: object
required:
- image
properties:
image:
type: string
description: "Base64 encoded image data (data:image/jpeg;base64,...) or HTTP(S) URL. Supported formats: JPEG, PNG, GIF, WebP"
example: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
caption:
type: string
description: "Optional caption text for the image"
example: "Beautiful sunset today! 🌅"
id:
type: string
description: "Optional custom message ID"
example: "status-image-123"
example:
image: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
caption: "Beautiful sunset today! 🌅"
id: "status-image-123"
StatusVideo:
type: object
required:
- video
properties:
video:
type: string
description: "Base64 encoded video data (data:video/mp4;base64,...) or HTTP(S) URL. Supported formats: MP4, 3GPP. Requires H.264 video codec and AAC audio codec"
example: "data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDE..."
caption:
type: string
description: "Optional caption text for the video"
example: "Check out this amazing video! 🎬"
id:
type: string
description: "Optional custom message ID"
example: "status-video-123"
example:
video: "data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDE..."
caption: "Check out this amazing video! 🎬"
id: "status-video-123"
StatusAudio:
type: object
required:
- audio
properties:
audio:
type: string
description: "Base64 encoded audio data (data:audio/ogg;base64,...) or HTTP(S) URL. Supported formats: OGG with Opus codec, MP3, M4A"
example: "data:audio/ogg;base64,T2dnUwACAAAAAAAAAABK/wAAAAAAAIAuABBT..."
caption:
type: string
description: "Optional caption text for the audio"
example: "Listen to this! 🎵"
ptt:
type: boolean
description: "Set to true to send as voice note (Push-To-Talk), false for regular audio"
default: false
example: false
id:
type: string
description: "Optional custom message ID"
example: "status-audio-123"
example:
audio: "data:audio/ogg;base64,T2dnUwACAAAAAAAAAABK/wAAAAAAAIAuABBT..."
caption: "Listen to this! 🎵"
ptt: false
id: "status-audio-123"
ChangePushNameRequest:
type: object
required:
- push_name
properties:
push_name:
type: string
description: "New push name for the user"
example: "John Doe"
example:
push_name: "John Doe"
SetMyStatusRequest:
type: object
required:
- status
properties:
status:
type: string
description: "New status message for the user"
example: "Working from home 🏠"
example:
status: "Working from home 🏠"
SetProfilePhoto:
type: object
required:
- Image
properties:
Image:
type: string
description: |
Image data to set as profile photo. Accepts two formats:
- **Base64 data URL**: `data:image/jpeg;base64,/9j/4AAQ...` (inline JPEG encoded as data URL)
- **HTTP/HTTPS URL**: `https://example.com/photo.jpg` (remote image, downloaded server-side)
**Image requirements:**
- Format: JPEG only (`.jpg` / `.jpeg`). PNG, GIF, WebP are NOT accepted by WhatsApp
- Maximum resolution: 640x640 pixels
- Recommended aspect ratio: 1:1 (square)
- Recommended file size: under 5MB
example: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
example:
Image: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
BusinessProfileRequest:
type: object
required:
- phone
properties:
phone:
type: string
description: "Phone number of the WhatsApp Business account to get profile information"
example: "5491155553934"
example:
phone: "5491155553934"
UserInfoImprovedResponse:
type: object
properties:
code:
type: integer
example: 200
data:
type: object
properties:
jid:
type: string
description: "User's WhatsApp JID"
example: "5491155553934@s.whatsapp.net"
status:
type: string
description: "User's current status message"
example: "Available for work 💼"
picture_id:
type: string
description: "Profile picture ID"
example: "1582328807"
verified_name:
type: string
description: "Verified business name (if available)"
example: "Company Name"
devices:
type: array
items:
type: object
properties:
user:
type: string
description: "User number"
example: "5491155553934"
agent:
type: string
description: "Device agent ID"
example: "25"
device:
type: string
description: "Device platform name"
example: "CHROME"
server:
type: string
description: "Server domain"
example: "s.whatsapp.net"
ad:
type: string
description: "Advertisement string"
example: "5491155553934.0:6@s.whatsapp.net"
success:
type: boolean
example: true
example:
code: 200
data:
jid: "5491155553934@s.whatsapp.net"
status: "Available for work 💼"
picture_id: "1582328807"
verified_name: "Company Name"
devices:
- user: "5491155553934"
agent: "25"
device: "CHROME"
server: "s.whatsapp.net"
ad: "5491155553934.0:6@s.whatsapp.net"
- user: "5491155553934"
agent: "15"
device: "DESKTOP"
server: "s.whatsapp.net"
ad: "5491155553934.0:0@s.whatsapp.net"
success: true
# Community Schemas
LinkGroupRequest:
type: object
required:
- parent_jid
- child_jid
properties:
parent_jid:
type: string
description: "JID of the parent community"
example: "120363025246487852@newsletter"
child_jid:
type: string
description: "JID of the child group to link"
example: "120363312246943103@g.us"
example:
parent_jid: "120363025246487852@newsletter"
child_jid: "120363312246943103@g.us"
UnlinkGroupRequest:
type: object
required:
- parent_jid
- child_jid
properties:
parent_jid:
type: string
description: "JID of the parent community"
example: "120363025246487852@newsletter"
child_jid:
type: string
description: "JID of the child group to unlink"
example: "120363312246943103@g.us"
example:
parent_jid: "120363025246487852@newsletter"
child_jid: "120363312246943103@g.us"
LinkedGroupsRequest:
type: object
required:
- community_jid
properties:
community_jid:
type: string
description: "JID of the community"
example: "120363025246487852@newsletter"
example:
community_jid: "120363025246487852@newsletter"
LinkedGroupsResponse:
type: object
properties:
success:
type: boolean
example: true
community_jid:
type: string
example: "120363025246487852@newsletter"
linked_groups:
type: array
items:
type: string
description: "Array of linked group JIDs"
example: ["120363312246943103@g.us", "120363417042313103@g.us"]
count:
type: integer
example: 2
description: "Number of linked groups"
example:
success: true
community_jid: "120363025246487852@newsletter"
linked_groups: ["120363312246943103@g.us", "120363417042313103@g.us"]
count: 2
GroupRequestsRequest:
type: object
required:
- group_jid
properties:
group_jid:
type: string
description: "JID of the group to get join requests for"
example: "120363312246943103@g.us"
example:
group_jid: "120363312246943103@g.us"
GroupRequestsResponse:
type: object
properties:
success:
type: boolean
example: true
group_jid:
type: string
example: "120363312246943103@g.us"
requests:
type: array
items:
type: object
properties:
jid:
type: string
example: "5491155553934@s.whatsapp.net"
request_time:
type: integer
format: int64
example: 1640995200
description: "Unix timestamp when request was made"
description: "Array of pending join requests"
count:
type: integer
example: 3
description: "Number of pending requests"
example:
success: true
group_jid: "120363312246943103@g.us"
requests:
- jid: "5491155553934@s.whatsapp.net"
request_time: 1640995200
- jid: "5521971532700@s.whatsapp.net"
request_time: 1640995300
count: 2
UpdateGroupRequestsRequest:
type: object
required:
- group_jid
- action
- participants
properties:
group_jid:
type: string
description: "JID of the group"
example: "120363312246943103@g.us"
action:
type: string
enum: [approve, reject]
description: "Action to perform on join requests"
example: "approve"
participants:
type: array
items:
type: string
description: "Array of participant JIDs to approve/reject"
example:
["5491155553934@s.whatsapp.net", "5521971532700@s.whatsapp.net"]
example:
group_jid: "120363312246943103@g.us"
action: "approve"
participants:
["5491155553934@s.whatsapp.net", "5521971532700@s.whatsapp.net"]
CreateCommunityRequest:
type: object
required:
- name
properties:
name:
type: string
description: "Name of the new community"
example: "My Community"
description:
type: string
description: "Optional community description"
example: "A community for our organization"
initial_groups:
type: array
items:
type: string
description: "Optional array of group JIDs to link immediately"
example: ["120363312246943103@g.us", "120363417042313103@g.us"]
example:
name: "My Community"
description: "A community for our organization"
initial_groups: ["120363312246943103@g.us"]
CreateCommunityResponse:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "Community created successfully"
community_jid:
type: string
example: "120363025246487852@newsletter"
name:
type: string
example: "My Community"
linked_groups:
type: array
items:
type: string
description: "Array of initially linked group JIDs"
example: ["120363312246943103@g.us"]
linked_count:
type: integer
example: 1
description: "Number of groups linked during creation"
example:
success: true
message: "Community created successfully"
community_jid: "120363025246487852@newsletter"
name: "My Community"
linked_groups: ["120363312246943103@g.us"]
linked_count: 1
CommunityAnnouncementRequest:
type: object
required:
- community_jid
- message
properties:
community_jid:
type: string
description: "JID of the community"
example: "120363025246487852@newsletter"
message:
type: string
description: "Announcement message text"
example: "Important community announcement for all members"
example:
community_jid: "120363025246487852@newsletter"
message: "Important community announcement for all members"
CommunityAnnouncementResponse:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "Announcement sent successfully"
community_jid:
type: string
example: "120363025246487852@newsletter"
announcement_text:
type: string
example: "Important community announcement for all members"
sent_to_groups:
type: integer
example: 3
description: "Number of linked groups that received the announcement"
example:
success: true
message: "Announcement sent successfully"
community_jid: "120363025246487852@newsletter"
announcement_text: "Important community announcement for all members"
sent_to_groups: 3
# Business Schemas
ResolveBusinessLinkRequest:
type: object
required:
- business_link
properties:
business_link:
type: string
description: "WhatsApp Business message link to resolve"
example: "https://wa.me/message/ABCDEFG123456"
example:
business_link: "https://wa.me/message/ABCDEFG123456"
BusinessLinkInfo:
type: object
properties:
success:
type: boolean
example: true
business_link:
type: string
example: "https://wa.me/message/ABCDEFG123456"
business_jid:
type: string
example: "5491155553934@s.whatsapp.net"
business_name:
type: string
example: "My Business"
verified:
type: boolean
example: true
description: "Whether the business is verified"
category:
type: string
example: "Retail"
description:
type: string
example: "Premium retail store"
website:
type: string
example: "https://mybusiness.com"
email:
type: string
example: "contact@mybusiness.com"
address:
type: string
example: "123 Main St, City, Country"
example:
success: true
business_link: "https://wa.me/message/ABCDEFG123456"
business_jid: "5491155553934@s.whatsapp.net"
business_name: "My Business"
verified: true
category: "Retail"
description: "Premium retail store"
ContactQRRequest:
type: object
required:
- phone
properties:
phone:
type: string
description: "Phone number to generate QR code for"
example: "5491155553934"
revoke:
type: boolean
description: "Whether to revoke existing QR codes before generating new one"
example: false
default: false
example:
phone: "5491155553934"
revoke: false
ContactQRResponse:
type: object
properties:
success:
type: boolean
example: true
phone:
type: string
example: "5491155553934"
qr_link:
type: string
example: "https://wa.me/qr/ABCDEFG123456"
description: "QR code link that can be used to add contact or start conversation"
revoked_previous:
type: boolean
example: false
description: "Whether previous QR codes were revoked"
example:
success: true
phone: "5491155553934"
qr_link: "https://wa.me/qr/ABCDEFG123456"
revoked_previous: false
BotInfo:
type: object
properties:
jid:
type: string
example: "5491155553934@s.whatsapp.net"
name:
type: string
example: "Support Bot"
description:
type: string
example: "Automated customer support assistant"
verified:
type: boolean
example: true
example:
jid: "5491155553934@s.whatsapp.net"
name: "Support Bot"
description: "Automated customer support assistant"
verified: true
BotProfilesRequest:
type: object
required:
- bot_jids
properties:
bot_jids:
type: array
items:
type: string
description: "Array of bot JIDs to get profiles for"
example:
["5491155553934@s.whatsapp.net", "5521971532700@s.whatsapp.net"]
example:
bot_jids: ["5491155553934@s.whatsapp.net", "5521971532700@s.whatsapp.net"]
BotProfileInfo:
type: object
properties:
jid:
type: string
example: "5491155553934@s.whatsapp.net"
name:
type: string
example: "Support Bot"
description:
type: string
example: "Automated customer support assistant"
verified:
type: boolean
example: true
avatar_url:
type: string
example: "https://example.com/bot-avatar.jpg"
capabilities:
type: array
items:
type: string
example: ["messaging", "automation", "customer_support"]
commands:
type: array
items:
type: object
properties:
command:
type: string
example: "/help"
description:
type: string
example: "Show available commands"
description: "Available bot commands"
example:
jid: "5491155553934@s.whatsapp.net"
name: "Support Bot"
description: "Automated customer support assistant"
verified: true
avatar_url: "https://example.com/bot-avatar.jpg"
capabilities: ["messaging", "automation"]
commands:
- command: "/help"
description: "Show available commands"
SendOrderRequest:
type: object
required:
- phone
- items
properties:
phone:
type: string
description: "Phone number of the business"
example: "5491155553934"
items:
type: array
items:
type: object
required:
- name
- quantity
- price
properties:
name:
type: string
example: "Product Name"
description: "Name of the product"
quantity:
type: integer
example: 2
description: "Quantity of the product"
price:
type: number
format: float
example: 19.99
description: "Price per unit"
currency:
type: string
example: "USD"
default: "USD"
description: "Currency code (ISO 4217)"
image_url:
type: string
example: "https://example.com/product.jpg"
description: "Optional product image URL"
description: "Array of order items"
notes:
type: string
description: "Optional order notes or special instructions"
example: "Please deliver in the morning"
example:
phone: "5491155553934"
items:
- name: "Product A"
quantity: 2
price: 19.99
currency: "USD"
- name: "Product B"
quantity: 1
price: 29.99
currency: "USD"
notes: "Please deliver in the morning"
OrderResponse:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "Order message sent successfully"
phone:
type: string
example: "5491155553934"
order_id:
type: string
example: "ORD123456789"
description: "Generated order ID"
items_count:
type: integer
example: 2
description: "Number of items in the order"
total_amount:
type: number
format: float
example: 69.97
description: "Total order amount"
example:
success: true
message: "Order message sent successfully"
phone: "5491155553934"
order_id: "ORD123456789"
items_count: 2
total_amount: 69.97
# Device Schemas
UserDevicesRequest:
type: object
required:
- jids
properties:
jids:
type: array
items:
type: string
description: "Array of user JIDs to get device information for"
example:
["5491155553934@s.whatsapp.net", "5521971532700@s.whatsapp.net"]
example:
jids: ["5491155553934@s.whatsapp.net", "5521971532700@s.whatsapp.net"]
DeviceInfo:
type: object
properties:
jid:
type: string
example: "5491155553934@s.whatsapp.net"
description: "User JID"
devices:
type: array
items:
type: object
properties:
device_id:
type: integer
example: 0
description: "Device ID (0 for main device)"
platform:
type: string
example: "CHROME"
description: "Device platform (CHROME, SAFARI, FIREFOX, EDGE, DESKTOP, etc.)"
description: "Array of devices for this user"
example:
jid: "5491155553934@s.whatsapp.net"
devices:
- device_id: 0
platform: "CHROME"
- device_id: 1
platform: "DESKTOP"
LinkedDevicesResponse:
type: object
properties:
success:
type: boolean
example: true
linked_devices:
type: array
items:
type: object
properties:
device_id:
type: integer
example: 0
platform:
type: string
example: "CHROME"
connected:
type: boolean
example: true
description: "Array of linked devices for current user"
count:
type: integer
example: 2
description: "Number of linked devices"
example:
success: true
linked_devices:
- device_id: 0
platform: "CHROME"
connected: true
- device_id: 1
platform: "DESKTOP"
connected: true
count: 2
DevicePlatformRequest:
type: object
required:
- device_id
properties:
device_id:
type: integer
description: "Device ID to get platform for"
example: 0
example:
device_id: 0
DevicePlatformResponse:
type: object
properties:
success:
type: boolean
example: true
device_id:
type: integer
example: 0
platform:
type: string
example: "CHROME"
description: "Platform name (CHROME, SAFARI, FIREFOX, EDGE, DESKTOP, IOS, ANDROID, etc.)"
example:
success: true
device_id: 0
platform: "CHROME"
# Privacy Schemas
SetPrivacySettingRequest:
type: object
required:
- setting
- value
properties:
setting:
type: string
enum:
[
group_add,
last_seen,
status,
profile,
read_receipts,
online,
call_add,
]
description: "Privacy setting to update"
example: "last_seen"
value:
type: string
enum: [all, contacts, contact_blacklist, none]
description: "Privacy value (all=everyone, contacts=contacts only, contact_blacklist=contacts except, none=nobody)"
example: "contacts"
users:
type: array
items:
type: string
description: "Optional array of user JIDs for blacklist/whitelist (not currently supported in API)"
example: ["5491155553934@s.whatsapp.net"]
example:
setting: "last_seen"
value: "contacts"
PrivacySettingsResponse:
type: object
properties:
success:
type: boolean
example: true
privacy_settings:
type: object
properties:
group_add:
type: string
example: "contacts"
description: "Who can add you to groups"
last_seen:
type: string
example: "contacts"
description: "Who can see your last seen"
status:
type: string
example: "contacts"
description: "Who can see your status updates"
profile:
type: string
example: "contacts"
description: "Who can see your profile photo"
read_receipts:
type: string
example: "all"
description: "Whether to send read receipts"
online:
type: string
example: "all"
description: "Who can see when you're online"
call_add:
type: string
example: "contacts"
description: "Who can call you"
example:
success: true
privacy_settings:
group_add: "contacts"
last_seen: "contacts"
status: "contacts"
profile: "contacts"
read_receipts: "all"
online: "all"
call_add: "contacts"
DisappearingTimerRequest:
type: object
required:
- timer
properties:
timer:
type: string
enum: ["24h", "7d", "90d", "off"]
description: "Disappearing message timer duration"
example: "24h"
example:
timer: "24h"
UpdateBlocklistRequest:
type: object
required:
- action
- users
properties:
action:
type: string
enum: [block, unblock]
description: "Action to perform (block or unblock)"
example: "block"
users:
type: array
items:
type: string
description: "Array of phone numbers or JIDs to block/unblock"
example: ["5491155553934", "5521971532700@s.whatsapp.net"]
example:
action: "block"
users: ["5491155553934", "5521971532700"]
BlocklistResponse:
type: object
properties:
success:
type: boolean
example: true
blocked_contacts:
type: array
items:
type: string
description: "Array of blocked contact JIDs"
example:
["5491155553934@s.whatsapp.net", "5521971532700@s.whatsapp.net"]
count:
type: integer
example: 2
description: "Number of blocked contacts"
example:
success: true
blocked_contacts:
["5491155553934@s.whatsapp.net", "5521971532700@s.whatsapp.net"]
count: 2
StatusPrivacyResponse:
type: object
properties:
success:
type: boolean
example: true
status_privacy:
type: string
example: "contacts"
description: "Current status privacy setting (all, contacts, contact_blacklist, or none)"
description:
type: string
example: "Status privacy setting (all, contacts, contact_blacklist, or none)"
example:
success: true
status_privacy: "contacts"
description: "Status privacy setting (all, contacts, contact_blacklist, or none)"
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: token
AdminAuth:
type: apiKey
in: header
name: Authorization
security:
- ApiKeyAuth: []