GOWA - WhatsApp REST API with support for UI, Multi Account, Webhooks, and MCP, and Chatwoot. Built with Golang for efficient memory use.
Go botgogolanggolang-whatsappgolang-whatsapp-apirestrest-apiwhatsappwhatsapp-apiwhatsapp-api-gowhatsapp-multi-devicewhatsapp-web-multi-device
openapi: "3.0.0"
info:
title: WhatsApp API MultiDevice
version: "9.7.0"
description: |
This API is used for sending whatsapp via API.
The web dashboard is a separate project (gowa-ui); the server downloads its
latest release asset and serves it at `/` (or returns a JSON banner when
APP_UI_ENABLED=false).
Device scoping:
- Send `X-Device-Id` on all device-scoped REST calls.
- WebSocket: connect to `/ws?device_id=<id>`.
- WebSocket auth (when basic auth is enabled): browsers cannot set an
Authorization header on WebSocket connections, so also pass
`&authorization=<base64(user:pass)>` in the query string. Use TLS in
production since the credential is visible in the URL.
servers:
- url: http://localhost:3000
tags:
- name: app
description: Initial Connection to Whatsapp server
- name: device
description: Device management for multi-device support
- name: user
description: Getting information
- name: send
description: Send Message (Text/Image/File/Video).
- name: message
description: Message manipulation (revoke/react/update).
- name: call
description: Call management (reject incoming calls)
- name: chat
description: Chat conversations and messaging
- name: group
description: Group setting
- name: newsletter
description: newsletter setting
- name: chatwoot
description: Chatwoot integration for customer support
security:
- basicAuth: []
paths:
/health:
get:
operationId: health
tags:
- app
summary: Health check
description: Public health probe registered at `/health`; it is not prefixed by `APP_BASE_PATH`.
security: []
responses:
'200':
description: Service healthy
content:
text/plain:
schema:
type: string
example: OK
'503':
description: Service unavailable
content:
text/plain:
schema:
type: string
example: Service Unavailable
/app/login:
get:
operationId: appLogin
tags:
- app
summary: Login to whatsapp server
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LoginResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/app/login-with-code:
get:
operationId: appLoginWithCode
tags:
- app
summary: Login with pairing code
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: phone
in: query
schema:
type: string
example: '628912344551'
description: Your phone number
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LoginWithCodeResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/app/passkey:
get:
operationId: appPasskeyStatus
tags:
- app
summary: Get pending passkey pairing state
description: >
Passkey pairing is initiated from the phone during QR login. When the phone requests it,
the server sends a WebAuthn challenge which is stored here (also broadcast over the
websocket as PASSKEY_REQUEST) until a response is submitted.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyStatusResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/app/passkey/response:
post:
operationId: appPasskeyResponse
tags:
- app
summary: Submit the WebAuthn assertion for passkey pairing
description: >
Send the WebAuthn assertion produced for the pending challenge (see GET /app/passkey).
The assertion must be produced by an authenticator holding the WhatsApp account's passkey,
against WhatsApp's relying-party ID; the payload format matches PublicKeyCredential.toJSON().
If the assertion is submitted within the 5-minute handoff window, pairing is confirmed
automatically; otherwise a confirmation code is issued (PASSKEY_CONFIRMATION websocket event)
and must be confirmed via POST /app/passkey/confirm.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebAuthnAssertion'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/app/passkey/confirm:
post:
operationId: appPasskeyConfirm
tags:
- app
summary: Confirm the passkey pairing code
description: >
Confirms that the pairing code from the PASSKEY_CONFIRMATION event was shown to the user
and matches the code displayed on the phone. Only needed when skip_handoff_ux is false.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/app/logout:
get:
operationId: appLogout
tags:
- app
summary: Logout the active device (keeps the device slot)
description: >-
Logs the active device out of WhatsApp and clears its session. The device
slot (id and display name) is kept, so it stays listed (disconnected) and
can be re-paired under the same id. Use DELETE /devices/{device_id} to remove the slot.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/app/reconnect:
get:
operationId: appReconnect
tags:
- app
summary: Reconnecting to whatsapp server
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/app/devices:
get:
operationId: appDevices
tags:
- app
summary: Get list connected devices
description: >
Returns all device IDs known to the server, including placeholders
created via the device API. Devices are now persisted in the storage
registry so IDs remain stable after application restarts.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/app/status:
get:
operationId: appStatus
tags:
- app
summary: Get connection status
description: Check whether the WhatsApp client is connected and logged in
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
type: integer
example: 200
code:
type: string
example: SUCCESS
message:
type: string
example: Connection status retrieved
results:
type: object
properties:
is_connected:
type: boolean
description: Whether the device is connected to WhatsApp servers
is_logged_in:
type: boolean
description: Whether the device is logged in to WhatsApp
device_id:
type: string
description: Session ID registered via POST /devices
example: 'org_2'
jid:
type: string
description: WhatsApp JID of the logged-in account (empty until login)
example: '[email protected]'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/app/metrics:
get:
operationId: appMetrics
tags:
- app
summary: Get server health metrics
description: >
Memory of the process and of its container (cgroup v2, then v1), CPU
time, size of statics/media and storages (walk cached for a minute),
free space on the volume, the session store and how many devices are
registered, logged in and connected. Requires no device. Nullable fields
are unknown on the current platform (non-Linux) or unlimited (container
memory limit). Folder usage is best effort: missing or unreadable entries
are omitted, and symlink targets are not traversed. Container metrics use
the standard /sys/fs/cgroup mount and are null when unavailable. Uptime
includes process initialization.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status: { type: integer, example: 200 }
code: { type: string, example: SUCCESS }
message: { type: string, example: Fetch app metrics success }
results:
type: object
properties:
version: { type: string, example: v9.6.0 }
session_store: { type: string, enum: [sqlite, postgres] }
devices:
type: object
properties:
total: { type: integer, example: 5 }
logged_in: { type: integer, example: 3 }
connected: { type: integer, example: 3 }
system:
type: object
properties:
started_at: { type: string, format: date-time }
uptime_seconds: { type: integer, example: 3600 }
go_version: { type: string, example: go1.26.9 }
cpu_seconds: { type: number, nullable: true, example: 17.9 }
memory:
type: object
properties:
heap_alloc_bytes: { type: integer, format: int64 }
runtime_sys_bytes: { type: integer, format: int64 }
process_rss_bytes: { type: integer, format: int64, nullable: true }
container_bytes: { type: integer, format: int64, nullable: true }
container_limit_bytes: { type: integer, format: int64, nullable: true }
goroutines: { type: integer }
gc_cycles: { type: integer }
folders:
type: object
additionalProperties:
type: object
properties:
bytes: { type: integer, format: int64 }
files: { type: integer, format: int64 }
filesystem:
type: object
properties:
total_bytes: { type: integer, format: int64, nullable: true }
free_bytes: { type: integer, format: int64, nullable: true }
/app/info:
get:
operationId: appInfo
tags:
- app
summary: Get server metadata
description: >
Returns server version, base path, media size limits, and enabled
features. Requires no device; intended for standalone UIs (gowa-ui)
that previously read these values from the embedded dashboard HTML.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
type: integer
example: 200
code:
type: string
example: SUCCESS
message:
type: string
example: Fetch app info success
results:
type: object
properties:
version:
type: string
example: 'v9.0.0'
os:
type: string
example: 'GOWA'
base_path:
type: string
example: ''
max_file_size:
type: integer
format: int64
description: Max document upload size in bytes
example: 50000000
max_video_size:
type: integer
format: int64
description: Max video upload size in bytes
example: 100000000
max_image_size:
type: integer
format: int64
description: Max image upload size in bytes
example: 20000000
chatwoot_enabled:
type: boolean
description: Whether Chatwoot integration routes are registered
scheduled_sends:
type: boolean
description: Whether send endpoints accept schedule fields and the /send/schedules routes exist
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
# Device Management API (v8)
/devices:
get:
operationId: listDevices
tags:
- device
summary: List all devices
description: Returns all registered devices with their connection status
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceListResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
post:
operationId: addDevice
tags:
- device
summary: Add a new device
description: Create a new device slot for multi-device management
requestBody:
content:
application/json:
schema:
type: object
properties:
device_id:
type: string
description: Optional custom device ID. If not provided, one will be generated.
example: 'my-custom-device-id'
webhook_url:
type: string
description: Optional device-specific webhook URL. If set, events for this device will be sent here instead of the global webhook.
example: 'https://device-webhook.example.com/handler'
webhook_secret:
type: string
description: Optional secret used to sign device-specific webhook payloads (HMAC).
example: 'super-secret-key'
webhook_events:
type: string
description: Optional comma-separated list of event names to forward to the device-specific webhook. Empty means all events.
example: 'message,message.ack'
webhook_insecure_skip_verify:
type: boolean
description: Optional. Skip TLS certificate verification when delivering to the device-specific webhook.
example: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceAddResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/devices/{device_id}:
get:
operationId: getDevice
tags:
- device
summary: Get device info
description: Get detailed information about a specific device
parameters:
- name: device_id
in: path
required: true
schema:
type: string
description: Device ID
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceInfoResponse'
'404':
description: Device not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
delete:
operationId: removeDevice
tags:
- device
summary: Remove a device
description: >-
Remove a device slot from the server. This also logs it out of WhatsApp and
clears its session and chat data. To log out while keeping the slot, use the
logout endpoint instead.
parameters:
- name: device_id
in: path
required: true
schema:
type: string
description: Device ID
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'404':
description: Device not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/devices/{device_id}/login:
get:
operationId: loginDevice
tags:
- device
summary: Login a device with QR code
description: >-
Start QR pairing for a specific device slot and return a link to the QR
image to scan. Equivalent to `GET /app/login` with
`X-Device-Id: <device_id>`, with the device taken from the path instead.
parameters:
- name: device_id
in: path
required: true
schema:
type: string
description: Device ID
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceLoginResponse'
'404':
description: Device not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/devices/{device_id}/login/code:
post:
operationId: loginDeviceWithCode
tags:
- device
summary: Login a device with pairing code
description: >-
Start pairing-code login for a specific device slot and return the code to
enter on the phone. Equivalent to `GET /app/login-with-code` with
`X-Device-Id: <device_id>`, with the device taken from the path instead.
parameters:
- name: device_id
in: path
required: true
schema:
type: string
description: Device ID
- name: phone
in: query
required: true
schema:
type: string
example: '628912344551'
description: Phone number to pair with
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceLoginWithCodeResponse'
'404':
description: Device not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/devices/{device_id}/logout:
post:
operationId: logoutDevice
tags:
- device
summary: Logout device
description: >-
Logs a specific device out of WhatsApp and clears its session, but keeps the
device slot (id and display name) so it can be re-paired under the same id.
To remove the slot entirely, use DELETE /devices/{device_id}.
parameters:
- name: device_id
in: path
required: true
schema:
type: string
description: Device ID
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'404':
description: Device not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/devices/{device_id}/reconnect:
post:
operationId: reconnectDevice
tags:
- device
summary: Reconnect device
description: Reconnect a specific device to WhatsApp
parameters:
- name: device_id
in: path
required: true
schema:
type: string
description: Device ID
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'404':
description: Device not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/devices/{device_id}/status:
get:
operationId: getDeviceStatus
tags:
- device
summary: Get device connection status
description: Get the current connection status of a specific device
parameters:
- name: device_id
in: path
required: true
schema:
type: string
description: Device ID
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceStatusResponse'
'404':
description: Device not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/devices/{device_id}/webhook:
get:
operationId: getDeviceWebhook
tags:
- device
summary: Get device webhook configuration
description: Get the webhook configuration for a specific device. Returns empty values if no device-specific webhook is set.
parameters:
- name: device_id
in: path
required: true
schema:
type: string
description: Device ID
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
type: integer
example: 200
code:
type: string
example: SUCCESS
message:
type: string
example: Device webhook retrieved
results:
type: object
properties:
device_id:
type: string
description: The device ID
example: 'my-device'
webhook_url:
type: string
description: The configured webhook URL (empty if not set)
example: 'https://example.com/webhook'
webhook_secret:
type: string
description: Secret used to sign payloads for this device webhook
example: 'super-secret-key'
webhook_events:
type: string
description: Comma-separated event whitelist for this device webhook
example: 'message,message.ack'
webhook_insecure_skip_verify:
type: boolean
description: Whether TLS verification is skipped for this device webhook
example: false
'404':
description: Device not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
patch:
operationId: updateDeviceWebhook
tags:
- device
summary: Set device webhook configuration
description: |
Set a custom webhook configuration for a specific device. When set, webhook events for this device
will be sent to this URL instead of the global webhook URL. Device-level `webhook_secret`,
`webhook_events`, and `webhook_insecure_skip_verify` override the global webhook settings for this device.
Set to empty string to clear and use the global webhook.
parameters:
- name: device_id
in: path
required: true
schema:
type: string
description: Device ID
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
webhook_url:
type: string
description: Custom webhook URL to use for this device. Set to empty string to clear.
example: 'https://example.com/webhook'
webhook_secret:
type: string
description: Optional secret used to sign payloads for this device webhook.
example: 'super-secret-key'
webhook_events:
type: string
description: Optional comma-separated event whitelist for this device webhook. Empty means all events.
example: 'message,message.ack'
webhook_insecure_skip_verify:
type: boolean
description: Optional. Skip TLS certificate verification for this device webhook.
example: false
required:
- webhook_url
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
type: integer
example: 200
code:
type: string
example: SUCCESS
message:
type: string
example: Device webhook updated
results:
type: object
properties:
device_id:
type: string
description: The device ID
example: 'my-device'
webhook_url:
type: string
description: The configured webhook URL
example: 'https://example.com/webhook'
webhook_secret:
type: string
description: Secret used to sign payloads for this device webhook
example: 'super-secret-key'
webhook_events:
type: string
description: Comma-separated event whitelist for this device webhook
example: 'message,message.ack'
webhook_insecure_skip_verify:
type: boolean
description: Whether TLS verification is skipped for this device webhook
example: false
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'404':
description: Device not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/user/presence/subscribe:
post:
operationId: userSubscribePresence
tags:
- user
summary: Subscribe to contact presence
description: |
Subscribe the selected logged-in device to an individual contact's online/offline updates.
Updates arrive through presence webhooks. For continuous tracking, set
WHATSAPP_PRESENCE_ON_CONNECT=available and WHATSAPP_PRESENCE_PULSE_ENABLED=false.
Keeping the device available suppresses phone push notifications.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- phone
properties:
phone:
type: string
description: Individual contact phone number with country code
example: '6289685028129'
responses:
'200':
description: Subscription accepted. This does not guarantee contact presence delivery.
content:
application/json:
schema:
type: object
properties:
status:
type: integer
example: 200
code:
type: string
example: SUCCESS
message:
type: string
example: Success subscribe to user presence
results:
type: object
properties:
subscribed:
type: boolean
example: true
jid:
type: string
example: '[email protected]'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/user/info:
get:
operationId: userInfo
tags:
- user
summary: User Info
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: phone
in: query
schema:
type: string
example: '[email protected]'
description: Phone number with country code
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UserInfoResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/user/avatar:
get:
operationId: userAvatar
tags:
- user
summary: User Avatar
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: phone
in: query
schema:
type: string
example: '[email protected]'
description: Phone number with country code
- name: is_preview
in: query
schema:
type: boolean
example: true
description: Whether to fetch a preview of the avatar
- name: is_community
in: query
schema:
type: boolean
example: false
description: Whether to fetch a community avatar
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UserAvatarResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'403':
description: 'AVATAR_HIDDEN: the contact hides the picture from this account (says nothing about whether one exists)'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorForbidden'
example:
code: AVATAR_HIDDEN
message: the user has hidden their profile picture from you
'404':
description: 'The contact has no profile picture (AVATAR_NOT_SET) or the device is unknown (DEVICE_NOT_FOUND). Check `code`, not only the status.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
examples:
avatarNotSet:
summary: The contact has no profile picture
value:
code: AVATAR_NOT_SET
message: that user or group does not have a profile picture
deviceNotFound:
summary: Unknown device
value:
code: DEVICE_NOT_FOUND
message: device not found; create a device first from /api/devices or provide a valid X-Device-Id
results:
device_id: my-device
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
post:
operationId: userChangeAvatar
tags:
- user
summary: User Change Avatar
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
avatar:
type: string
format: binary
description: Avatar to send
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/user/pushname:
post:
operationId: userChangePushName
tags:
- user
summary: User Change Push Name
description: Update the display name (push name) shown to others in WhatsApp
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
type: object
properties:
push_name:
type: string
example: 'John Doe'
description: The new display name to set
required:
- push_name
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/user/my/privacy:
get:
operationId: userMyPrivacy
tags:
- user
summary: User My Privacy Setting
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UserPrivacyResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/user/my/groups:
get:
operationId: userMyGroups
tags:
- user
summary: User My List Groups
description: |
Get all groups that the authenticated user has joined.
⚠️ **Known Limitation**: This endpoint returns a maximum of 500 groups due to a WhatsApp protocol limitation.
The underlying whatsmeow library's `GetJoinedGroups()` function sends a single query to WhatsApp servers,
which enforces this limit. This is not a bug in this API - it's a constraint imposed by WhatsApp's
multi-device protocol. Users with more than 500 groups will only receive the first 500 groups.
For more details, see: https://github.com/tulir/whatsmeow/blob/main/group.go
externalDocs:
description: WhatsApp protocol limitation reference (whatsmeow source)
url: https://github.com/tulir/whatsmeow/blob/main/group.go
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UserGroupResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/user/my/newsletters:
get:
operationId: userMyNewsletter
tags:
- user
summary: User My List Groups
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/NewsletterResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/user/my/contacts:
get:
operationId: userMyContacts
tags:
- user
summary: Get list of user contacts
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MyListContactsResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/user/check:
get:
operationId: userCheck
tags:
- user
summary: Check if user is on WhatsApp
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: phone
in: query
schema:
type: string
example: '628912344551'
description: Phone number with country code
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UserCheckResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/user/business-profile:
get:
operationId: userBusinessProfile
tags:
- user
summary: Get Business Profile Information
description: Retrieve detailed business profile information for a WhatsApp business account
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: phone
in: query
required: true
schema:
type: string
example: '[email protected]'
description: Phone number with country code of the business account
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessProfileResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/send/message:
post:
operationId: sendMessage
tags:
- send
summary: Send Message
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/ScheduleOptions'
properties:
phone:
type: string
example: '[email protected]'
description: Phone number with country code
message:
type: string
example: selamat malam
description: Message to send
reply_message_id:
type: string
example: 3EB089B9D6ADD58153C561
description: Message ID that you want reply
is_forwarded:
type: boolean
example: false
description: Whether this is a forwarded message
duration:
type: integer
example: 86400
description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
mentions:
type: array
items:
type: string
example: ["628123456789", "@everyone"]
description: |
List of phone numbers to mention (ghost mentions - no @ required in message text).
Use special keyword "@everyone" to mention all group participants.
allow_reshare:
type: boolean
example: false
description: Show the reshare button to status viewers. Requires `phone` to be `status@broadcast`; GOWA rejects the field for any other recipient.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/send/image:
post:
operationId: sendImage
tags:
- send
summary: Send Image
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
multipart/form-data:
schema:
type: object
allOf:
- $ref: '#/components/schemas/ScheduleOptions'
properties:
phone:
type: string
example: '[email protected]'
description: Phone number with country code
caption:
type: string
example: selamat malam
description: Caption to send
mentions:
type: array
items:
type: string
example: ["628123456789", "@everyone"]
description: |
List of phone numbers to mention (ghost mentions - no @ required in caption).
`@phone` in the caption is also mentioned. Use special keyword "@everyone" to mention all group participants.
Send one `mentions` form field per entry.
reply_message_id:
type: string
example: 3EB089B9D6ADD58153C561
description: Message ID that you want reply
view_once:
type: boolean
example: false
description: View once
image:
type: string
format: binary
description: Image to send
image_url:
type: string
example: https://example.com/image.jpg
description: Image URL to send
compress:
type: boolean
example: false
description: Compress image
hd:
type: boolean
example: true
description: Send a high-definition image rendition (maximum edge 2560px). Overrides compress when true.
duration:
type: integer
example: 86400
description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
is_forwarded:
type: boolean
example: false
description: Whether this is a forwarded message
allow_reshare:
type: boolean
example: false
description: Show the reshare button to status viewers. Requires `phone` to be `status@broadcast`; GOWA rejects the field for any other recipient.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/send/audio:
post:
operationId: sendAudio
tags:
- send
summary: Send Audio
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
multipart/form-data:
schema:
type: object
allOf:
- $ref: '#/components/schemas/ScheduleOptions'
properties:
phone:
type: string
example: '[email protected]'
description: Phone number with country code
audio:
type: string
format: binary
description: Audio to send
audio_url:
type: string
example: https://example.com/audio.mp3
description: Audio URL to send
ptt:
type: boolean
example: false
description: Send as a WhatsApp voice note. When true, ffmpeg is required to transcode to OGG Opus.
reply_message_id:
type: string
example: 3EB089B9D6ADD58153C561
description: Message ID that you want reply
is_forwarded:
type: boolean
example: false
description: Whether this is a forwarded message
duration:
type: integer
example: 86400
description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/send/file:
post:
operationId: sendFile
tags:
- send
summary: Send File
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
multipart/form-data:
schema:
type: object
allOf:
- $ref: '#/components/schemas/ScheduleOptions'
properties:
phone:
type: string
example: '[email protected]'
description: Phone number with country code
caption:
type: string
example: selamat malam
description: Caption to send
mentions:
type: array
items:
type: string
example: ["628123456789", "@everyone"]
description: |
List of phone numbers to mention (ghost mentions - no @ required in caption).
`@phone` in the caption is also mentioned. Use special keyword "@everyone" to mention all group participants.
Send one `mentions` form field per entry.
reply_message_id:
type: string
example: 3EB089B9D6ADD58153C561
description: Message ID that you want reply
file:
type: string
format: binary
description: File to send
file_url:
type: string
example: https://example.com/document.pdf
description: File URL to download and send
is_forwarded:
type: boolean
example: false
description: Whether this is a forwarded message
duration:
type: integer
example: 86400
description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/send/sticker:
post:
operationId: sendSticker
tags:
- send
summary: Send Sticker
description: Send sticker with automatic conversion to WebP format
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
multipart/form-data:
schema:
type: object
allOf:
- $ref: '#/components/schemas/ScheduleOptions'
properties:
phone:
type: string
example: '[email protected]'
description: Phone number with country code
sticker:
type: string
format: binary
description: Sticker image file (jpg/jpeg/png/webp/gif)
sticker_url:
type: string
example: https://example.com/sticker.png
description: URL of sticker image to send
duration:
type: integer
example: 86400
description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
reply_message_id:
type: string
example: 3EB089B9D6ADD58153C561
description: Message ID that you want reply
is_forwarded:
type: boolean
example: false
description: Whether this is a forwarded sticker
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/send/video:
post:
operationId: sendVideo
tags:
- send
summary: Send Video
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
multipart/form-data:
schema:
type: object
allOf:
- $ref: '#/components/schemas/ScheduleOptions'
properties:
phone:
type: string
example: '[email protected]'
description: Phone number with country code
caption:
type: string
example: ini contoh caption video
description: Caption to send
mentions:
type: array
items:
type: string
example: ["628123456789", "@everyone"]
description: |
List of phone numbers to mention (ghost mentions - no @ required in caption).
`@phone` in the caption is also mentioned. Use special keyword "@everyone" to mention all group participants.
Send one `mentions` form field per entry.
reply_message_id:
type: string
example: 3EB089B9D6ADD58153C561
description: Message ID that you want reply
view_once:
type: boolean
example: false
description: View once
video:
type: string
format: binary
description: Video to send
video_url:
type: string
example: https://example.com/sample.mp4
description: Video URL to send
compress:
type: boolean
example: false
description: Compress video
hd:
type: boolean
example: true
description: Send an H.264 8-bit YUV 4:2:0 high-definition video rendition at CRF 23, capped at 1280x1280 while preserving aspect ratio and avoiding upscaling. Overrides compress when true.
gif_playback:
type: boolean
example: false
description: Display video as GIF (looping, silent, autoplay)
duration:
type: integer
example: 86400
description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
is_forwarded:
type: boolean
example: false
description: Whether this is a forwarded message
allow_reshare:
type: boolean
example: false
description: Show the reshare button to status viewers. Requires `phone` to be `status@broadcast`; GOWA rejects the field for any other recipient.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/send/contact:
post:
operationId: sendContact
tags:
- send
summary: Send Contact
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/ScheduleOptions'
properties:
phone:
type: string
example: '[email protected]'
description: Phone number with country code
contact_name:
type: string
example: Aldino Kemal
description: Contact name
contact_phone:
type: string
example: '6289685024992'
description: Contact phone number
is_forwarded:
type: boolean
example: false
description: Whether this is a forwarded message
duration:
type: integer
example: 86400
description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/send/link:
post:
operationId: sendLink
tags:
- send
summary: Send Link
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/ScheduleOptions'
properties:
phone:
type: string
example: '[email protected]'
description: Phone number with country code
link:
type: string
example: "https://google.com"
description: Link to send
caption:
type: string
example: 'Halo ini contoh caption'
description: Caption to send
is_forwarded:
type: boolean
example: false
description: Whether this is a forwarded message
duration:
type: integer
example: 86400
description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/send/location:
post:
operationId: sendLocation
tags:
- send
summary: Send Location
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/ScheduleOptions'
properties:
phone:
type: string
example: '[email protected]'
description: Phone number with country code
latitude:
type: string
example: "-7.797068"
description: Latitude coordinate
longitude:
type: string
example: '110.370529'
description: Longitude coordinate
is_forwarded:
type: boolean
example: false
description: Whether this is a forwarded message
duration:
type: integer
example: 86400
description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/send/poll:
post:
operationId: sendPoll
tags:
- send
summary: Send Poll / Vote
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
required: true
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/ScheduleOptions'
properties:
phone:
type: string
description: The WhatsApp phone number to send the poll to, including the '@s.whatsapp.net' suffix.
example: '[email protected]'
question:
type: string
description: The question for the poll.
example: 'Siapa Nama Avatar The Last Air Bender?'
options:
type: array
description: The options for the poll.
items:
type: string
example: [ 'Zuko', 'Aang', 'Katara' ]
max_answer:
type: integer
description: The maximum number of answers allowed for the poll.
example: 2
duration:
type: integer
example: 86400
description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
required:
- phone
- question
- options
- max_answer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/send/presence:
post:
operationId: sendPresence
tags:
- send
summary: Send presence status
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The presence type to send
enum: [available, unavailable]
example: 'available'
is_forwarded:
type: boolean
example: false
description: Whether this is a forwarded message
required:
- type
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/send/chat-presence:
post:
operationId: sendChatPresence
tags:
- send
summary: Send chat presence (typing indicator)
description: Send typing indicator to start or stop showing that you are composing a message. Presence cannot be scheduled; schedule fields (scheduled_at, timezone, recurrence, ...) are rejected with 400.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
phone:
type: string
example: '[email protected]'
description: Phone number with country code
action:
type: string
enum: [start, stop]
example: 'start'
description: Action to perform - "start" to begin typing indicator, "stop" to end typing indicator
required:
- phone
- action
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/send/schedules:
get:
operationId: listScheduledSends
tags:
- send
summary: List scheduled sends
description: >-
Lists the device's scheduled sends. Upcoming schedules come first
(soonest next run first), followed by finished ones, newest first.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: status
in: query
schema:
type: string
enum: [active, running, paused, completed, failed, cancelled]
description: Only schedules in this status
- name: search
in: query
schema:
type: string
description: Match the recipient or the message text
- name: message_type
in: query
schema:
type: string
enum: [text, image, file, video, audio, sticker, contact, link, location, poll, forward]
description: Only this kind of scheduled send
- name: limit
in: query
schema:
type: integer
default: 25
minimum: 1
maximum: 100
description: Maximum number of schedules to return
- name: offset
in: query
schema:
type: integer
default: 0
minimum: 0
description: Number of schedules to skip (for pagination)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleListResponse'
'400':
description: Bad Request (e.g. unknown status or message_type, limit or offset out of range)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/send/schedules/{schedule_id}:
get:
operationId: getScheduledSend
tags:
- send
summary: Get a scheduled send
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- $ref: '#/components/parameters/ScheduleIdPath'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleResponse'
'404':
description: Schedule not found for this device
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/send/schedules/{schedule_id}/pause:
post:
operationId: pauseScheduledSend
tags:
- send
summary: Pause a scheduled send
description: Stops an active schedule from sending until it is resumed. Only an active schedule can be paused.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- $ref: '#/components/parameters/ScheduleIdPath'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request (the schedule is not active)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'404':
description: Schedule not found for this device
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/send/schedules/{schedule_id}/resume:
post:
operationId: resumeScheduledSend
tags:
- send
summary: Resume a paused scheduled send
description: >-
Makes a paused schedule active again. Only a paused schedule can be
resumed. A recurring schedule whose next run passed while paused
continues at its next slot, or completes if none is left; an overdue
one-time schedule sends right away.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- $ref: '#/components/parameters/ScheduleIdPath'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request (the schedule is not paused)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'404':
description: Schedule not found for this device
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/send/schedules/{schedule_id}/cancel:
post:
operationId: cancelScheduledSend
tags:
- send
summary: Cancel a scheduled send
description: >-
Cancels an active, paused, or failed schedule so it never sends again.
Its stored media is removed.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- $ref: '#/components/parameters/ScheduleIdPath'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request (the schedule is running, completed, or already cancelled)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'404':
description: Schedule not found for this device
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/message/{message_id}/revoke:
post:
operationId: revokeMessage
tags:
- message
summary: Revoke Message
description: |
Revoke (delete for everyone) a message. Revokes the bot's own message by default.
If the target message was sent by another user and is present in chat storage,
the original sender is resolved automatically so a group-admin bot can revoke
other members' messages (anti-spam use case). The WhatsApp server rejects the
request if the bot is not a group admin.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- in: path
name: message_id
schema:
type: string
required: true
description: Message ID
requestBody:
content:
application/json:
schema:
type: object
properties:
phone:
type: string
example: '[email protected]'
description: Phone number with country code
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/message/{message_id}/delete:
post:
operationId: deleteMessage
tags:
- message
summary: Delete Message
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- in: path
name: message_id
schema:
type: string
required: true
description: Message ID
requestBody:
content:
application/json:
schema:
type: object
properties:
phone:
type: string
example: '[email protected]'
description: Phone number with country code
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/message/{message_id}/reaction:
post:
operationId: reactMessage
tags:
- message
summary: Send reaction to message
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- in: path
name: message_id
schema:
type: string
required: true
description: Message ID
requestBody:
content:
application/json:
schema:
type: object
properties:
phone:
type: string
example: '[email protected]'
description: Phone number with country code
emoji:
type: string
example: "🙏"
description: Emoji to react
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/message/{message_id}/update:
post:
operationId: updateMessage
tags:
- message
summary: Edit message by message ID before 15 minutes
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- in: path
name: message_id
schema:
type: string
required: true
description: Message ID
requestBody:
content:
application/json:
schema:
type: object
properties:
phone:
type: string
example: '[email protected]'
description: Phone number with country code
message:
type: string
example: 'Hello World'
description: New message to send
link:
type: string
example: 'https://example.com/page'
description: Optional URL. When set, the edit is sent with a rich link preview (title, description, thumbnail) like /send/link. Appended to the message if not already present.
required:
- phone
- message
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/message/{message_id}/read:
post:
operationId: readMessage
tags:
- message
summary: Mark as read message
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- in: path
name: message_id
schema:
type: string
required: true
description: Message ID
requestBody:
content:
application/json:
schema:
type: object
properties:
phone:
type: string
example: '[email protected]'
description: Phone number with country code
required:
- phone
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/message/{message_id}/played:
post:
operationId: markMessagePlayed
tags:
- message
summary: Mark an audio message as played
description: >-
Sends WhatsApp's played receipt for an incoming audio message or voice
note. The message must exist in the active device's chat storage and
belong to the supplied chat.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- in: path
name: message_id
schema:
type: string
required: true
description: Message ID
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
phone:
type: string
example: '[email protected]'
description: Phone number or group JID containing the audio message
required:
- phone
responses:
'200':
description: Played receipt sent
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/message/{message_id}/star:
post:
operationId: starMessage
tags:
- message
summary: Star message
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- in: path
name: message_id
schema:
type: string
required: true
description: Message ID
requestBody:
content:
application/json:
schema:
type: object
properties:
phone:
type: string
example: '[email protected]'
description: Phone number with country code
required:
- phone
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/message/{message_id}/unstar:
post:
operationId: unstarMessage
tags:
- message
summary: Unstar message
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- in: path
name: message_id
schema:
type: string
required: true
description: Message ID
requestBody:
content:
application/json:
schema:
type: object
properties:
phone:
type: string
example: '[email protected]'
description: Phone number with country code
required:
- phone
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/message/{message_id}/forward:
post:
operationId: forwardMessage
tags:
- message
summary: Forward Message
description: |
Forward a message that exists in local chat storage to another chat by message ID.
Text and standard media types (image, video, video note, audio, document, sticker) are supported.
Media references are reused when possible; stale refs trigger an automatic re-upload fallback.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- in: path
name: message_id
schema:
type: string
required: true
description: Source message ID from chat storage
example: '3EB0123456789ABCDEF'
requestBody:
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/ScheduleOptions'
required:
- phone
properties:
phone:
type: string
example: '[email protected]'
description: Destination phone number or group JID
duration:
type: integer
example: 0
description: Optional disappearing message duration override (0, 86400, 604800, 7776000)
force_reupload:
type: boolean
example: false
description: Skip media reference reuse and re-upload media before sending
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/message/{message_id}/download:
get:
operationId: downloadMessageMedia
tags:
- message
summary: Download media from message
description: Download media content (image, video, audio, document) from a message
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- in: path
name: message_id
schema:
type: string
required: true
description: Message ID
example: '3EB0123456789ABCDEF'
- in: query
name: phone
schema:
type: string
required: true
description: Phone number with country code
example: '[email protected]'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
type: integer
example: 200
code:
type: string
example: SUCCESS
message:
type: string
example: Media downloaded successfully
results:
type: object
properties:
status:
type: string
example: Media downloaded successfully
message_id:
type: string
example: 3EB0ABC123456789
media_type:
type: string
example: audio
filename:
type: string
example: audio.ogg
file_path:
type: string
description: Local server file path where the media was saved
example: statics/media/6289685028129/2026-06-09/audio.ogg
file_url:
type: string
description: Public URL for downloading the saved media when it is stored under the served statics directory
example: http://localhost:3000/statics/media/6289685028129/2026-06-09/audio.ogg
file_size:
type: integer
example: 524288
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'404':
description: Message or media not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/call/reject:
post:
operationId: rejectCall
tags:
- call
summary: Reject an incoming call
description: |
Programmatically reject a specific incoming call. This endpoint allows selective call rejection
based on your application logic (e.g., time-of-day rules, caller whitelists, agent availability).
The call must still be ringing — rejection will fail if the call has already ended or been answered.
This is complementary to the auto-reject feature (`WHATSAPP_AUTO_REJECT_CALL=true`) which rejects
all incoming calls globally. Use this API for fine-grained control.
**Required fields from webhook:**
- `caller_jid`: Use `payload.from` from the `call.offer` webhook event
- `call_id`: Use `payload.call_id` from the `call.offer` webhook event
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- caller_jid
- call_id
properties:
caller_jid:
type: string
example: '[email protected]'
description: JID of the caller (from webhook `payload.from`)
call_id:
type: string
example: 'ABC123DEF456'
description: Unique call identifier (from webhook `payload.call_id`)
responses:
'200':
description: Call rejected successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request (missing or invalid fields)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error (call already ended, not connected, etc.)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/chats:
get:
operationId: listChats
tags:
- chat
summary: Get list of chats
description: Retrieve a list of chat conversations with their basic information
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: limit
in: query
schema:
type: integer
default: 25
maximum: 100
description: Maximum number of chats to return
- name: offset
in: query
schema:
type: integer
default: 0
description: Number of chats to skip (for pagination)
- name: search
in: query
schema:
type: string
description: Search chats by name
- name: has_media
in: query
schema:
type: boolean
default: false
description: Filter chats that contain media messages
- name: archived
in: query
schema:
type: boolean
description: Filter by archived status. true = archived only, false = non-archived only. Omit to return all chats.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ChatListResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorUnauthorized'
/chat/{chat_jid}/messages:
get:
operationId: getChatMessages
tags:
- chat
summary: Get messages from a specific chat
description: Retrieve messages from a specific chat conversation with filtering options
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- in: path
name: chat_jid
schema:
type: string
required: true
description: Chat JID (e.g., [email protected] for individual or [email protected] for group). Percent-encoded values (e.g., groupid%40g.us) are accepted.
example: '[email protected]'
- name: limit
in: query
schema:
type: integer
default: 50
maximum: 100
description: Maximum number of messages to return
- name: offset
in: query
schema:
type: integer
default: 0
description: Number of messages to skip (for pagination)
- name: start_time
in: query
schema:
type: string
format: date-time
description: Filter messages from this timestamp (ISO 8601 format)
- name: end_time
in: query
schema:
type: string
format: date-time
description: Filter messages until this timestamp (ISO 8601 format)
- name: media_only
in: query
schema:
type: boolean
default: false
description: Only return messages with media content
- name: is_from_me
in: query
schema:
type: boolean
description: Filter messages by sender (true for messages sent by you, false for received messages). When both media_only=true and isFromMe=false are provided, media_only takes precedence and will return all media messages regardless of sender.
- name: search
in: query
schema:
type: string
description: Search messages by content text
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ChatMessagesResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorUnauthorized'
'404':
description: Chat Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/chat/{chat_jid}/history:
post:
operationId: requestChatHistory
tags:
- chat
summary: Request older chat history from the phone
description: >-
Asks the phone for older messages of a chat on demand (what WhatsApp
Web does when you scroll up / "load older messages"). The request is
anchored at the oldest message currently stored locally for that
chat, so the chat must already have at least one stored message. The
phone answers asynchronously with a history sync event that gets
persisted into chat storage; this endpoint only confirms the request
was sent, it does not return the older messages directly.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- in: path
name: chat_jid
schema:
type: string
required: true
description: Chat JID (e.g., [email protected] for individual or [email protected] for group). Percent-encoded values (e.g., groupid%40g.us) are accepted.
example: '[email protected]'
requestBody:
content:
application/json:
schema:
type: object
properties:
count:
type: integer
default: 50
minimum: 0
maximum: 500
example: 50
description: Number of older messages to request from the phone. Omit it, or send 0, to use the default of 50.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RequestChatHistoryResponse'
'400':
description: Bad Request (e.g. missing chat_jid, count out of range, or chat has no stored messages to anchor on)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorUnauthorized'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/chat/{chat_jid}/pin:
post:
operationId: pinChat
tags:
- chat
summary: Pin or unpin a chat
description: Pin or unpin a chat conversation to the top of the chat list
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- in: path
name: chat_jid
schema:
type: string
required: true
description: Chat JID (e.g., [email protected] for individual or [email protected] for group). Percent-encoded values (e.g., groupid%40g.us) are accepted.
example: '[email protected]'
requestBody:
content:
application/json:
schema:
type: object
properties:
pinned:
type: boolean
example: true
description: Whether to pin (true) or unpin (false) the chat
required:
- pinned
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PinChatResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorUnauthorized'
'404':
description: Chat Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/chat/{chat_jid}/disappearing:
post:
operationId: setDisappearingTimer
tags:
- chat
summary: Set disappearing messages timer
description: Set or disable disappearing messages for a chat. Valid timer values are 0 (off), 86400 (24h), 604800 (7d), 7776000 (90d).
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- in: path
name: chat_jid
schema:
type: string
required: true
description: Chat JID (e.g., [email protected] for individual or [email protected] for group). Percent-encoded values (e.g., groupid%40g.us) are accepted.
example: '[email protected]'
requestBody:
content:
application/json:
schema:
type: object
properties:
timer_seconds:
type: integer
example: 86400
description: 'Timer in seconds: 0 (off), 86400 (24h), 604800 (7d), 7776000 (90d)'
required:
- timer_seconds
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SetDisappearingTimerResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/chat/{chat_jid}/archive:
post:
operationId: archiveChat
tags:
- chat
summary: Archive or unarchive a chat
description: Archive or unarchive a chat conversation. Archived chats are hidden from the main chat list.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- in: path
name: chat_jid
schema:
type: string
required: true
description: Chat JID (e.g., [email protected] for individual or [email protected] for group). Percent-encoded values (e.g., groupid%40g.us) are accepted.
example: '[email protected]'
requestBody:
content:
application/json:
schema:
type: object
properties:
archived:
type: boolean
example: true
description: Whether to archive (true) or unarchive (false) the chat
required:
- archived
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ArchiveChatResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorUnauthorized'
'404':
description: Chat Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/info:
get:
operationId: groupInfo
tags:
- group
summary: Group Info
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: group_id
in: query
schema:
type: string
example: '[email protected]'
description: WhatsApp Group ID
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GroupInfoResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group:
post:
operationId: createGroup
tags:
- group
summary: Create group and add participant
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
type: object
properties:
title:
type: string
example: 'Example Group Title'
participants:
type: array
items:
type: string
example:
- '6819241294719274'
- '6829241294719274'
- '6839241294719274'
example:
- '6819241294719274'
- '6829241294719274'
- '6839241294719274'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateGroupResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/participants:
get:
operationId: getGroupParticipants
tags:
- group
summary: Get list of participants in a group
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: group_id
in: query
required: true
schema:
type: string
example: '[email protected]'
description: The group ID to fetch participants for
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GroupParticipantsResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
post:
operationId: addParticipantToGroup
tags:
- group
summary: Adding more participants to group
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ManageParticipantRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ManageParticipantResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/participants/export:
get:
operationId: exportGroupParticipants
tags:
- group
summary: Export group participants as CSV
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: group_id
in: query
required: true
schema:
type: string
example: '[email protected]'
description: The group ID to export participants for
responses:
'200':
description: CSV stream containing the participants list
content:
text/csv:
schema:
type: string
format: binary
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/participants/remove:
post:
operationId: removeParticipantFromGroup
tags:
- group
summary: Remove participants from group
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ManageParticipantRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ManageParticipantResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/participants/promote:
post:
operationId: promoteParticipantToAdmin
tags:
- group
summary: Promote participants to admin
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ManageParticipantRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ManageParticipantResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/participants/demote:
post:
operationId: demoteParticipantToMember
tags:
- group
summary: Demote participants to member
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ManageParticipantRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ManageParticipantResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/join-with-link:
post:
operationId: joinGroupWithLink
tags:
- group
summary: Join group with link
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
type: object
properties:
link:
type: string
example: 'https://chat.whatsapp.com/whatsappKeyJoinGroup'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/info-from-link:
get:
operationId: getGroupInfoFromLink
tags:
- group
summary: Get group information from invitation link
description: Retrieve group information without joining the group using its invitation link
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: link
in: query
required: true
schema:
type: string
example: 'https://chat.whatsapp.com/whatsappKeyJoinGroup'
description: WhatsApp group invitation link
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GroupInfoFromLinkResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/participant-requests:
get:
operationId: getGroupParticipantRequests
tags:
- group
summary: Get list of participant requests to join group
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: group_id
in: query
required: true
schema:
type: string
example: '[email protected]'
description: The group ID to get participant requests for
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GroupParticipantRequestListResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/participant-requests/approve:
post:
operationId: approveGroupParticipantRequest
tags:
- group
summary: Approve participant request to join group
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
type: object
properties:
group_id:
type: string
example: '[email protected]'
description: The group ID
participants:
type: array
items:
type: string
example: ['6281234567890']
description: Array of participant WhatsApp IDs to approve
required:
- group_id
- participants
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/participant-requests/reject:
post:
operationId: rejectGroupParticipantRequest
tags:
- group
summary: Reject participant request to join group
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
type: object
properties:
group_id:
type: string
example: '[email protected]'
description: The group ID
participants:
type: array
items:
type: string
example: ['6281234567890']
description: Array of participant WhatsApp IDs to reject
required:
- group_id
- participants
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/leave:
post:
operationId: leaveGroup
tags:
- group
summary: Leave group
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
type: object
properties:
group_id:
type: string
example: '[email protected]'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/photo:
post:
operationId: setGroupPhoto
tags:
- group
summary: Set group photo
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
group_id:
type: string
example: '[email protected]'
description: The group ID
photo:
type: string
format: binary
description: Group photo to upload (JPEG format recommended). Leave empty to remove photo.
required:
- group_id
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SetGroupPhotoResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/name:
post:
operationId: setGroupName
tags:
- group
summary: Set group name
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
type: object
properties:
group_id:
type: string
example: '[email protected]'
description: The group ID
name:
type: string
example: 'New Group Name'
description: The new group name (max 25 characters)
maxLength: 25
required:
- group_id
- name
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/locked:
post:
operationId: setGroupLocked
tags:
- group
summary: Set group locked status
description: Lock/unlock group so only admins can modify group info
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
type: object
properties:
group_id:
type: string
example: '[email protected]'
description: The group ID
locked:
type: boolean
example: true
description: Whether to lock the group (true) or unlock it (false)
required:
- group_id
- locked
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/announce:
post:
operationId: setGroupAnnounce
tags:
- group
summary: Set group announce mode
description: Enable/disable announce mode so only admins can send messages
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
type: object
properties:
group_id:
type: string
example: '[email protected]'
description: The group ID
announce:
type: boolean
example: true
description: Whether to enable announce mode (true) or disable it (false)
required:
- group_id
- announce
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/topic:
post:
operationId: setGroupTopic
tags:
- group
summary: Set group topic
description: Set or remove group topic/description
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
type: object
properties:
group_id:
type: string
example: '[email protected]'
description: The group ID
topic:
type: string
example: 'Welcome to our group! Please follow the rules.'
description: The group topic/description. Leave empty to remove the topic.
required:
- group_id
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/group/invite-link:
get:
operationId: groupInviteLink
tags:
- group
summary: Group Invite Link
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: group_id
in: query
schema:
type: string
required: true
description: WhatsApp Group ID
- name: reset
in: query
schema:
type: boolean
default: false
example: false
description: Reset existing invite link
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetGroupInviteLinkResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/newsletter/follow:
post:
operationId: followNewsletter
tags:
- newsletter
summary: Follow newsletter
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
type: object
required: [newsletter_id]
properties:
newsletter_id:
type: string
example: '120363024512399999@newsletter'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/newsletter/unfollow:
post:
operationId: unfollowNewsletter
tags:
- newsletter
summary: Unfollow newsletter
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
type: object
properties:
newsletter_id:
type: string
example: '120363024512399999@newsletter'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/newsletter/info:
get:
operationId: getNewsletterInfo
tags:
- newsletter
summary: Get newsletter (channel) metadata
description: |
Returns the channel metadata (name, description, subscribers count,
verification, picture, invite code, state). Provide exactly one of
`newsletter_id` or `invite`. Neither requires following the channel;
`viewer_metadata` is null when WhatsApp does not return viewer-specific metadata.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: newsletter_id
in: query
required: false
schema:
type: string
example: '120363024512399999@newsletter'
- name: invite
in: query
required: false
description: Channel invite link (https://whatsapp.com/channel/...) or just the code
schema:
type: string
example: 'https://whatsapp.com/channel/0029Va4K0PZ5a245NkngBA2M'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/NewsletterInfoResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/newsletter/directory:
get:
operationId: searchNewsletterDirectory
tags:
- newsletter
summary: Browse or search the public channel directory
description: |
Mirrors the "Find channels" screen of the official clients. Without
`search_text` it browses a `view` and requires at least one country
code; with `search_text` it searches channels by name (country codes
are not supported by the search). Paginate with `cursor` while
`has_more` is true. Uses undocumented WhatsApp queries captured from
WhatsApp Web, which may change without notice.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: view
in: query
required: false
schema:
type: string
enum: [RECOMMENDED, TRENDING, POPULAR, NEW, FEATURED]
default: RECOMMENDED
- name: search_text
in: query
required: false
schema:
type: string
example: news
- name: country_codes
in: query
required: false
description: ISO 3166-1 alpha-2 codes, repeated or comma separated. Required when browsing a view.
schema:
type: array
items:
type: string
example: [ID]
- name: categories
in: query
required: false
schema:
type: array
items:
type: string
enum: [BUSINESS, ENTERTAINMENT, LIFESTYLE, NEWS, ORGANIZATIONS, PEOPLE, SPORTS]
- name: limit
in: query
required: false
schema:
type: integer
default: 20
minimum: 1
maximum: 50
- name: cursor
in: query
required: false
description: next_cursor from the previous page
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/NewsletterDirectoryResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/newsletter/messages:
get:
operationId: getNewsletterMessages
tags:
- newsletter
summary: Get latest newsletter (channel) messages
description: |
Fetches the latest messages posted in a newsletter (channel) directly
from WhatsApp servers. Following the channel is not required. The
server keeps roughly the last 30 days of posts; `views_count` is only
reported to channel admins and is 0 otherwise.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: newsletter_id
in: query
required: true
schema:
type: string
example: '120363024512399999@newsletter'
- name: count
in: query
required: false
description: Number of messages to return (default 50, max 100)
schema:
type: integer
default: 50
minimum: 1
maximum: 100
- name: before
in: query
required: false
description: Fetch messages older than this message server ID, used for pagination
schema:
type: integer
minimum: 0
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/NewsletterMessagesResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/newsletter/message-updates:
get:
operationId: getNewsletterMessageUpdates
tags:
- newsletter
summary: Get newsletter message counters
description: |
Returns only the counters (forwards and reactions per emoji) of the
messages after `after`, without message content. Cheaper than
re-fetching messages to refresh engagement. Does not require following.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: newsletter_id
in: query
required: true
schema:
type: string
example: '120363024512399999@newsletter'
- name: after
in: query
required: true
description: Return updates for messages with a server ID greater than this one
schema:
type: integer
minimum: 1
- name: count
in: query
required: false
schema:
type: integer
default: 50
minimum: 1
maximum: 100
- name: since
in: query
required: false
description: Unix timestamp (seconds); only messages updated after it
schema:
type: integer
minimum: 0
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/NewsletterMessagesResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/newsletter/live-updates:
get:
operationId: listNewsletterLiveUpdates
tags:
- newsletter
summary: List live updates subscriptions of the device
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/NewsletterLiveUpdatesListResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
post:
operationId: subscribeNewsletterLiveUpdates
tags:
- newsletter
summary: Subscribe to newsletter live updates
description: |
Subscribes the device to live counter updates of a channel, delivered
as `newsletter.message` webhooks. WhatsApp grants the subscription for
a short duration (90 seconds observed); GOWA renews it before it
expires and after reconnects until it is unsubscribed. Subscriptions
are kept in memory and do not survive a restart.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
content:
application/json:
schema:
type: object
required: [newsletter_id]
properties:
newsletter_id:
type: string
example: '120363024512399999@newsletter'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/NewsletterLiveUpdatesResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
delete:
operationId: unsubscribeNewsletterLiveUpdates
tags:
- newsletter
summary: Stop renewing newsletter live updates
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: newsletter_id
in: query
required: true
schema:
type: string
example: '120363024512399999@newsletter'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/newsletter/messages/{server_id}/download:
get:
operationId: downloadNewsletterMessageMedia
tags:
- newsletter
summary: Download media from a newsletter message
description: |
Fetches one newsletter message directly from WhatsApp by server ID,
downloads its media to the server's statics directory, and returns the
saved file metadata and public URL. Supported media types are images,
videos, video notes, audio, documents, and stickers.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
- name: server_id
in: path
required: true
description: Newsletter message server ID returned by GET /newsletter/messages
schema:
type: integer
minimum: 1
example: 8872
- name: newsletter_id
in: query
required: true
description: Newsletter JID containing the message
schema:
type: string
example: '120363024512399999@newsletter'
responses:
'200':
description: Media downloaded successfully
content:
application/json:
schema:
$ref: '#/components/schemas/NewsletterMediaDownloadResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Message lookup or media download failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
/chatwoot/sync:
post:
operationId: chatwootSyncHistory
tags:
- chatwoot
summary: Sync message history to Chatwoot
description: |
Initiates a background sync of WhatsApp message history to Chatwoot.
Messages from the configured number of days will be imported.
This endpoint requires CHATWOOT_ENABLED=true in configuration.
requestBody:
content:
application/json:
schema:
type: object
properties:
device_id:
type: string
description: Device ID to sync (uses CHATWOOT_DEVICE_ID if not specified)
days_limit:
type: integer
default: 3
description: Number of days of history to sync
include_media:
type: boolean
default: true
description: Include media attachments in sync
include_groups:
type: boolean
default: true
description: Include group chats in sync
responses:
'200':
description: Sync initiated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ChatwootSyncResponse'
'400':
description: Bad Request (device not found or Chatwoot not configured)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'409':
description: Sync already in progress
content:
application/json:
schema:
type: object
properties:
status:
type: integer
example: 409
code:
type: string
example: SYNC_ALREADY_RUNNING
message:
type: string
example: A sync is already in progress for this device
results:
type: object
properties:
progress:
$ref: '#/components/schemas/ChatwootSyncStatusResponse/properties/results'
/chatwoot/sync/status:
get:
operationId: chatwootSyncStatus
tags:
- chatwoot
summary: Get Chatwoot sync progress
description: Returns the current sync progress for a device
parameters:
- name: device_id
in: query
description: Device ID to check sync status for
schema:
type: string
responses:
'200':
description: Sync status retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/ChatwootSyncStatusResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
/chatwoot/webhook:
post:
operationId: chatwootWebhook
tags:
- chatwoot
summary: Chatwoot webhook endpoint
description: |
Receives webhook events from Chatwoot and sends messages to WhatsApp.
Configure this URL in your Chatwoot inbox webhook settings.
When CHATWOOT_WEBHOOK_SECRET is set the request must prove knowledge of
it. Recommended: Chatwoot's own signature, sent by Chatwoot when the API
channel has a webhook secret — `X-Chatwoot-Timestamp` (unix seconds) and
`X-Chatwoot-Signature: sha256=<hex HMAC-SHA256 of "<timestamp>.<raw body>">`.
The timestamp must be within CHATWOOT_WEBHOOK_SIGNATURE_TOLERANCE (5m by
default) of the server clock. Also accepted: `X-Hub-Signature-256`
(HMAC-SHA256 of the raw body), the secret in `X-Chatwoot-Webhook-Secret`
or `X-Gowa-Chatwoot-Secret`, or the `secret` query parameter (discouraged:
the secret then appears in URLs and logs).
The secret that applies is the secret of the device the payload is
routed to: that device config's `webhook_secret` when it has one (the
global secret is then not accepted for it), CHATWOOT_WEBHOOK_SECRET
otherwise and when no device resolves. A Chatwoot-signed request that
was already accepted (answered 2xx) inside the tolerance window is
acknowledged with 200 and not acted on again. One that was answered
with any other status is not remembered, so sending the identical
request again is handled.
parameters:
- name: X-Chatwoot-Signature
in: header
description: 'Chatwoot signature: sha256=<hex HMAC-SHA256 of "<timestamp>.<raw body>" keyed with the webhook secret>'
schema:
type: string
- name: X-Chatwoot-Timestamp
in: header
description: Unix time (seconds) the webhook was signed at
schema:
type: string
- name: secret
in: query
description: The webhook secret. Discouraged; prefer the signature headers.
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
description: Chatwoot webhook payload (see Chatwoot documentation)
responses:
'200':
description: Webhook processed
'401':
description: Secret or signature missing or invalid for the device the request is routed to, or the signature timestamp is outside the tolerance window
'503':
description: Device not available, the routed device's config could not be read, or an identical signed request is still being handled
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
/chatwoot/webhook/{device_id}:
post:
operationId: chatwootDeviceWebhook
tags:
- chatwoot
summary: Per-device Chatwoot webhook endpoint
description: |
Per-device variant of the Chatwoot webhook: configure each device's Chatwoot
inbox to POST here (the URL is returned as `webhook_url` by the device config
endpoints) so agent replies route deterministically to that device.
Route-by-config: in addition to the optional secret, the payload's
account and inbox must match the device's stored config or the request is
rejected with 401. Unknown device ids and non-message events are acknowledged
with 200 and ignored.
The request is authenticated like `/chatwoot/webhook`, with the device
config's `webhook_secret` when it has one and CHATWOOT_WEBHOOK_SECRET
otherwise.
parameters:
- name: device_id
in: path
required: true
description: Device ID (or WhatsApp JID) the webhook is bound to
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
description: Chatwoot webhook payload (see Chatwoot documentation)
responses:
'200':
description: Webhook processed (or acknowledged and ignored)
'401':
description: Invalid secret or signature, or payload account/inbox does not match the device's config
'503':
description: The device's config could not be read, so the request could not be authenticated, or an identical signed request is still being handled
/chatwoot/configs:
get:
operationId: chatwootListConfigs
tags:
- chatwoot
summary: List per-device Chatwoot configs
description: Returns every per-device Chatwoot routing config. API tokens are masked.
responses:
'200':
description: Configs retrieved
content:
application/json:
schema:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Chatwoot device configs
results:
type: array
items:
$ref: '#/components/schemas/ChatwootDeviceConfig'
/devices/{device_id}/chatwoot/config:
get:
operationId: chatwootGetDeviceConfig
tags:
- chatwoot
summary: Get a device's Chatwoot config
description: Returns the per-device Chatwoot routing config (API token masked).
parameters:
- $ref: '#/components/parameters/ChatwootConfigDeviceId'
responses:
'200':
description: Config retrieved
content:
application/json:
schema:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Chatwoot device config
results:
$ref: '#/components/schemas/ChatwootDeviceConfig'
'404':
description: Device not found (DEVICE_NOT_FOUND) or no config for this device (CONFIG_NOT_FOUND)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
put:
operationId: chatwootUpsertDeviceConfig
tags:
- chatwoot
summary: Create or update a device's Chatwoot config
description: |
Routes this device's messages to its own Chatwoot destination (URL + account +
inbox + token) instead of the global CHATWOOT_* env config.
The URL is canonicalized and validated (http/https only, no embedded
credentials, hosts resolving to private/loopback/link-local/metadata addresses
are rejected unless allowlisted via CHATWOOT_ALLOWED_HOSTS).
On update, an empty `api_token` — or the masked value echoed back from a GET —
keeps the stored token. Changing the routing identity (url/account/inbox) is
rejected with 409 once the config has linked conversations; delete and
recreate the config to rebind.
parameters:
- $ref: '#/components/parameters/ChatwootConfigDeviceId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- chatwoot_url
- account_id
- inbox_id
properties:
chatwoot_url:
type: string
example: 'https://chatwoot.example.com'
account_id:
type: integer
example: 1
inbox_id:
type: integer
example: 5
api_token:
type: string
description: Chatwoot agent/bot API token. Required on create; empty (or the masked value) keeps the stored token on update.
webhook_secret:
type: string
description: |
Webhook secret of this inbox's API channel. When set it protects every
webhook routed to this device (on `/chatwoot/webhook/{device_id}` and on
the shared `/chatwoot/webhook`) instead of
CHATWOOT_WEBHOOK_SECRET. Omit to keep the stored value; send an empty
string to remove it. Never returned by the API.
enabled:
type: boolean
default: true
responses:
'200':
description: Config saved
content:
application/json:
schema:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Chatwoot device config saved
results:
$ref: '#/components/schemas/ChatwootDeviceConfig'
'400':
description: Invalid request (INVALID_REQUEST) or rejected URL (INVALID_CHATWOOT_URL)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'404':
description: Device not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'409':
description: Routing identity change rejected while linked conversations exist (CONFIG_HAS_LINKED_CONVERSATIONS)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
delete:
operationId: chatwootDeleteDeviceConfig
tags:
- chatwoot
summary: Delete a device's Chatwoot config
description: |
Removes the device's Chatwoot routing config along with its stored message
links (stale links would otherwise keep answering reverse lookups for the old
destination after a rebind).
parameters:
- $ref: '#/components/parameters/ChatwootConfigDeviceId'
responses:
'200':
description: Config deleted
content:
application/json:
schema:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Chatwoot device config deleted
results:
type: object
properties:
device_id:
type: string
example: 'my-device-id'
/send/interactive:
post:
operationId: sendInteractive
tags: [send]
summary: Send an experimental interactive message
description: |
Immediate-only REST send for native-flow buttons, selection lists,
location requests, and carousels. Not supported by scheduled sends or MCP.
Uses an unofficial protocol; API success does not guarantee recipient
rendering or delivery. Accepts individual user or group recipients only.
Provide either buttons or cards. Overall HTTP body limits also apply.
parameters:
- $ref: '#/components/parameters/DeviceIdHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InteractiveSendRequest'
example:
phone: '628123456789'
body: Confirm your order?
buttons:
- name: quick_reply
params:
display_text: Confirm
id: confirm
responses:
'200':
description: Accepted for send; recipient rendering is unverified
content:
application/json:
schema:
$ref: '#/components/schemas/SendResponse'
'400':
description: Invalid recipient, text, button parameters, or image limits
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBadRequest'
'500':
description: Device, media upload, or WhatsApp send failure
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInternalServer'
components:
parameters:
DeviceIdHeader:
name: X-Device-Id
in: header
required: false
description: |
Device identifier for multi-device support. Required when multiple devices are registered.
If only one device is registered, it will be used as the default.
Can also be provided as `device_id` query parameter.
schema:
type: string
example: 'my-device-id'
ScheduleIdPath:
name: schedule_id
in: path
required: true
schema:
type: string
description: Schedule ID returned as `schedule_id` by a scheduled send
ChatwootConfigDeviceId:
name: device_id
in: path
required: true
description: Device ID (or WhatsApp JID) whose Chatwoot config is addressed
schema:
type: string
example: 'my-device-id'
securitySchemes:
basicAuth:
type: http
scheme: basic
schemas:
ChatwootDeviceConfig:
type: object
description: Per-device Chatwoot routing config (API token masked on every read)
properties:
device_id:
type: string
example: 'my-device-id'
device_jid:
type: string
description: WhatsApp JID of the device; stamped automatically at login (empty before pairing)
example: '[email protected]'
chatwoot_url:
type: string
example: 'https://chatwoot.example.com'
account_id:
type: integer
example: 1
inbox_id:
type: integer
example: 5
api_token:
type: string
description: Masked; only the last 4 characters are revealed
example: '****1234'
enabled:
type: boolean
example: true
webhook_url:
type: string
description: URL to set on this device's Chatwoot inbox so agent replies route back to this device
example: 'https://gowa.example.com/chatwoot/webhook/my-device-id'
webhook_secret_set:
type: boolean
description: Whether this device has its own webhook secret (the secret itself is never returned)
example: true
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
CreateGroupResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success get list groups
results:
type: object
properties:
group_id:
type: string
example: [email protected]
GroupInfoFromLinkResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success get group info from link
results:
type: object
properties:
group_id:
type: string
example: '[email protected]'
description: The group ID
name:
type: string
example: 'Example Group Name'
description: The group name
topic:
type: string
example: 'Welcome to our group! Please follow the rules.'
description: The group topic/description
created_at:
type: string
format: date-time
example: '2024-01-15T10:30:00Z'
description: When the group was created
participant_count:
type: integer
example: 25
description: Number of participants in the group
is_locked:
type: boolean
example: false
description: Whether the group is locked (only admins can modify group info)
is_announce:
type: boolean
example: false
description: Whether the group is in announce mode (only admins can send messages)
is_ephemeral:
type: boolean
example: false
description: Whether the group has disappearing messages enabled
description:
type: string
example: 'This group is for discussing project updates'
description: Additional description of the group
ManageParticipantRequest:
type: object
properties:
group_id:
type: string
example: [email protected]
participants:
type: array
items:
type: string
example:
- '6819241294719274'
- '6829241294719274'
- '6839241294719274'
ManageParticipantResponse:
type: object
additionalProperties: false
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success get list groups
results:
type: array
items:
type: object
additionalProperties: false
properties:
participant:
type: string
example: '[email protected]'
status:
type: string
example: success
message:
type: string
example: Participant added
GroupParticipantsResponse:
type: object
additionalProperties: false
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success getting group participants
results:
$ref: '#/components/schemas/GroupParticipantsResult'
GroupParticipantsResult:
type: object
additionalProperties: false
properties:
group_id:
type: string
example: '[email protected]'
name:
type: string
example: My Awesome Group
participants:
type: array
items:
$ref: '#/components/schemas/GroupParticipantItem'
GroupParticipantItem:
type: object
additionalProperties: false
properties:
jid:
type: string
example: '[email protected]'
phone_number:
type: string
example: '[email protected]'
lid:
type: string
nullable: true
example: '12345@lid'
display_name:
type: string
nullable: true
example: Anonymous Member
is_admin:
type: boolean
example: true
is_super_admin:
type: boolean
example: false
SetGroupPhotoResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success update group photo
results:
type: object
properties:
picture_id:
type: string
example: "1647874123"
description: The ID of the uploaded picture, or 'remove' if photo was removed
message:
type: string
example: Success update group photo
UserMyGroupItem:
type: object
description: |
One joined group as serialized `whatsmeow/types.GroupInfo`. Embedded structs are flattened; field names stay PascalCase (Go default JSON).
properties:
JID:
type: string
example: "[email protected]"
OwnerJID:
type: string
OwnerPN:
type: string
Name:
type: string
NameSetAt:
type: string
format: date-time
NameSetBy:
type: string
NameSetByPN:
type: string
GroupCreated:
type: string
format: date-time
CreatorCountryCode:
type: string
ParticipantVersionID:
type: string
ParticipantCount:
type: integer
Participants:
type: array
items:
$ref: '#/components/schemas/JoinedGroupParticipant'
MemberAddMode:
type: string
example: "admin_add"
Suspended:
type: boolean
AddressingMode:
type: string
IsLocked:
type: boolean
IsAnnounce:
type: boolean
AnnounceVersionID:
type: string
IsEphemeral:
type: boolean
DisappearingTimer:
type: integer
IsIncognito:
type: boolean
IsJoinApprovalRequired:
type: boolean
DefaultMembershipApprovalMode:
type: string
IsParent:
type: boolean
LinkedParentJID:
type: string
IsDefaultSubGroup:
type: boolean
Topic:
type: string
TopicID:
type: string
TopicDeleted:
type: boolean
TopicSetAt:
type: string
format: date-time
TopicSetBy:
type: string
TopicSetByPN:
type: string
JoinedGroupParticipant:
type: object
description: Serialized `whatsmeow/types.GroupParticipant` in joined-group list payloads.
properties:
JID:
type: string
description: Primary ID for the member (often `@lid`).
PhoneNumber:
type: string
description: User JID string when known (e.g. `[email protected]`); may be empty in edge cases.
LID:
type: string
IsAdmin:
type: boolean
IsSuperAdmin:
type: boolean
DisplayName:
type: string
description: Set for some anonymous / announcement cases; often empty.
Error:
type: integer
AddRequest:
type: object
nullable: true
UserGroupResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success get list groups
results:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/UserMyGroupItem'
UserInfoResponse:
type: object
required:
- code
- message
- results
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success
results:
type: object
properties:
verified_name:
type: string
example: Aldino Kemal
status:
type: string
example: Hello World
picture_id:
type: string
example: 1651459152
devices:
type: array
items:
type: object
properties:
User:
type: string
example: 6289685021291
Agent:
type: integer
example: 0
Device:
type: string
example: UNKNOWN
Server:
type: string
example: s.whatsapp.net
AD:
type: boolean
example: true
UserAvatarResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success
results:
type: object
properties:
url:
type: string
example: 'https://pps.whatsapp.net/v/t61.24694-24/181358562_385581386633509_6230178822944778044_n.jpg?ccb=11-4&oh=df36c5b990497b8a5758a0f1ad8118a8&oe=620AA726'
id:
type: string
example: '1635239861'
type:
type: string
example: 'image'
UserPrivacyResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success get privacy
results:
type: object
properties:
group_add:
type: string
example: all
last_seen:
type: string
example: null
status:
type: string
example: all
profile:
type: string
example: all
read_receipts:
type: string
example: all
SendResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success
results:
type: object
properties:
message_id:
type: string
example: '3EB0B430B6F8F1D0E053AC120E0A9E5C'
description: Omitted for scheduled sends
status:
type: string
example: '<feature> success ....'
schedule_id:
type: string
example: '0b5c3a8e-7f5d-4d6f-9d1e-2f8c1a7b9e10'
description: Scheduled sends only. Use it with the /send/schedules routes.
scheduled_at:
type: string
format: date-time
example: '2026-10-01T02:00:00Z'
description: Scheduled sends only. The first send time.
next_run_at:
type: string
format: date-time
example: '2026-10-01T02:00:00Z'
description: Scheduled sends only. When the worker sends next.
ScheduleOptions:
type: object
description: |
Optional fields that schedule the message instead of sending it now. Set
`scheduled_at` to schedule; without it the message is sent immediately.
A background worker sends it at the scheduled time, retrying while the
device is offline or not logged in. Uploaded media is stored on the
server until the schedule finishes.
In multipart/form-data bodies, send `weekdays` as a repeated field
(`weekdays=1`, `weekdays=3`).
properties:
scheduled_at:
type: string
format: date-time
example: '2026-10-01T09:00:00+07:00'
description: RFC3339 time of the first send. Must be in the future. The first send always happens at this time, even if it falls outside `weekdays` or `day_of_month`; those set the repeats that follow.
timezone:
type: string
example: Asia/Jakarta
description: IANA timezone used to compute recurring runs. Required when scheduled_at is set.
recurrence:
type: string
enum: [once, daily, weekly, monthly]
default: once
description: How often to repeat the send
weekdays:
type: array
items:
type: integer
minimum: 0
maximum: 6
uniqueItems: true
example: [1, 3, 5]
description: Days to send on, 0=Sunday through 6=Saturday. Required when recurrence is weekly.
day_of_month:
type: integer
minimum: 1
maximum: 31
example: 15
description: Day of the month to send on, clamped to the month's last day. Required when recurrence is monthly.
end_at:
type: string
format: date-time
example: '2026-12-31T23:59:59+07:00'
description: Recurring only. No sends happen after this time; must be after scheduled_at.
occurrence_limit:
type: integer
minimum: 1
example: 10
description: Recurring only. Stop after this many sends.
Schedule:
type: object
properties:
id:
type: string
example: '0b5c3a8e-7f5d-4d6f-9d1e-2f8c1a7b9e10'
message_type:
type: string
enum: [text, image, file, video, audio, sticker, contact, link, location, poll, forward]
example: text
phone:
type: string
example: '[email protected]'
summary:
type: string
example: selamat pagi
description: Short preview of the message
status:
type: string
enum: [active, running, paused, completed, failed, cancelled]
example: active
description: |
- `active`: waiting for its next run
- `running`: claimed by the worker and sending
- `paused`: held until resumed
- `completed`: no runs left
- `failed`: gave up after retries or a validation error
- `cancelled`: cancelled by the user
scheduled_at:
type: string
format: date-time
example: '2026-10-01T02:00:00Z'
next_run_at:
type: string
format: date-time
example: '2026-10-01T02:00:00Z'
description: Omitted when no run is left
timezone:
type: string
example: Asia/Jakarta
recurrence:
type: string
enum: [once, daily, weekly, monthly]
example: once
weekdays:
type: array
items:
type: integer
example: [1, 3, 5]
day_of_month:
type: integer
example: 15
end_at:
type: string
format: date-time
occurrence_limit:
type: integer
example: 10
occurrence_count:
type: integer
example: 0
description: Number of successful sends so far
attempts:
type: integer
example: 0
description: Failed attempts for the current run
last_run_at:
type: string
format: date-time
last_message_id:
type: string
example: '3EB0B430B6F8F1D0E053AC120E0A9E5C'
last_error:
type: string
created_at:
type: string
format: date-time
example: '2026-09-25T08:00:00Z'
updated_at:
type: string
format: date-time
example: '2026-09-25T08:00:00Z'
ScheduleResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Schedule fetched
results:
$ref: '#/components/schemas/Schedule'
ScheduleListResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Schedules fetched
results:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Schedule'
pagination:
type: object
properties:
limit:
type: integer
example: 25
offset:
type: integer
example: 0
total:
type: integer
example: 3
DeviceResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Fetch device success
results:
type: array
items:
type: object
properties:
name:
type: string
example: 'Aldino Kemal'
device:
type: string
description: Session ID registered via POST /devices (stable across restarts)
example: 'org_2'
jid:
type: string
description: WhatsApp JID of the logged-in account (empty until login)
example: '[email protected]'
# Device Management Schemas (v8)
DeviceListResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: List devices
status:
type: integer
example: 200
results:
type: array
items:
$ref: '#/components/schemas/DeviceInfo'
DeviceAddResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Device added
status:
type: integer
example: 200
results:
type: object
properties:
id:
type: string
example: 'my-device-id'
display_name:
type: string
example: 'John Doe'
state:
type: string
enum: [disconnected, connecting, connected, logged_in]
example: 'disconnected'
jid:
type: string
example: '[email protected]'
created_at:
type: string
format: date-time
example: '2024-01-01T00:00:00Z'
webhook_url:
type: string
description: Device-specific webhook URL echoed when provided on create
example: 'https://device-webhook.example.com/handler'
webhook_secret:
type: string
description: Device-specific webhook secret echoed when provided on create
example: 'super-secret-key'
webhook_events:
type: string
description: Device-specific event whitelist echoed when provided on create
example: 'message,message.ack'
webhook_insecure_skip_verify:
type: boolean
description: Device-specific TLS verification setting echoed when provided on create
example: false
DeviceInfoResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Device info
status:
type: integer
example: 200
results:
$ref: '#/components/schemas/DeviceInfo'
DeviceStatusResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Device status
status:
type: integer
example: 200
results:
type: object
properties:
device_id:
type: string
example: 'my-device-id'
is_connected:
type: boolean
example: true
is_logged_in:
type: boolean
example: true
DeviceLoginResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Login success
status:
type: integer
example: 200
results:
type: object
properties:
device_id:
type: string
example: 'my-device-id'
qr_link:
type: string
example: 'http://localhost:3000/statics/images/qrcode/scan-qr-b0b7bb43-9a22-455a-814f-5a225c743310.png'
qr_duration:
type: integer
example: 30
DeviceLoginWithCodeResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Login with code started
status:
type: integer
example: 200
results:
type: object
properties:
device_id:
type: string
example: 'my-device-id'
pair_code:
type: string
example: ABCD-1234
DeviceInfo:
type: object
properties:
id:
type: string
example: 'my-device-id'
phone_number:
type: string
example: '628123456789'
display_name:
type: string
example: 'John Doe'
state:
type: string
enum: [disconnected, connecting, connected, logged_in]
example: 'logged_in'
jid:
type: string
example: '[email protected]'
created_at:
type: string
format: date-time
example: '2024-01-01T00:00:00Z'
LoginWithCodeResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success
results:
type: object
properties:
pair_code:
type: string
example: ABCD-1234
LoginResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success
results:
type: object
properties:
qr_duration:
type: integer
example: 30
qr_link:
type: string
example: 'http://localhost:3000/statics/images/qrcode/scan-qr-b0b7bb43-9a22-455a-814f-5a225c743310.png'
PasskeyStatusResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Passkey pairing status
results:
type: object
properties:
device_id:
type: string
example: device-1
status:
type: string
enum: [none, awaiting_response, awaiting_confirmation]
example: awaiting_response
challenge:
type: object
nullable: true
description: WebAuthn assertion request options (PublicKeyCredentialRequestOptions JSON, base64url-encoded binary fields)
properties:
challenge:
type: string
example: dGVzdC1jaGFsbGVuZ2U
timeout:
type: integer
example: 60000
rpId:
type: string
example: whatsapp.com
allowCredentials:
type: array
items:
type: object
properties:
id:
type: string
type:
type: string
example: public-key
transports:
type: array
items:
type: string
userVerification:
type: string
example: required
code:
type: string
description: Pairing confirmation code (set while awaiting confirmation)
example: ABCD-EFGH
skip_handoff_ux:
type: boolean
example: false
WebAuthnAssertion:
type: object
description: WebAuthn assertion in PublicKeyCredential.toJSON() format (binary fields base64url-encoded without padding)
required: [id, rawId, type, response]
properties:
id:
type: string
example: XcnXe2W9me1XZTGii6JI9A
rawId:
type: string
example: XcnXe2W9me1XZTGii6JI9A
type:
type: string
example: public-key
response:
type: object
required: [clientDataJSON, authenticatorData, signature]
properties:
clientDataJSON:
type: string
authenticatorData:
type: string
signature:
type: string
userHandle:
type: string
nullable: true
GenericResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success
results:
type: string
example: null
ErrorInternalServer:
type: object
properties:
code:
type: string
example: INTERNAL_SERVER_ERROR
description: 'SYSTEM_CODE_ERROR'
message:
type: string
example: you are not loggin
description: 'Detail error message'
results:
type: object
example: null
description: 'additional data'
ErrorBadRequest:
type: object
properties:
code:
type: string
example: 400
description: 'HTTP Status Code'
message:
type: string
example: field cannot be blank
description: 'Detail error message'
results:
type: object
example: null
description: 'additional data'
ErrorUnauthorized:
type: object
properties:
code:
type: string
example: 401
description: 'HTTP Status Code'
message:
type: string
example: Unauthorized access
description: 'Detail error message'
results:
type: object
example: null
description: 'additional data'
ErrorForbidden:
type: object
properties:
code:
type: string
example: AVATAR_HIDDEN
description: 'SYSTEM_CODE_ERROR'
message:
type: string
example: the user has hidden their profile picture from you
description: 'Detail error message'
results:
type: object
description: 'additional data'
ErrorNotFound:
type: object
properties:
code:
type: string
example: 404
description: 'HTTP Status Code'
message:
type: string
example: Chat not found
description: 'Detail error message'
results:
type: object
example: null
description: 'additional data'
NewsletterResponse:
type: object
properties:
code:
type: string
example: "SUCCESS"
message:
type: string
example: "Success get list newsletter"
results:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Newsletter'
Newsletter:
type: object
properties:
id:
type: string
example: "120363144038483540@newsletter"
state:
type: object
properties:
type:
type: string
example: "active"
thread_metadata:
type: object
properties:
creation_time:
type: string
example: "1688746895"
invite:
type: string
example: "0029Va4K0PZ5a245NkngBA2M"
name:
type: object
properties:
text:
type: string
example: "WhatsApp"
id:
type: string
example: "1688746895480511"
update_time:
type: string
example: "1688746895480511"
description:
type: object
properties:
text:
type: string
example: "WhatsApp's official channel. Follow for our latest feature launches, updates, exclusive drops and more."
id:
type: string
example: "1689653839450668"
update_time:
type: string
example: "1689653839450668"
subscribers_count:
type: string
example: "0"
verification:
type: string
example: "verified"
picture:
type: object
properties:
url:
type: string
example: ""
id:
type: string
example: "1707950960975554"
type:
type: string
example: "IMAGE"
direct_path:
type: string
example: "/v/t61.24694-24/416962407_970228831134395_8869146381947923973_n.jpg?ccb=11-4&oh=01_Q5AaIIvOIeu3l0HCZWILrmr-dGR_vXFqnhUeytw0-ojPc4hL&oe=670D95B1&_nc_sid=5e03e0&_nc_cat=110"
preview:
type: object
properties:
url:
type: string
example: ""
id:
type: string
example: "1707950960975554"
type:
type: string
example: "PREVIEW"
direct_path:
type: string
example: "/v/t61.24694-24/416962407_970228831134395_8869146381947923973_n.jpg?stp=dst-jpg_s192x192&ccb=11-4&oh=01_Q5AaIHO-DQklqm3q3awF7xwji_WAn9DkgZASQA0B2Ct0qbSa&oe=670D95B1&_nc_sid=5e03e0&_nc_cat=110"
settings:
type: object
properties:
reaction_codes:
type: object
properties:
value:
type: string
example: "ALL"
viewer_metadata:
type: object
nullable: true
description: Null when viewer-specific metadata is unavailable.
properties:
mute:
type: string
example: "off"
role:
type: string
example: "subscriber"
NewsletterInfoResponse:
type: object
properties:
code:
type: string
example: "SUCCESS"
message:
type: string
example: "Success get newsletter info"
results:
$ref: '#/components/schemas/Newsletter'
NewsletterDirectoryResponse:
type: object
properties:
code:
type: string
example: "SUCCESS"
message:
type: string
example: "Success search newsletter directory"
results:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Newsletter'
next_cursor:
type: string
example: "GTby6Oiy0/jOqwPYxYXQtvjOqwPC0uaVue3OqwMZ"
has_more:
type: boolean
example: true
NewsletterLiveUpdatesSubscription:
type: object
properties:
newsletter_id:
type: string
example: '120363024512399999@newsletter'
duration_seconds:
type: integer
example: 90
expires_at:
type: string
example: "2026-10-28T17:37:28Z"
renewed_at:
type: string
example: "2026-10-28T17:35:58Z"
last_error:
type: string
description: Last renewal error, cleared after a successful renewal
NewsletterLiveUpdatesResponse:
type: object
properties:
code:
type: string
example: "SUCCESS"
message:
type: string
example: "Success subscribe newsletter live updates"
results:
$ref: '#/components/schemas/NewsletterLiveUpdatesSubscription'
NewsletterLiveUpdatesListResponse:
type: object
properties:
code:
type: string
example: "SUCCESS"
message:
type: string
example: "Success list newsletter live updates"
results:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/NewsletterLiveUpdatesSubscription'
NewsletterMessagesResponse:
type: object
properties:
code:
type: string
example: "SUCCESS"
message:
type: string
example: "Success get newsletter messages"
results:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/NewsletterMessage'
NewsletterMessage:
type: object
properties:
server_id:
type: integer
example: 123
message_id:
type: string
example: "3EB0XXXXXXXXXXXXXXXX"
type:
type: string
example: "text"
timestamp:
type: string
example: "2026-06-30T10:00:00Z"
views_count:
type: integer
description: Only reported to channel admins; 0 otherwise
example: 42
forwards_count:
type: integer
example: 7
reaction_counts:
type: object
additionalProperties:
type: integer
example: { "😀": 3, "👍": 5 }
text:
type: string
example: "Hello from the channel!"
NewsletterMediaDownloadResponse:
type: object
properties:
status:
type: integer
example: 200
code:
type: string
example: SUCCESS
message:
type: string
example: Media downloaded successfully
results:
type: object
properties:
server_id:
type: integer
example: 8872
message_id:
type: string
example: ACBD7F85529AAD63FAF376F622351D14
status:
type: string
example: Media downloaded successfully to statics/media/120363024512399999/2026-08-28/image.jpg
media_type:
type: string
enum: [image, video, video_note, audio, document, sticker]
example: image
mime_type:
type: string
example: image/jpeg
filename:
type: string
example: image.jpg
file_path:
type: string
description: Local server path where the downloaded media was saved
example: statics/media/120363024512399999/2026-08-28/image.jpg
file_url:
type: string
description: Public URL for the saved media file
example: http://localhost:3000/statics/media/120363024512399999/2026-08-28/image.jpg
file_size:
type: integer
format: int64
example: 524288
MyListContactsResponse:
type: object
properties:
code:
type: string
example: "SUCCESS"
message:
type: string
example: "Success get list contacts"
results:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/MyListContacts'
MyListContacts:
type: object
properties:
jid:
type: string
example: "[email protected]"
name:
type: string
example: "Aldino Kemal"
GroupParticipantRequestItem:
type: object
properties:
jid:
type: string
description: Requester's JID; often `@lid` until a phone mapping exists locally.
example: "84198740205822@lid"
phone_number:
type: string
description: |
Digits from the resolved `@s.whatsapp.net` JID when LID→PN mapping is available.
Empty when only `@lid` is known — the LID user part is not a phone number and must not be shown here.
example: "6289685024091"
display_name:
type: string
description: From saved contact, verified business name, or WhatsApp-supplied display (may be omitted when empty).
example: "John Doe"
requested_at:
type: string
format: date-time
example: "2026-03-27T23:18:47Z"
GroupParticipantRequestListResponse:
type: object
properties:
code:
type: string
example: "SUCCESS"
message:
type: string
example: "Success getting list requested participants"
results:
type: array
description: Pending join requests for the group (not wrapped in `data`).
items:
$ref: '#/components/schemas/GroupParticipantRequestItem'
UserCheckResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success check user
results:
type: object
properties:
is_on_whatsapp:
type: boolean
example: true
BusinessProfileResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success get business profile
results:
type: object
properties:
jid:
type: string
example: '[email protected]'
description: Business account JID
email:
type: string
example: '[email protected]'
description: Business email address
address:
type: string
example: '123 Business Street, City, Country'
description: Business physical address
categories:
type: array
description: Business categories
items:
type: object
properties:
id:
type: string
example: 'retail'
name:
type: string
example: 'Retail Store'
profile_options:
type: object
description: Additional profile options
example:
website: 'https://example.com'
description: 'Business description'
business_hours_timezone:
type: string
example: 'Asia/Jakarta'
description: Business hours timezone
business_hours:
type: array
description: Business operating hours
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'
ChatListResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success get chat list
results:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Chat'
pagination:
type: object
properties:
limit:
type: integer
example: 25
offset:
type: integer
example: 0
total:
type: integer
example: 150
Chat:
type: object
properties:
jid:
type: string
example: '[email protected]'
description: Chat JID identifier
name:
type: string
example: 'John Doe'
description: Chat display name
last_message_time:
type: string
format: date-time
example: '2024-01-15T10:30:00Z'
description: Timestamp of the last message
ephemeral_expiration:
type: integer
example: 0
description: Ephemeral message expiration time in seconds (0 = disabled)
created_at:
type: string
format: date-time
example: '2024-01-10T08:00:00Z'
description: Chat creation timestamp
updated_at:
type: string
format: date-time
example: '2024-01-15T10:30:00Z'
description: Chat last update timestamp
archived:
type: boolean
example: false
description: Whether the chat is archived
ChatMessagesResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success get chat messages
results:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ChatMessage'
pagination:
type: object
properties:
limit:
type: integer
example: 50
offset:
type: integer
example: 0
total:
type: integer
example: 1250
chat_info:
$ref: '#/components/schemas/Chat'
ChatMessage:
type: object
properties:
id:
type: string
example: '3EB0B430B6F8F1D0E053AC120E0A9E5C'
description: Message ID
chat_jid:
type: string
example: '[email protected]'
description: Chat JID this message belongs to
sender_jid:
type: string
example: '[email protected]'
description: Sender JID
sender_display_name:
type: string
example: 'Saved Contact'
description: >-
Human-readable sender label resolved dynamically when this response is produced, not stored with the message.
For other senders, it prefers the saved contact full name, then the stored contact push name, business name,
JID user part, and raw JID. For the active account, it prefers the device display name (falling back to the
stored account push name), account JID user part, account JID, sender JID user part, and raw sender JID.
A contact rename can therefore change the label returned for historical messages. `sender_jid` remains the
stable sender identifier.
content:
type: string
example: 'Hello, how are you?'
description: Message text content
timestamp:
type: string
format: date-time
example: '2024-01-15T10:30:00Z'
description: Message timestamp
is_from_me:
type: boolean
example: false
description: Whether this message was sent by the current user
media_type:
type: string
example: 'image'
nullable: true
description: Type of media (image, video, audio, document, etc.). Value `call` indicates a stored incoming call log.
reactions:
type: array
description: Emoji reactions attached to this message
items:
$ref: '#/components/schemas/ChatReaction'
call_metadata:
type: string
example: '{"call_id":"ABC","auto_rejected":false}'
description: JSON string with call details when media_type is `call`. Omitted when not applicable (matches Go json omitempty).
referral_metadata:
type: string
example: '{"ctwa_clid":"clid_123","source_app":"whatsapp"}'
description: JSON string with Meta Ads referral/attribution details when the message originated from a Click-to-WhatsApp ad. Omitted when not applicable (matches Go json omitempty).
context_metadata:
type: string
example: '{"replied_to_id":"AC625C65EA7143E71D784176C4A90A93"}'
description: JSON string containing the replied-to message ID when reply context is known. Captured from live, sent, and history-sync messages. Omitted when no reply context is available, including older stored rows until they are reingested with context.
filename:
type: string
example: 'photo.jpg'
nullable: true
description: Original filename for media messages
url:
type: string
example: 'https://media.example.com/file.jpg'
nullable: true
description: Media file URL
file_length:
type: integer
example: 1024768
nullable: true
description: File size in bytes for media messages
created_at:
type: string
format: date-time
example: '2024-01-15T10:30:00Z'
description: Record creation timestamp
updated_at:
type: string
format: date-time
example: '2024-01-15T10:30:00Z'
description: Record last update timestamp
ChatReaction:
type: object
properties:
emoji:
type: string
example: '👍'
description: Emoji used in the reaction
sender_jid:
type: string
example: '[email protected]'
description: JID of the user who reacted
sender_display_name:
type: string
example: 'Saved Contact'
description: >-
Human-readable sender label resolved dynamically when this response is produced, not stored with the reaction.
For other senders, it prefers the saved contact full name, then the stored contact push name, business name,
JID user part, and raw JID. For the active account, it prefers the device display name (falling back to the
stored account push name), account JID user part, account JID, sender JID user part, and raw sender JID.
A contact rename can therefore change the label returned for historical reactions. `sender_jid` remains the
stable sender identifier.
is_from_me:
type: boolean
example: false
description: Whether the reaction was made by the current user
timestamp:
type: string
format: date-time
example: '2024-01-15T10:31:00Z'
description: When the reaction was received
RequestChatHistoryResponse:
type: object
properties:
status:
type: integer
example: 200
code:
type: string
example: SUCCESS
message:
type: string
example: History sync requested successfully
results:
type: object
properties:
status:
type: string
example: requested
chat_jid:
type: string
example: '[email protected]'
requested_count:
type: integer
example: 50
anchor_message_id:
type: string
example: '3EB0C767D82B0A0D1234'
anchor_timestamp:
type: string
format: date-time
example: '2026-05-16T08:00:00Z'
PinChatResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Chat pinned successfully
results:
type: object
properties:
status:
type: string
example: success
message:
type: string
example: Chat pinned successfully
chat_jid:
type: string
example: '[email protected]'
pinned:
type: boolean
example: true
SetDisappearingTimerResponse:
type: object
properties:
status:
type: integer
example: 200
code:
type: string
example: SUCCESS
message:
type: string
example: Disappearing messages set to 86400 seconds
results:
type: object
properties:
status:
type: string
example: success
message:
type: string
example: Disappearing messages set to 86400 seconds
chat_jid:
type: string
example: '[email protected]'
timer_seconds:
type: integer
example: 86400
ArchiveChatResponse:
type: object
properties:
status:
type: integer
example: 200
code:
type: string
example: SUCCESS
message:
type: string
example: Chat archived successfully
results:
type: object
properties:
status:
type: string
example: success
message:
type: string
example: Chat archived successfully
chat_jid:
type: string
example: '[email protected]'
archived:
type: boolean
example: true
GroupInfoResponse:
type: object
properties:
status:
type: integer
example: 200
code:
type: string
example: SUCCESS
message:
type: string
example: Success get group info
results:
type: object
description: Group information object (structure may vary)
additionalProperties: true
GetGroupInviteLinkResponse:
type: object
properties:
code:
type: string
example: SUCCESS
message:
type: string
example: Success get group invite link
results:
type: object
properties:
invite_link:
type: string
example: 'https://chat.whatsapp.com/ABC123...'
description: The group invite link
group_id:
type: string
example: '[email protected]'
description: The group ID
ChatwootSyncResponse:
type: object
properties:
status:
type: integer
example: 200
code:
type: string
example: SYNC_STARTED
message:
type: string
example: History sync initiated in background
results:
type: object
properties:
device_id:
type: string
example: my-device-id
days_limit:
type: integer
example: 3
include_media:
type: boolean
example: true
include_groups:
type: boolean
example: true
ChatwootSyncStatusResponse:
type: object
properties:
status:
type: integer
example: 200
code:
type: string
example: SUCCESS
message:
type: string
example: Sync status retrieved
results:
type: object
properties:
device_id:
type: string
example: my-device-id
status:
type: string
enum: [idle, running, completed, failed]
example: running
total_chats:
type: integer
example: 10
synced_chats:
type: integer
example: 5
total_messages:
type: integer
example: 100
synced_messages:
type: integer
example: 50
failed_messages:
type: integer
example: 2
current_chat:
type: string
example: "[email protected]"
started_at:
type: string
format: date-time
completed_at:
type: string
format: date-time
error:
type: string
InteractiveNativeFlowButton:
type: object
required: [name, params]
properties:
name:
type: string
enum: [quick_reply, cta_url, cta_copy, cta_call, single_select, send_location]
params:
type: object
additionalProperties: true
description: |
Maximum 16384 JSON bytes. quick_reply requires display_text and id;
cta_url requires display_text and an absolute HTTP(S) url;
cta_copy requires display_text and copy_code;
cta_call requires display_text and phone_number.
single_select requires title and nonempty sections, each with
nonempty rows whose id and title are nonempty strings.
send_location accepts an object such as {} and must be the sole
button in a non-carousel message. All named text parameters must
be nonempty strings.
InteractiveCarouselCard:
type: object
required: [body, buttons]
properties:
title:
type: string
description: Maximum 256 bytes.
body:
type: string
description: Required nonblank text, maximum 4096 bytes.
footer:
type: string
description: Maximum 256 bytes.
image_base64:
type: string
description: |
Optional raw standard base64 JPEG or PNG, without a data URL prefix.
Maximum 2800000 encoded characters and 2000000 decoded bytes, also
subject to the configured image limit. Maximum 4096 pixels per side.
Resized, JPEG-encoded, thumbnailed, and uploaded before sending.
buttons:
type: array
minItems: 1
maxItems: 10
items:
$ref: '#/components/schemas/InteractiveNativeFlowButton'
InteractiveSendRequest:
type: object
required: [phone, body]
properties:
phone:
type: string
description: Phone number or full individual user or group JID.
body:
type: string
description: Required nonblank text, maximum 4096 bytes.
footer:
type: string
description: Maximum 256 bytes.
buttons:
type: array
minItems: 1
maxItems: 10
items:
$ref: '#/components/schemas/InteractiveNativeFlowButton'
cards:
type: array
minItems: 2
maxItems: 10
items:
$ref: '#/components/schemas/InteractiveCarouselCard'
oneOf:
- required: [buttons]
not:
required: [cards]
- required: [cards]
not:
required: [buttons]