API Reference

API Documentation

Base URL: https://api.waumfy.com

Authentication

Most endpoints require a JWT access token in the Authorization header. Custom API trigger and Phone endpoints use an API key in the X-API-Key header.

Authorization: Bearer <access_token>

X-API-Key: sl_your_key_here

WebSocket (Socket.IO)

Connect with your JWT token for real-time QR codes, session status, and incoming messages.

io('https://api.waumfy.com', { auth: { token: '<jwt>' } })

qr:update{ sessionId, qr }

session:status{ sessionId, status, phoneNumber? }

message:received{ sessionId, from, messageId, message }

Webhook Events

Events are dispatched as HTTP POST requests to your configured webhook URL. Each payload is HMAC-signed via the X-Waumfy-Signature header.

MESSAGE_RECEIVEDFired when an inbound message arrives on any connected session.

sessionIdstringYour WhatsApp session ID

fromstringSender JID (e.g. 919XXXXXXXXX@s.whatsapp.net)

senderPhonestringSender phone number (digits only)

senderNamestring | nullPush name set by the sender

messageIdstringUnique WhatsApp message ID

timestampnumberUnix timestamp (seconds)

bodystring | nullText content or caption; null for audio/sticker

pttbooleanAudio only — true if voice note (push-to-talk), false if audio file

durationnumber | nullAudio only — length in seconds

mimetypestring | nullAudio only — MIME type (e.g. audio/ogg; codecs=opus)

quotedMessageIdstringPresent only when message is a reply

quotedBodystring | nullText of the quoted message (replies only)

MESSAGE_DELIVEREDFired when an outbound message reaches the recipient's device.

messageIdstringWhatsApp message ID

tostringRecipient JID

MESSAGE_READFired when the recipient opens and reads an outbound message.

messageIdstringWhatsApp message ID

tostringRecipient JID

Action Payload Reference

JSON body for every action type when triggering via POST /api/apis/trigger/:slug.

Send TextSEND_TEXT

Send a plain text message.

{
  "to": "919XXXXXXXXX",
  "text": "Hello! Your order has been confirmed."
}

Send Text + ImageSEND_TEXT_IMAGE

Send an image with a text caption.

{
  "to": "919XXXXXXXXX",
  "imageUrl": "https://example.com/promo.jpg",
  "text": "Check out our latest offer!"
}

Send ImageSEND_MEDIA

Send an image file.

{
  "to": "919XXXXXXXXX",
  "mediaType": "image",
  "mediaUrl": "https://example.com/photo.jpg",
  "caption": "Here is your receipt"
}

Send VideoSEND_MEDIA

Send a video file.

{
  "to": "919XXXXXXXXX",
  "mediaType": "video",
  "mediaUrl": "https://example.com/demo.mp4",
  "caption": "Watch our product demo"
}

Send DocumentSEND_MEDIA

Send a PDF or document file.

{
  "to": "919XXXXXXXXX",
  "mediaType": "document",
  "mediaUrl": "https://example.com/invoice.pdf",
  "fileName": "invoice.pdf"
}

Send Voice NoteSEND_MEDIA

Send an OGG/Opus file as an inline voice note with waveform.

{
  "to": "919XXXXXXXXX",
  "mediaType": "audio",
  "mediaUrl": "https://example.com/message.ogg",
  "ptt": true
}

Send Audio FileSEND_MEDIA

Send an MP3/M4A/WAV as a regular audio attachment.

{
  "to": "919XXXXXXXXX",
  "mediaType": "audio",
  "mediaUrl": "https://example.com/track.mp3",
  "ptt": false
}

Send LocationSEND_LOCATION

Send GPS coordinates with a name and address label.

{
  "to": "919XXXXXXXXX",
  "latitude": "28.6139",
  "longitude": "77.2090",
  "name": "India Gate",
  "address": "New Delhi, India"
}

Send Contact CardSEND_CONTACT

Send a vCard contact that the recipient can save.

{
  "to": "919XXXXXXXXX",
  "contactName": "Rahul Sharma",
  "contactPhone": "919876543210"
}

Send ReactionSEND_REACTION

React to any message with an emoji.

{
  "to": "919XXXXXXXXX",
  "messageId": "3A22367A5402F21231C4",
  "emoji": "👍"
}

Reply To MessageREPLY_TO_MESSAGE

Send a quoted reply to a specific message.

{
  "to": "919XXXXXXXXX",
  "messageId": "3A22367A5402F21231C4",
  "text": "Got it! Delivering by 5pm.",
  "quotedText": "When will my order arrive?"
}

Delete MessageDELETE_MESSAGE

Recall/delete a message sent by your session.

{
  "to": "919XXXXXXXXX",
  "messageId": "3A22367A5402F21231C4"
}

Check NumberCHECK_NUMBER

Check if a phone number has WhatsApp.

{
  "phone": "919XXXXXXXXX"
}
// Response: { "exists": true, "jid": "919XXXXXXXXX@s.whatsapp.net" }

Get Group IDGET_GROUP_ID

Find a group ID by name (fuzzy match).

{
  "groupName": "Sales Team"
}
// Response: { "groups": [{ "id": "120363...@g.us", "name": "Sales Team", "participantCount": 12 }] }

Get Group MembersGET_GROUP_MEMBERS

List all members of a group with their roles.

{
  "groupId": "120363408831987455@g.us"
}
// Response: { "name": "Sales Team", "memberCount": 12, "members": [{ "phone": "919...", "role": "admin" }] }

Get Profile PictureGET_PROFILE_PIC

Fetch a contact's profile picture URL.

{
  "phone": "919XXXXXXXXX"
}
// Response: { "phone": "919XXXXXXXXX", "url": "https://pps.whatsapp.net/..." }

Mark As ReadMARK_AS_READ

Mark a received message as read.

{
  "to": "919XXXXXXXXX",
  "messageId": "3A22367A5402F21231C4"
}

Custom JSONCUSTOM_JSON

Send any Baileys message type — no restrictions. Pass raw content in the content field.

{
  "to": "919XXXXXXXXX",
  "content": {
    "poll": {
      "name": "Preferred time?",
      "values": ["Morning", "Afternoon", "Evening"],
      "selectableCount": 1
    }
  }
}

Authentication

POST/api/auth/registerCreate a new account

POST/api/auth/loginGet access + refresh tokens

POST/api/auth/refreshRotate refresh token

GET/api/auth/meGet current user profileAuth

Sessions

GET/api/sessionsList all WhatsApp sessionsAuth

POST/api/sessionsCreate a new session (QR via WS)Auth

POST/api/sessions/:id/sendSend a text messageAuth

POST/api/sessions/:id/disconnectDisconnect a sessionAuth

DELETE/api/sessions/:idDelete session + cleanupAuth

Messages

GET/api/messagesList message logs (paginated)Auth

GET/api/messages/:idGet a single messageAuth

Broadcasts

GET/api/broadcastsList all broadcast campaignsAuth

POST/api/broadcastsCreate a new broadcastAuth

POST/api/broadcasts/:id/pausePause a running broadcastAuth

POST/api/broadcasts/:id/resumeResume a paused broadcastAuth

POST/api/broadcasts/:id/cancelCancel a broadcastAuth

Custom API Actions

GET/api/apisList all custom API actionsAuth

POST/api/apisCreate a custom API actionAuth

DELETE/api/apis/:idDelete a custom API actionAuth

POST/api/apis/trigger/:slugTrigger an action (API key auth)

Phones (programmatic)

GET/api/apis/phonesList your WhatsApp numbersAPI Key

POST/api/apis/phonesAdd a number — body: { name }API Key

GET/api/apis/phones/:idGet a number + connection statusAPI Key

GET/api/apis/phones/:id/qrFetch the pairing QR to connectAPI Key

DELETE/api/apis/phones/:idRemove a numberAPI Key

Webhooks

GET/api/webhooksList outgoing webhooksAuth

POST/api/webhooksCreate an outgoing webhookAuth

DELETE/api/webhooks/:idDelete a webhookAuth

API Keys

GET/api/api-keysList your API keysAuth

POST/api/api-keysGenerate a new API keyAuth

DELETE/api/api-keys/:idRevoke an API keyAuth

Subscriptions

GET/api/subscriptions/plansList available plans

POST/api/subscriptions/validate-couponValidate a coupon codeAuth

POST/api/subscriptions/subscribeSubscribe to a planAuth

GET/api/subscriptions/myGet active subscriptionAuth