Skip to main content

07 - API Specification

The tables below follow the controllers in apps/api/src/**/*.controller.ts: pnpm check:api-contract fails when a route is missing from them. For interactive exploration, use Swagger UI at <API base host>:<API port>/api/docs.

7.1 Overview​

PropertyValue
Base URL (Docker)http://localhost:3333/api/v1
Base URL (local dev)http://localhost:3000/api/v1
Swagger UI<API host>:<port>/api/docs
Global prefixapi/v1 (from app.setGlobalPrefix('api/v1') in apps/api/src/main.ts)
FormatJSON
AuthBearer Token or x-api-key header

All endpoint paths in this document are relative to the base URL. For example, POST /messages/text resolves to POST http://localhost:3333/api/v1/messages/text under the Docker default.


7.2 Authentication​

Bearer Token​

Authorization: Bearer YOUR_JWT_TOKEN

Issued by POST /auth/register and POST /auth/login. Refresh with POST /auth/refresh.

API Key​

x-api-key: YOUR_API_KEY

The Swagger UI registers the API key under the api-key security scheme; the header name is lowercase x-api-key. Create keys in the dashboard, or with POST /api-keys while signed in: an API key cannot create another.

API-key scopes​

A key can carry a list of scopes. A route that asks for a scope answers 403 to a key whose list lacks it. A key with no scope list, or with *, keeps full access. A scope only narrows a key: it still acts with its user's role (see Roles below), so messages:write on a viewer's key sends nothing.

Scope (its name in the dashboard)Routes it guards
messages:read (Read Messages)GET /conversations, GET /conversations/unread-count, GET /conversations/:id, GET /conversations/:id/messages, GET /messages/:id, GET /messages/profile/:profileId, GET /messages/conversation/:conversationId and its /load-older, GET /messages/schedule/:profileId
messages:write (Send Messages)every POST /messages/... (the sends, schedule and otp included), DELETE /messages/:id, DELETE /messages/schedule/:id; PUT /conversations/:id/read, /archive, /unarchive, /mute and /pin, DELETE /conversations/:id, DELETE /conversations/:id/messages; POST /calls/:id/reply and POST /calls/:id/call-link
contacts:read (Read Contacts)GET /contacts, GET /contacts/:id, GET /contacts/export/csv, and the number checks GET /contacts/profile/:profileId/validate/:phone and POST /contacts/profile/:profileId/validate
contacts:write (Manage Contacts)the other contact routes: POST /contacts, PUT and DELETE /contacts/:id, POST and DELETE /contacts/:id/tags, POST /contacts/import, /contacts/import/csv and /contacts/sync/whatsapp, POST /contacts/profile/:profileId/save-to-whatsapp, DELETE /contacts/profile/:profileId/whatsapp/:phone
customers:read (Read Customers)every GET /customers/...: the search, a customer, a number's customers, the lookup and its preview, the history, the notes and the lookup settings
customers:write (Manage Customers)the other customer routes: POST /customers/links, POST /customers/links/:linkId/use, DELETE /customers/links/:linkId, PATCH and DELETE /customers/:id, POST /customers/:id/notes, PATCH and DELETE /customers/:id/notes/:noteId, PUT /customers/config and POST /customers/config/test
profiles:read (Read Profiles)GET /profiles, GET /profiles/:id, GET /profiles/:id/status, GET /accounts/:accountId/profiles, GET /accounts/:accountId/profiles/:profileId
profiles:write (Manage Profiles)POST /profiles, PUT and DELETE /profiles/:id, POST /profiles/:id/connect and /disconnect, PUT /profiles/:id/calls-settings, POST, GET and DELETE /profiles/:id/calls-announcement; under /accounts/:accountId/profiles: the create, the delete, connect, disconnect and GET .../:profileId/qr; and the pairing QR on the socket
webhooks:read (Read Webhooks)GET /webhooks, GET /webhooks/:id (they show each webhook's signing secret and custom headers)
webhooks:write (Manage Webhooks)POST /webhooks, PUT and DELETE /webhooks/:id, POST /webhooks/:id/test
broadcast:write (Send Broadcasts)POST /broadcast, PUT and DELETE /broadcast/:id, POST /broadcast/:id/schedule, /start, /pause, /resume and /cancel; POST /bulk/send and POST /bulk/batch/:batchId/cancel. Their reads ask for no scope
recordings:read (Read Recordings)GET /calls/:id/recording
recordings:delete (Delete Recordings)DELETE /calls/:id/recording, and, together with profiles:write, a PUT /profiles/:id/calls-settings that carries retentionDays

Every other route asks for no scope. On the socket, the pairing QR (qr:update) needs profiles:write too; the rest of the events need none (WebSocket API).

Roles​

Each organization member has one role. An API key acts with its user's role, at the time of each request.

RoleMay
viewerread; their own account: sign-in and sign-out, password, preferences, sessions, 2FA, notifications, API keys, and deleting the account
memberas a viewer, plus send messages one at a time, upload media, work the chats (read, archive, pin, mute), schedule messages, handle calls (answer, follow-up, assign, reject, reply, call link), add and edit contacts and their tags, link numbers to customers and write their notes and tags, use the AI routes
adminas a member, plus configure the organization, accounts, profiles, workspaces, broadcasts, automation, auto-replies, webhooks, templates, the knowledge base, groups, contact import and sync, send and cancel bulk batches, delete chats, delete customers and set the customer lookup, read webhooks and audit logs, export contacts, and manage members and viewers
owneras an admin, plus manage admins

A viewer's reads include the lookups that are POSTs: a template preview, an automation test, a number check and a knowledge-base search. A few reads are for owners and admins only (webhooks, audit logs, the exports, a group's invite link, the auto-reply hooks' settings, call recordings, the calls media status, a profile's call announcement and the QR route): the notes under each section below say which.

The server-wide settings (/settings/*) and the integrations (/integrations/*) are for the server's owner: the owner of the oldest organization. A role that may not call a route gets 403. scripts/api-roles.snapshot.json lists each route's class; the CI checks it against the code.


7.3 Response Format​

Success Response​

A response is the JSON of what was asked for, with no envelope around it: an object, or a list.

{ "id": "0b6c1e1a-3f5a-4c1e-9a52-7d1f5c3e8b41", "displayName": "Sales", "status": "connected" }

Error Response​

An error has its HTTP status, and a body with the status, a message and the status's name:

{ "statusCode": 403, "message": "Resource not found in your organization", "error": "Forbidden" }
  • On the routes of your workspaces' resources (profiles, contacts, conversations, calls and the like), an id outside your organization, or of nothing at all, is this 403: the API does not say which.
  • The customer routes (/customers/...) answer 404 instead, for an id outside your organization as for an id of nothing.
  • A validation error (400) lists every problem in message.
  • Some errors carry a code of their own in error: a send through a disconnected profile is 409 PROFILE_DISCONNECTED, and the send gate's 429 is { "error": "DAILY_LIMIT_REACHED", … } without statusCode (see Messaging).
  • A refusal with reasons is 409 { "message": "…", "reasons": ["…"] }, from the call settings and the announcement (see Calls).

7.4 Endpoints​

The tables below mirror the @Controller(...) decorators in apps/api/src/. Use them as the authoritative endpoint list; if Swagger and this document diverge, Swagger wins.

Auth (/auth)​

MethodEndpointDescription
POST/auth/registerRegister an account, with its organization, and receive tokens. Open to the first user of a new server; after that it answers 403 unless ALLOW_REGISTRATION is true
GET/auth/registrationWhether registration is open: { "open": boolean } (public)
POST/auth/loginLog in and receive tokens
POST/auth/2fa/verifyVerify a 2FA challenge during login
POST/auth/refreshExchange refresh token for a new access token
POST/auth/logoutInvalidate the current session
GET/auth/meGet the current user
GET/auth/preferencesGet user preferences
PATCH/auth/preferencesUpdate user preferences
POST/auth/change-passwordChange the current user's password
DELETE/auth/accountDelete the current user account (an owner's deletes their organization; the server's owner gets 403 while other organizations use the server)
POST/auth/2fa/setupBegin 2FA enrollment
POST/auth/2fa/enableConfirm and enable 2FA
POST/auth/2fa/disableDisable 2FA
POST/auth/2fa/backup-codesGenerate 2FA backup codes
GET/auth/sessionsList active sessions
DELETE/auth/sessions/:idRevoke a specific session
DELETE/auth/sessionsRevoke all sessions except current

Health (/health)​

MethodEndpointDescription
GET/healthLiveness probe
GET/health/readyReadiness probe

Accounts (/accounts)​

Every role reads, except the QR route, which is for owners and admins and also needs profiles:write on an API key with a scope list (scopes). Owners and admins create, change and delete accounts, and create, delete, connect and disconnect their profiles.

MethodEndpointDescription
GET/accountsList accounts
POST/accountsCreate account
GET/accounts/:idGet account
PUT/accounts/:idUpdate account
DELETE/accounts/:idDelete account
GET/accounts/:accountId/profilesList profiles inside an account
POST/accounts/:accountId/profilesCreate a profile in an account
GET/accounts/:accountId/profiles/:profileIdGet profile (account-scoped)
DELETE/accounts/:accountId/profiles/:profileIdDelete profile (account-scoped)
POST/accounts/:accountId/profiles/:profileId/connectStart WhatsApp connection
POST/accounts/:accountId/profiles/:profileId/disconnectDisconnect
GET/accounts/:accountId/profiles/:profileId/qrA placeholder: answers { "qr": null, "status": "pending" } whatever the profile's state. The QR arrives over the WebSocket as qr:update, to owners and admins (WebSocket API), and the dashboard shows it on the profile's page

Profiles (/profiles) — flat alternative to the account-scoped routes​

Every role lists and reads profiles, and their status. Owners and admins create, change, delete, connect and disconnect profiles, set their call settings, and upload, listen to or remove their announcement.

MethodEndpointDescription
GET/profilesList profiles
POST/profilesCreate profile
GET/profiles/:idGet profile
PUT/profiles/:idUpdate profile
PUT/profiles/:id/calls-settingsThe profile's call settings: answerInDashboard, recording, retentionDays (1-3650); 409 with reasons when one cannot be turned on
POST/profiles/:id/calls-announcementUpload the announcement callers hear before a recorded call (multipart file: mp3, wav, ogg, webm or m4a, at most 2 MB and 30 seconds; half a second more is allowed for encoders' padding)
GET/profiles/:id/calls-announcementThe profile's announcement, to listen to
DELETE/profiles/:id/calls-announcementRemove the announcement (409 while recording is on; its file goes at a nightly sweep once it is an hour old)
DELETE/profiles/:idDelete profile
POST/profiles/:id/connectStart WhatsApp connection
POST/profiles/:id/disconnectDisconnect
GET/profiles/:id/statusGet connection status

No /profiles route returns the QR either: after POST /profiles/:id/connect it arrives over the WebSocket as qr:update (WebSocket API), to the owners and admins that joined the profile.

Messages (/messages)​

Owners, admins and members send; deleting a stored message (DELETE /messages/:id) is for owners and admins.

MethodEndpointDescription
POST/messages/textSend text message
POST/messages/otpSend an OTP with delivery-confirmed failover to a secondary channel
POST/messages/imageSend image
POST/messages/videoSend video
POST/messages/audioSend audio/voice
POST/messages/documentSend document
POST/messages/locationSend location
POST/messages/contactSend contact card
POST/messages/reactionSend a reaction
POST/messages/replySend a quoted reply
POST/messages/pollSend poll
POST/messages/typingSet typing presence
POST/messages/mark-readMark messages read
POST/messages/delete-for-everyoneDelete message for everyone
POST/messages/scheduleSchedule a message
GET/messages/schedule/:profileIdList scheduled messages for a profile
DELETE/messages/schedule/:idCancel a scheduled message
GET/messages/profile/:profileIdList messages for a profile
GET/messages/conversation/:conversationIdList messages in a conversation
GET/messages/conversation/:conversationId/load-olderFetch older messages from WhatsApp and persist them
GET/messages/:idGet a single message
DELETE/messages/:idDelete a message locally

Message lists answer at most 500 rows per request (limit).

Disconnected profile. The endpoints that deliver a message (text, image, video, audio, document, location, contact, reaction, reply, poll) answer 409 Conflict when the profile has no live WhatsApp connection, instead of reporting success:

{ "statusCode": 409, "error": "PROFILE_DISCONNECTED", "message": "Profile is not connected; the message was not sent" }

The message is stored with status: "failed" and a message.failed event is emitted. Nothing is retried automatically, so reconnect the profile and send again. POST /messages/otp does not return the 409: it fails over to its secondary channel, or answers 502 OTP_DELIVERY_FAILED when no channel delivers. Bulk batches, broadcasts and scheduled messages record the message as failed instead of returning an error. With DURABLE_SEND=true a send is enqueued instead and retried a bounded number of times before it ends failed (see Durable Sending).

Send timeout. The same endpoints answer 504 Gateway Timeout with "error": "SEND_TIMEOUT" when the WhatsApp engine has not finished the send after SEND_TIMEOUT_MS (60 s by default). The message is stored as failed and message.failed is emitted, but WhatsApp may still deliver it, so a retry can send it twice. See Send Gate.

Bulk Messaging (/bulk)​

Every role reads batches. Sending a batch and cancelling one are for owners and admins, and an API key with a scope list needs broadcast:write for both. A member sends one message at a time (Messages).

MethodEndpointDescription
POST/bulk/sendSend bulk messages with variables
GET/bulk/batchesList batches
GET/bulk/batch/:batchIdGet batch status
POST/bulk/batch/:batchId/cancelCancel batch

Broadcast (/broadcast)​

MethodEndpointDescription
POST/broadcastCreate a broadcast campaign
GET/broadcastList broadcasts
GET/broadcast/:idGet broadcast
PUT/broadcast/:idUpdate broadcast
DELETE/broadcast/:idDelete broadcast
POST/broadcast/:id/scheduleSchedule broadcast
POST/broadcast/:id/startStart broadcast immediately
POST/broadcast/:id/pausePause broadcast
POST/broadcast/:id/resumeResume broadcast
POST/broadcast/:id/cancelCancel broadcast
GET/broadcast/:id/statsBroadcast delivery stats
GET/broadcast/:id/recipientsBroadcast recipient list

Groups (/groups)​

Every role lists and reads groups. Everything else is for owners and admins, the invite link included: GET /groups/:groupId/invite-link is a read that only they may make.

MethodEndpointDescription
GET/groups/profile/:profileIdList groups for a profile
GET/groups/:groupIdGet group info
POST/groupsCreate group
PATCH/groups/:groupIdUpdate group
POST/groups/:groupId/participants/addAdd participants
POST/groups/:groupId/participants/removeRemove participants
POST/groups/:groupId/participants/promotePromote to admin
POST/groups/:groupId/participants/demoteDemote from admin
POST/groups/:groupId/leaveLeave group
GET/groups/:groupId/invite-linkGet invite link
POST/groups/:groupId/invite-link/revokeRevoke invite link

Conversations (/conversations)​

An API key needs messages:read for the reads and messages:write for the changes.

MethodEndpointDescription
GET/conversationsList conversations
GET/conversations/unread-countTotal unread message count across the org
GET/conversations/:idGet conversation
GET/conversations/:id/messagesList messages in conversation
PUT/conversations/:id/readMark conversation read
PUT/conversations/:id/archiveArchive
PUT/conversations/:id/unarchiveUnarchive
PUT/conversations/:id/muteMute
PUT/conversations/:id/pinPin
DELETE/conversations/:idDelete conversation
DELETE/conversations/:id/messagesClear messages in conversation

Calls (/calls)​

Incoming WhatsApp calls, stored per profile and published as the call.received, call.answered, call.rejected, call.ended and call.updated webhook events; a call's recording sends call.recording.ready when it is stored and call.recording.deleted when it is deleted.

MethodEndpointDescription
GET/callsList calls of a profile, newest first (profileId required; filters outcome, followUp, from (caller JID or phone number, e.g. 628111000111), since (ISO 8601 date); paging limit 1-100, cursor)
GET/calls/open-countOpen call follow-ups across the org
GET/calls/media/statusReadiness of answering calls in the dashboard and of recording them: the media server, the recordings storage and every profile of the organization (owner or admin)
GET/calls/:idGet a call
PATCH/calls/:idUpdate the follow-up status (open, in_progress, done) or the assignee
POST/calls/:id/rejectReject a call that is still ringing
POST/calls/:id/replySend a text to the caller (default: the profile's callReplyMessage)
POST/calls/:id/call-linkCreate a WhatsApp call link (voice / video) and send it to the caller
GET/calls/:id/recordingThe call's recording, audio/webm (owner or admin; HTTP Range; ?download=1 as an attachment; audited)
DELETE/calls/:id/recordingDelete the call's recording (owner or admin)

reply and call-link send a WhatsApp message to the caller, so they behave like a send from /messages:

  • API-key scope. An API key with an explicit scope list needs messages:write (Send Messages) for them, and gets 403 without it. Keys with no scopes or with *, and JWT logins, skip this check. The reads, PATCH and reject ask for no scope.
  • Send gate. The text goes through the profile's send gate (see Messaging): it waits out the pacing delay and can be refused with 429 and a code in the body. DAILY_LIMIT_REACHED and REPEAT_SUPPRESSED (the same text to the same caller within a minute, by default) can happen at any time; COLD_DAILY_LIMIT_REACHED and COLD_CIRCUIT_OPEN only once the service window has closed. An incoming call opens the service window (serviceWindowHours, 24 hours by default) the way an incoming message does, so answering a recent call is a reply, not cold outreach. With DURABLE_SEND=true or ENGINE_HOST=worker the text is queued instead (the message in the response has status: "queued"), and a delivery failure arrives as a message.failed webhook.

Other errors of the call actions:

StatusWhen
409reject: the call is not ringing any more. Any action: the profile is not connected. call-link: the engine cannot create call links (Baileys)
422reply or call-link for a group call
502The text to the caller was not sent, or WhatsApp returned no call link
504reject or the creation of the call link: WhatsApp did not answer in time (about 30 seconds)

Auto-reject. A profile with autoRejectCalls on (set with PUT /profiles/:id) rejects a ringing call at once (rejectedBy is auto). A non-blank autoRejectCallMessage is then sent to the caller, also when the reject failed because the caller had already hung up. That reply goes through the same send gate and is sent at most once per caller per 24 hours; it is never sent for a group call or for a call known only from its call log. A reply the gate refuses or the engine fails to send is not retried and does not use up the 24 hours, so the caller's next call can try again.

Recordings. A call answered in the dashboard on a profile with recording on is recorded from before the profile's announcement, in stereo: left the caller, right what the caller heard. A call answered with video is recorded with its pictures too: the caller full frame, the agent's camera in a corner while it is on. When the recorder does not start or the announcement does not play, the call goes on unrecorded. A recording is stored when its call ends (call.recording.ready). Each call in GET /calls and GET /calls/:id has recording: null, or the recording's facts:

  • id, mimeType (audio/webm, or video/webm for a call answered with video), durationSec, bytes, announcementPlayed, createdAt;
  • partial: it may end before its call did (cut short by a restart, a recorder that did not stop cleanly, or a write that failed);
  • once its file is deleted, deletedAt and deleteReason (admin or retention). The row stays as evidence.

The audio itself:

  • Owner or admin only, on a call of their organization. An API key with an explicit scope list needs recordings:read to play or download and recordings:delete to delete. Such a key also needs profiles:write for PUT /profiles/:id/calls-settings, the announcement routes and deleting a profile (DELETE /profiles/:id, DELETE /accounts/:accountId/profiles/:profileId, which delete its recordings too), and recordings:delete as well to change retentionDays (a shorter period deletes recordings). Keys with no scopes or with * skip these checks.
  • GET /calls/:id/recording answers 200, or 206 for a Range: bytes=… request, with Accept-Ranges: bytes and Cache-Control: private, no-store.
    • Only one range is served: a list is answered whole. A range past the end is 416.
    • ?download=1 adds Content-Disposition: attachment.
    • Every read is audited (call.recording.play, call.recording.download, with the IP and user agent) before its first byte: once every 10 minutes per user, address, user agent, recording and action, whatever range it asks for, so a player's seeks do not flood the audit log and no range escapes it. A request that cannot be audited is refused with 503.
    • A HEAD answers the same headers without the audio, and is audited as a read.
    • 404 when the call has no recording, it was deleted, its file is missing, or it is stored in another location than this server uses now (see Call recordings). 503 while the recordings storage is not configured, or when it does not answer (try again).
  • DELETE /calls/:id/recording deletes the file and answers { callId, recordingId, deletedAt }. It is audited as call.recording.delete and sends the call.recording.deleted webhook. A recording already deleted is 404, and one stored in another location 409; while the recordings storage is not configured, the answer is 503.
  • A browser player cannot point an <audio> element at this route: the route needs the Authorization (or x-api-key) header. Fetch the file with the header, then play what was fetched.

The answers. Dates are ISO 8601 strings.

RouteAnswer
GET /calls{ calls, nextCursor }: a page of calls, newest first. Pass nextCursor as cursor for the next page; it is null on the last one
GET /calls/open-count{ count }
GET /calls/:id, PATCH /calls/:id, POST /calls/:id/rejectthe call
POST /calls/:id/reply{ call, message }: the call, and the message sent (success, messageId, conversationId, status, and waMessageId once it went out)
POST /calls/:id/call-link{ call, message, link }
GET /calls/media/statusthe readiness (below)
GET /calls/:id/recordingthe audio (above)
DELETE /calls/:id/recording{ callId, recordingId, deletedAt }
PUT /profiles/:id/calls-settings{ profileId, answerInDashboard, recording, retentionDays, announcement }, the settings as stored
POST /profiles/:id/calls-announcement{ profileId, announcement: { mimeType, durationSec } }
GET /profiles/:id/calls-announcementthe audio, with its stored Content-Type
DELETE /profiles/:id/calls-announcement{ profileId, announcement: null }

A call:

FieldMeaning
id, profileId, waCallIdMultiWA's id of the call, its profile, and WhatsApp's id of the call
fromJidThe caller: 628111000111@s.whatsapp.net, or an @lid id when WhatsApp hides the number
isVideo, isGroup, directiondirection is incoming
outcomeringing, answered (in the dashboard), missed, rejected, answered_elsewhere or unknown
rejectedByauto, agent or device, for a rejected call
startedAt, endedAtWhen it started ringing, and when it stopped; for an answered call, when the conversation ended
followUp, assignedUserId, assignedUserThe follow-up (open, in_progress or done), and who it is assigned to ({ id, name })
answeredByUserId, answeredBy, answeredAtThe agent who answered it in the dashboard ({ id, name }), once outcome is answered
endedBy, endReason, talkSecondsHow an answered call ended: by the agent, the caller or the server; hangup, caller_hangup, agent_lost, media_failed, time_limit or server_restart; and the talk time in seconds (null when not known)
autoReplySentAtWhen the auto-reject reply was sent
conversationId, conversationThe caller's chat ({ id, name }), once there is one
metadataDetails, such as the call links sent
recordingnull, or the recording's facts (above)
createdAt, updatedAt

PATCH /calls/:id takes followUp and assignedUserId; assignedUserId: null unassigns the call, and an assignee must be an active owner, admin or member of the organization. It, reject, reply and call-link are for owners, admins and members; a viewer gets 403. The media status, the recordings, the call settings and the announcement are for owners and admins.

GET /calls/media/status (owner or admin) answers the media server's readiness, its recordings storage, and each profile of the organization:

{
"server": {
"enabled": true,
"worker": "up",
"port": 40000,
"engineHost": "api",
"activeSessions": 0,
"videoCalls": { "active": 0, "max": 2 },
"recordings": { "storage": "local", "configured": true, "problem": null, "lastCheck": { "at": "2026-11-03T02:30:00.000Z", "ok": true } }
},
"profiles": [
{ "profileId": "0b6c1e1a-3f5a-4c1e-9a52-7d1f5c3e8b41", "name": "Sales", "answerInDashboard": true, "recording": false, "retentionDays": 90, "announcement": null, "ready": true, "reasons": [], "video": true }
]
}
  • server.enabled is true when CALLS_MEDIA_ENABLED=true and the engines run in the API (ENGINE_HOST is not worker); worker is up or down; port is null while disabled; engineHost must be api for answering in the dashboard; activeSessions counts the organization's calls connecting or connected in the dashboard; videoCalls.active counts those of them answered with video, and videoCalls.max is the server's cap (CALLS_MAX_VIDEO_CALLS), shared with every organization.
  • server.recordings: storage is local or s3; configured: false with problem naming the missing or refused setting; lastCheck is the last check that the storage refuses reads without credentials (its reason when it failed: storage_not_private, storage_check_failed, or recordings_storage_unset from the nightly check while no storage is configured).
  • Each profile has its call settings, ready, the reasons it is not ready, and video: whether its video calls are answered with video now (ready, and its WhatsApp Web can).

Turning answerInDashboard on answers 409 with reasons when the profile is not ready: engine_host_worker, media_disabled, media_server_down, auto_reject_on, profile_not_connected, engine_not_supported, and those of its WhatsApp Web page: not_ready, web_calling_disabled, voip_stack_unavailable, module_missing, hooks_missing, not_prepared and page_error. Calls answered in the dashboard says what each one means.

Turning recording on answers 409 with reasons when it cannot be on:

  • no_announcement;
  • recordings_storage_unset (see Call recordings);
  • storage_not_private: the storage serves its files without credentials, and recording is turned off on every profile;
  • storage_check_failed: the check proved nothing; try again.

A true sent for a setting that is already on (recording or answerInDashboard) is left as it is, without a check, so a form may send every field. DELETE /profiles/:id/calls-announcement answers 409 (recording_on) while recording is on.

The announcement upload answers 413 past 2 MB, 415 for another format or a file that cannot be read, 422 past 30 seconds (counted from the audio itself: an mp3's frames, a wav's samples; half a second more is allowed for encoders' padding) or for a file that does not say how long it is (a browser recording, for one), and 503 while two other announcements are being read or the recordings storage does not answer (as GET /profiles/:id/calls-announcement does then). It answers 400 without a file, and 409 (recordings_storage_unset) while the recordings storage is not configured. A new announcement replaces the profile's previous one, whose file, like a removed one's, goes at a nightly sweep once it is an hour old.

Contacts (/contacts)​

Owners, admins and members add and edit contacts and tags; deleting, importing, syncing and exporting, and saving contacts to or deleting them from the WhatsApp address book, are for owners and admins. Every role may validate numbers.

MethodEndpointDescription
GET/contactsList contacts
POST/contactsCreate contact
GET/contacts/:idGet contact
PUT/contacts/:idUpdate contact
DELETE/contacts/:idDelete contact
POST/contacts/importImport contacts
POST/contacts/import/csvImport contacts from CSV
GET/contacts/export/csvExport contacts as CSV
POST/contacts/:id/tagsAdd tags
DELETE/contacts/:id/tagsRemove tags
GET/contacts/profile/:profileId/validate/:phoneValidate a single phone number on WhatsApp
POST/contacts/profile/:profileId/validateValidate a batch of phone numbers
POST/contacts/sync/whatsappSync contacts from WhatsApp
POST/contacts/profile/:profileId/save-to-whatsappSave a contact into the WhatsApp account addressbook (whatsapp-web-js only)
DELETE/contacts/profile/:profileId/whatsapp/:phoneDelete a contact from the WhatsApp account addressbook (whatsapp-web-js only)

Contact lists answer at most 1000 rows per request (limit), and a bulk validation takes at most 1000 numbers.

Customers (/customers)​

The guide, with the lookup contract and an example endpoint: Customers.

A customer is an ID in the organization's own system, linked to WhatsApp numbers. Every role reads, but for the preview of an ID that is not linked yet, which owners, admins and members make. Owners, admins and members link numbers, write notes and change tags; a note is changed by its author, an owner or an admin. Owners and admins delete customers and change the lookup settings. Another organization's customer, link or note answers 404.

MethodEndpointDescription
GET/customersSearch by ID (prefix), linked number or name (q); page, pageSize (at most 100)
GET/customers/configThe lookup settings: idLabel, lookupUrl, hasSecret, timeoutMs, configured (the secret is never sent)
PUT/customers/configChange the lookup settings: an empty lookupUrl turns the lookup off, an omitted secret keeps it, an empty one clears it (owner or admin)
POST/customers/config/testOne lookup of an externalId with the saved settings, bypassing the cache (owner or admin)
GET/customers/lookupPreview the lookup of an externalId that is not linked yet; stores nothing (owner, admin or member). At most 30 a minute for each user, or for each API key when the request came with one; past that, 429 "Too many lookups, try again shortly"
GET/customers/by-phone/:phoneThe customers linked to a number, its default first
POST/customers/linksLink a number to a customer ID (externalId, phone): 201 with a new link, 200 with one that existed
POST/customers/links/:linkId/useMake a link its number's default
DELETE/customers/links/:linkIdRemove a link; the customer, its notes and tags stay
GET/customers/:idA customer with its links, tags, manual fields and 20 newest notes
PATCH/customers/:idChange tags; displayName and manualFields only while no lookup is configured (else 409)
DELETE/customers/:idDelete a customer with its links and notes (owner or admin)
GET/customers/:id/lookupThe live lookup: ok, not_found, unavailable or not_configured (refresh=true skips the minute's cache)
GET/customers/:id/historyThe organization's one-to-one chats and calls with the customer's numbers, newest first (limit at most 50)
GET/customers/:id/notesThe notes, newest first (page, pageSize at most 100)
POST/customers/:id/notesAdd a note (body, 1 to 2000 characters)
PATCH/customers/:id/notes/:noteIdEdit a note: its author, an owner or an admin
DELETE/customers/:id/notes/:noteIdDelete a note: its author, an owner or an admin

Templates (/templates)​

MethodEndpointDescription
POST/templatesCreate template
GET/templatesList templates
GET/templates/:idGet template
PUT/templates/:idUpdate template
DELETE/templates/:idDelete template
POST/templates/:id/previewRender preview with variables
POST/templates/:id/duplicateDuplicate template

Webhooks (/webhooks)​

Owner and admin only, reads included (they carry the signing secret). A key with webhooks:read reads each webhook's signing secret and custom headers.

MethodEndpointDescription
POST/webhooksCreate webhook
GET/webhooksList webhooks
GET/webhooks/:idGet webhook
PUT/webhooks/:idUpdate webhook
DELETE/webhooks/:idDelete webhook
POST/webhooks/:id/testSend a test event

Removed: the legacy global /hooks registry has been retired. Use the organization-scoped /webhooks endpoints above — they sign every delivery with an HMAC X-MultiWA-Signature header and are isolated per tenant.

Automation (/automation)​

MethodEndpointDescription
POST/automationCreate automation flow
GET/automationList automation flows
GET/automation/:idGet flow
PUT/automation/:idUpdate flow
DELETE/automation/:idDelete flow
PUT/automation/:id/toggleToggle active flag
POST/automation/:id/testTest a flow with sample input
GET/automation/:id/statsFlow execution stats
POST/automation/reorderReorder the profile's flows (an id that is not one of them: 404, nothing changes)

Auto-reply (/autoreply)​

Every role lists and reads the rules and the quick replies. Owners and admins create, change, toggle and delete them, configure the two hooks, and read the hooks' settings (GET /autoreply/webhook-reply/:profileId and GET /autoreply/ai-hook/:profileId).

MethodEndpointDescription
POST/autoreply/quick-repliesCreate a quick reply
GET/autoreply/quick-repliesList quick replies
DELETE/autoreply/quick-replies/:idDelete a quick reply
POST/autoreplyCreate an auto-reply rule
GET/autoreplyList auto-reply rules
GET/autoreply/:idGet rule
PUT/autoreply/:idUpdate rule
DELETE/autoreply/:idDelete rule
PUT/autoreply/:id/toggleToggle active flag
POST/autoreply/webhook-replyConfigure webhook-driven reply
GET/autoreply/webhook-reply/:profileIdGet webhook-reply config
POST/autoreply/ai-hookConfigure AI-driven reply
GET/autoreply/ai-hook/:profileIdGet AI-hook config

AI (/ai and /ai/knowledge)​

MethodEndpointDescription
GET/ai/statusAI provider status
POST/ai/completeGeneric completion
POST/ai/auto-replyGenerate an auto-reply suggestion
POST/ai/sentimentSentiment scoring
POST/ai/translateTranslate text
POST/ai/knowledge/:profileId/textIngest text into the knowledge base
GET/ai/knowledge/:profileIdList knowledge documents
DELETE/ai/knowledge/:idDelete a knowledge document
POST/ai/knowledge/:profileId/searchSearch the knowledge base

API Keys (/api-keys)​

MethodEndpointDescription
GET/api-keysList API keys
POST/api-keysCreate API key (signed in; a request made with an API key gets 403)
DELETE/api-keys/:idRevoke API key

Settings (/settings)​

The server's owner only (the owner of the oldest organization).

MethodEndpointDescription
GET/settings/storageGet storage settings
PUT/settings/storageUpdate storage settings
POST/settings/storage/testTest storage configuration
GET/settings/smtpGet SMTP settings
PUT/settings/smtpUpdate SMTP settings
POST/settings/smtp/testTest SMTP configuration

Uploads (/uploads)​

MethodEndpointDescription
POST/uploads/mediaUpload media for use in messages

Integrations (/integrations)​

The server's owner only: the integrations configuration comes from the server's environment.

MethodEndpointDescription
GET/integrations/configGet integration config
PUT/integrations/configUpdate integration config
POST/integrations/testTest integration connectivity

Statistics (/statistics)​

MethodEndpointDescription
GET/statistics/dashboardDashboard summary
GET/statistics/messagesMessage totals
GET/statistics/messages/trendMessage volume trend
GET/statistics/contactsContact stats
GET/statistics/broadcastsBroadcast stats
GET/statistics/automationsAutomation stats
GET/statistics/response-timeResponse-time stats

Audit (/audit)​

Owners and admins only.

MethodEndpointDescription
GET/audit/logsList audit log entries
GET/audit/summaryAudit summary
GET/audit/actionsAudit action catalog

Notifications (/notifications)​

MethodEndpointDescription
GET/notificationsList notifications
GET/notifications/unread-countUnread count
PATCH/notifications/:id/readMark a notification read
PATCH/notifications/read-allMark all read
DELETE/notifications/:idDelete one
DELETE/notificationsDelete all
GET/notifications/push/vapid-keyWeb Push VAPID public key
GET/notifications/push/subscriptionsList push subscriptions
POST/notifications/push/subscribeRegister a push subscription
POST/notifications/push/unsubscribeRemove a push subscription
POST/notifications/push/testSend a test push notification

Organizations (/organizations)​

MethodEndpointDescription
GET/organizations/currentGet current organization
PUT/organizations/currentUpdate current organization. It keeps settings.customers whatever settings it is sent: only PUT /customers/config changes it
GET/organizations/membersList members
POST/organizations/membersInvite a member
PUT/organizations/members/:id/roleChange member role
DELETE/organizations/members/:idRemove member

Workspaces (/workspaces)​

Every role reads. Owners and admins create, change and delete workspaces.

MethodEndpointDescription
GET/workspacesList workspaces
POST/workspacesCreate workspace
GET/workspaces/:idGet workspace
PUT/workspaces/:idUpdate workspace
DELETE/workspaces/:idDelete workspace

GDPR (/account)​

MethodEndpointDescription
GET/account/exportExport the caller's own data (user, sessions, notifications, push subscriptions, audit log) and the organization's profiles, messages (the newest 10000), contacts, automations and customers (with their links, notes and tags). Owners and admins only
DELETE/account/deleteDelete account and personal data. The organization stays, so an owner gets 403: an owner deletes their account with DELETE /auth/account, which deletes the organization too

7.5 Example: Send Bulk with Variables​

Bulk sends are for owners and admins: the key must be an owner's or an admin's, and, with a scope list, carry broadcast:write.

curl -X POST http://localhost:3333/api/v1/bulk/send \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"profileId": "profile-123",
"messages": [
{
"chatId": "628123456789@c.us",
"type": "text",
"content": { "text": "Hello {name}!" },
"variables": { "name": "John" }
},
{
"chatId": "628987654321@c.us",
"type": "text",
"content": { "text": "Hello {name}!" },
"variables": { "name": "Jane" }
}
],
"options": {
"delayBetweenMessages": 5000,
"randomizeDelay": true
}
}'

← Engine Abstraction · Documentation Index · WebSocket API →