WhatsApp Business API

Getting Started & Authentication

1.1 Base URLs

NextMavens exposes two URLs -- use the one that matches your integration needs:

ServiceBase URLUse For
WhatsApp APIhttps://whatsapp.nextmavens.cloudDirect API calls -- send messages, manage instances, webhooks (Evolution API)
Admin Dashboardhttps://admin.nextmavens.cloudManage clients, create instances, scan QR codes, monitor status

1.2 Credentials You Need

When NextMavens provisions your account, you will receive three distinct credentials. Each serves a different purpose:

CredentialTypeWhere to Find ItUsed For
Master API Key128-char hex stringAdmin Dashboard -- System Keys (top-right menu) or welcome email from NextMavensCreating & managing instances, admin operations. Sent as apikey header on all Evolution API calls.
Instance NameString (your choice)Admin Dashboard -- Instances tab -- the name you or NextMavens assigned when creating the instanceURL path parameter identifying which WhatsApp number to use (e.g. /message/sendText/mycompany-sales)
Instance API Key64-char hex stringResponse field hash.apikey after creating an instance, or Admin Dashboard -- Instances -- view instance detailsPer-instance authentication -- replaces the master key for calls scoped to a specific instance
IMPORTANT: The Master API Key and Instance API Key are different. The Master key can create and manage all instances. The Instance key is scoped to a single WhatsApp number -- use it when your application sends messages for that specific instance. Keep both secret -- never expose them in client-side code or public repositories.

1.3 How to Structure Your API Requests

Every request to the Evolution API requires an apikey header. You can use either your Master API Key or the Instance API Key:

curl -X POST https://whatsapp.nextmavens.cloud/message/sendText/mycompany-sales \
  -H "apikey: YOUR_INSTANCE_OR_MASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": "254712345678", "text": "Hello!"}'

Admin API calls (via the Express proxy at https://admin.nextmavens.cloud) use a different auth mechanism -- a JWT Authorization token obtained from POST /api/login:

curl -X POST https://admin.nextmavens.cloud/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "your_admin_user", "password": "your_password"}'
# Returns: { "token": "eyJhbGciOi..." }
# Then use: Authorization: Bearer eyJhbGciOi...

1.4 Quick Integration Checklist

  1. Receive credentials -- NextMavens sends you your Master API Key and admin dashboard login via email, or you pick them up from the dashboard after account creation.
  2. Log in to the Admin Dashboard -- Go to https://admin.nextmavens.cloud and log in with your admin credentials.
  3. Create a WhatsApp Instance -- Navigate to the Instances tab, click "Create Instance", give it a name (e.g. mycompany-sales), and link it to your client account.
  4. Copy the Instance API Key -- After creation, the response includes hash.apikey. Save this -- it's your per-instance token.
  5. Connect via QR Code -- Click "Connect" on your instance, scan the QR code with your WhatsApp mobile app (Settings -- Linked Devices -- Link a Device).
  6. Verify connection -- Wait for the instance status to show open (green). This means the WhatsApp session is active.
  7. Test a message -- Use the Instance API Key and instance name to send a test message via POST /message/sendText/{instanceName}.
  8. Integrate into your application -- Use the base URL https://whatsapp.nextmavens.cloud with the apikey header in your backend code. See the endpoint reference below for all available operations.
NOTE: This guide covers direct Evolution API integration. If you prefer a managed approach, NextMavens also provides an Admin API proxy with JWT authentication -- contact support for details.

Instance Management

Instance Management

Instance Management

An 'instance' represents one WhatsApp phone number connection. Each company can have multiple instances one per phone number they want to use.

1.1 Create an Instance

POST /instance/create

{
  "instanceName": "mycompany-sales",
  "integration": "WHATSAPP-BAILEYS",
  "qrcode": true,
  "number": "",
  "token": "optional-custom-token"
}
WARNING: Save the hash.apikey value from the response. This is the per-instance token used for all subsequent calls to this instance. It is different from your global API key.

1.2 Get QR Code (for reconnection)

GET /instance/connect/{instanceName}

Use when instance is disconnected and user needs to re-scan QR.

1.3 Check Instance Status

GET /instance/connectionState/{instanceName}

StatusMeaning
openConnected and ready to send/receive messages
connectingQR was scanned, waiting for full connection
closeDisconnected user needs to re-scan QR code
refusedConnection was refused by WhatsApp servers

1.4 Fetch All Instances

GET /instance/fetchInstances

1.5 Delete an Instance

DELETE /instance/delete/{instanceName}

WARNING: Deleting an instance removes the WhatsApp session permanently. The phone number can be reconnected by creating a new instance.

Sending Messages

Sending Messages

Sending Messages

WARNING: Always check that instance status is 'open' before sending messages. Sending to a disconnected instance returns a 400 error.

2.1 Send Text Message

POST /message/sendText/{instanceName}

{
  "number": "254712345678",
  "text": "Hello from NextMavens API!",
  "delay": 1200
}

Parameters:

  • number: Always include country code, no + or spaces
  • delay: Delay in ms (RECOMMENDED: 1000-3000 ms)

2.2 Send Image

POST /message/sendMedia/{instanceName}

{
  "number": "254712345678",
  "mediatype": "image",
  "mimetype": "image/jpeg",
  "caption": "Check this out!",
  "media": "https://example.com/image.jpg",
  "delay": 2000
}

2.3 Send Document / PDF

{
  "number": "254712345678",
  "mediatype": "document",
  "mimetype": "application/pdf",
  "caption": "Invoice #1234",
  "fileName": "invoice_1234.pdf",
  "media": "BASE64_ENCODED_PDF_DATA"
}

2.4 Send Audio (Voice Note)

{
  "number": "254712345678",
  "audio": "BASE64_ENCODED_AUDIO",
  "encoding": true
}
NOTE: For audio, always send pure base64 without the data:audio/ogg;base64, prefix. Set encoding: true so Evolution API converts it to WhatsApp's PTT format.

2.5 Send Media — Image, Video, Document, Audio File

POST /message/sendMedia/{instanceName}

The sendMedia endpoint supports four media types:

FieldRequiredDescription
numberYesPhone with country code, no +
mediatypeYesimage, video, document, or audio
mediaYesPublic URL or base64 data URI
captionNoCaption (works with image, video, document)
fileNameRequired for documentDisplay filename with extension
mimetypeNoMIME type — auto-detected from URL
delayNoDelay in ms (1000–3000 recommended)

Send an Image

{
  "number": "254712345678",
  "mediatype": "image",
  "media": "https://example.com/photo.jpg",
  "caption": "Check this out!",
  "delay": 2000
}

Send a Video

{
  "number": "254712345678",
  "mediatype": "video",
  "media": "https://example.com/clip.mp4",
  "caption": "Watch this!",
  "delay": 3000
}

Send a Document (PDF, CSV, etc.)

{
  "number": "254712345678",
  "mediatype": "document",
  "media": "https://example.com/invoice.pdf",
  "fileName": "Invoice-2024-04.pdf",
  "caption": "Your monthly invoice",
  "delay": 2000
}
IMPORTANT: The fileName field is required when mediatype is document. Without it, the file appears as "unknown" on the recipient's phone.

Send an Audio File (Music/Podcast)

{
  "number": "254712345678",
  "mediatype": "audio",
  "media": "https://example.com/podcast.mp3",
  "delay": 2000
}
NOTE: Using sendMedia with mediatype: "audio" sends the file as a music attachment. To send as a voice note (plays through earpiece, shows waveform bubble), use section 2.6 below.

2.6 Send Voice Note (WhatsApp Audio Bubble)

POST /message/sendWhatsAppAudio/{instanceName}

Sends audio as a WhatsApp voice note — appears as a dark bubble with play button and waveform, plays through the earpiece.

{
  "number": "254712345678",
  "audio": "data:audio/mpeg;base64,SUQzAwAAAA...",
  "encoding": true
}
FieldRequiredDescription
numberYesPhone with country code, no +
audioYesBase64 audio or public URL
encodingNoAuto-convert to WhatsApp OGG/OPUS format
NOTE: Set encoding: true to auto-convert MP3/WAV to OGG/OPUS. Supported inputs: MP3, WAV, OGG, M4A, FLAC.

2.7 Send Location

POST /message/sendLocation/{instanceName}

{
  "number": "254712345678",
  "name": "Nairobi CBD",
  "address": "Kenyatta Avenue, Nairobi, Kenya",
  "latitude": -1.2921,
  "longitude": 36.8219
}
FieldRequiredDescription
latitudeYesGPS latitude
longitudeYesGPS longitude
nameYesLocation name shown at top of pin
addressYesStreet address shown below name

2.8 Send Contact Card

POST /message/sendContact/{instanceName}

{
  "number": "254712345678",
  "contact": [{
    "fullName": "John Smith",
    "wuid": "254700000000",
    "phoneNumber": "+254 700 000 000",
    "organization": "NextMavens",
    "email": "john@nextmavens.com"
  }]
}

2.9 Send Sticker

POST /message/sendSticker/{instanceName}

{
  "number": "254712345678",
  "sticker": "https://example.com/sticker.png"
}
NOTE: The API auto-converts PNG/JPG to WebP format required by WhatsApp. Best results with square images (512x512px).

2.10 Send Interactive Poll

POST /message/sendPoll/{instanceName}

{
  "number": "254712345678",
  "name": "Preferred contact method?",
  "selectableCount": 1,
  "values": ["Email", "Phone Call", "WhatsApp"]
}
FieldDescription
namePoll question
selectableCount1 = single choice, 2+ = up to N, 0 = unlimited
valuesArray of poll option strings

2.11 Send Interactive Buttons

POST /message/sendButtons/{instanceName}

{
  "number": "254712345678",
  "title": "Choose an option",
  "description": "Please select below:",
  "footer": "NextMavens",
  "buttons": [
    { "type": "reply", "displayText": "Yes", "id": "btn_yes" },
    { "type": "url", "displayText": "Visit Website", "url": "https://example.com" },
    { "type": "call", "displayText": "Call Support", "phoneNumber": "+254700000000" }
  ]
}
Button TypeRequiredBehavior
replyidSends reply back with button ID
urlurlOpens URL in browser
callphoneNumberInitiates phone call

2.12 React to a Message

POST /message/sendReaction/{instanceName}

{
  "key": {
    "remoteJid": "254712345678@s.whatsapp.net",
    "fromMe": false,
    "id": "BAE5F2A1B2C3D4E5"
  },
  "reaction": "\u{1f44d}"
}

Set reaction to empty string "" to remove a reaction.

2.13 Delete a Message

DELETE /chat/deleteMessage/{instanceName}

{
  "remoteJid": "254712345678@s.whatsapp.net",
  "messageId": "BAE5F2A1B2C3D4E5",
  "fromMe": true,
  "onlyMe": false
}
IMPORTANT: Deleting for everyone requires fromMe: true and the message must be within WhatsApp's ~48hr deletion window.

Webhooks Real-Time Events

Webhooks Real-Time Events

Webhooks Real-Time Events

Configure webhooks to receive real-time events (incoming messages, status updates, QR code changes) on your server.

3.1 Set Webhook for an Instance

POST /webhook/set/{instanceName}

Set the webhook URL and choose which events to receive. The payload must be wrapped in a webhook object.

{
  "webhook": {
    "enabled": true,
    "url": "https://yourapp.com/webhook/whatsapp",
    "byEvents": false,
    "base64": false,
    "events": [
      "APPLICATION_STARTUP",
      "QRCODE_UPDATED",
      "CONNECTION_UPDATE",
      "MESSAGES_SET",
      "MESSAGES_UPSERT",
      "MESSAGES_UPDATE",
      "MESSAGES_DELETE",
      "SEND_MESSAGE",
      "CONTACTS_SET",
      "CONTACTS_UPSERT",
      "CONTACTS_UPDATE",
      "PRESENCE_UPDATE",
      "CHATS_SET",
      "CHATS_UPSERT",
      "CHATS_UPDATE",
      "CHATS_DELETE",
      "GROUPS_UPSERT",
      "GROUP_UPDATE",
      "GROUP_PARTICIPANTS_UPDATE",
      "CALL",
      "TYPEBOT_START",
      "TYPEBOT_CHANGE_STATUS"
    ]
  }
}
NOTE: The byEvents flag groups webhooks by event type when true. The base64 flag includes media as base64-encoded strings. Your endpoint must respond within 5 seconds with HTTP 200.

3.2 Webhook Event Reference

EventTriggered When
APPLICATION_STARTUPEvolution API instance starts up
QRCODE_UPDATEDA new QR code is generated (initial or after expiry)
CONNECTION_UPDATEInstance connects, disconnects, or QR is scanned
MESSAGES_SETInitial message list sync (full history)
MESSAGES_UPSERTA new message is received or sent
MESSAGES_UPDATEA message status changes (sent, delivered, read)
MESSAGES_DELETEA message is deleted
SEND_MESSAGEConfirmation that a message was sent
PRESENCE_UPDATEA contact's online/typing status changes
CONTACTS_SETFull contact list sync
CONTACTS_UPSERTA contact is added or updated
CONTACTS_UPDATEContact metadata (e.g., status) changed
CHATS_SETFull chat list sync
CHATS_UPSERTA chat is created or updated
CHATS_UPDATEChat metadata changed (e.g., mute, pin)
CHATS_DELETEA chat is deleted
GROUPS_UPSERTA group is created or updated
GROUP_UPDATEGroup settings changed
GROUP_PARTICIPANTS_UPDATEParticipants added/removed
CALLIncoming or outgoing call event
TYPEBOT_STARTTypebot integration started
TYPEBOT_CHANGE_STATUSTypebot status changed

3.3 Sample Incoming Message Webhook Payload

{
  "event": "messages.upsert",
  "instance": "mycompany-sales",
  "data": {
    "key": {
      "remoteJid": "254712345678@s.whatsapp.net",
      "fromMe": false,
      "id": "3EB0A12345ABCDEF"
    },
    "pushName": "John Doe",
    "message": {
      "conversation": "Hello! I need help with my order."
    },
    "messageTimestamp": 1714000000,
    "messageType": "conversation"
  },
  "destination": "https://yourapp.com/webhook/messages-upsert",
  "date_time": "2024-04-22T10:30:00.000Z",
  "sender": "company-number@s.whatsapp.net",
  "server_url": "https://whatsapp.nextmavens.cloud",
  "webhook": true
}

3.4 Webhook Best Practices

  • Respond Quickly: Acknowledge the webhook within 5 seconds with status 200. Process data asynchronously afterwards.
  • Verify Source: Validate the apikey or instance to ensure the webhook is from your Evolution API.
  • Retry Logic: Evolution API does not retry failed webhooks automatically. Implement your own retry queue for reliability.
  • Idempotency: Use the data.key.id as a unique message ID to avoid duplicate processing.
  • Security: Use HTTPS, validate payload signatures if you add a custom header token.

Instance Settings

Instance Settings

Instance Settings

Configure per-instance behavior for call handling, presence, and message read receipts.

6.1 Get Current Settings

GET /settings/find/{instanceName}

curl -X GET "https://whatsapp.nextmavens.cloud/settings/find/my-instance" \
  -H "apikey: YOUR_INSTANCE_API_KEY"

Response:

{
  "settings": {
    "rejectCall": true,
    "msgCall": "Sorry, I cannot take calls right now.",
    "groupsIgnore": false,
    "alwaysOnline": true,
    "readMessages": false,
    "readStatus": false,
    "syncFullHistory": false
  }
}

6.2 Update Settings

POST /settings/set/{instanceName}

{
  "rejectCall": true,
  "msgCall": "Sorry, I cannot take calls right now.",
  "groupsIgnore": false,
  "alwaysOnline": true,
  "readMessages": false,
  "readStatus": false,
  "syncFullHistory": false
}
TIP: These settings can also be provided during instance creation (/instance/create) to avoid an extra API call.

Contact Chat Management

Contact Chat Management

Contact & Chat Management

4.1 Check if Number Exists on WhatsApp

POST /chat/whatsappNumbers/{instanceName}

{
  "numbers": ["254712345678", "254700112233"]
}
NOTE: Always verify numbers before bulk sending. Sending to non-WhatsApp numbers does not cause issues, but it wastes your rate limit quota and can increase spam signals.

4.2 Fetch Chat History

POST /chat/findMessages/{instanceName}

{
  "where": {
    "key": { "remoteJid": "254712345678@s.whatsapp.net" }
  },
  "limit": 50
}

4.3 Mark Messages as Read

POST /chat/markMessageAsRead/{instanceName}

{
  "readMessages": [
    { "remoteJid": "254712345678@s.whatsapp.net", "fromMe": false, "id": "MESSAGE_ID" }
  ]
}

4.4 Get Profile Picture URL

GET /chat/fetchProfilePictureUrl/{instanceName}?number=254712345678

Group Management

Group Management

Group Management

5.1 Create a Group

POST /group/create/{instanceName}

{
  "subject": "Team Updates",
  "description": "Company-wide announcements",
  "participants": ["254712345678", "254700112233"]
}

5.2 Send Message to Group

POST /message/sendText/{instanceName}

{
  "number": "120363XXXXXXXXXX@g.us",
  "text": "Hello team!"
}

Use the group JID, not a phone number.

5.3 Fetch All Groups

GET /group/fetchAllGroups/{instanceName}?getParticipants=false

Error Codes Troubleshooting

Error Codes Troubleshooting

Error Codes & Troubleshooting

CodeErrorResolution
400Bad RequestCheck your request body missing or invalid field
401UnauthorizedMissing apikey header in your request
403ForbiddenYour API key is invalid or deactivated contact support
404Instance not foundThe instanceName in your URL doesn't exist check spelling
409Instance existsAn instance with this name already exists use fetchInstances to check
429Rate limit exceededSlow down your requests respect the delay parameter
500Internal errorServer error check with NextMavens support; include your instance name

Complete Integration Flow

Complete Integration Flow

Complete Integration Flow

Here is the complete flow from receiving API credentials to sending your first message:

  1. Receive your API key from NextMavens via email/dashboard
  2. Create an instance: POST /instance/create with instanceName
  3. Display the QR code (base64 image) to the end user in your app
  4. User scans QR with their WhatsApp mobile app
  5. Poll GET /instance/connectionState/{instanceName} until status === 'open'
  6. Store the instance token (from create response hash.apikey) in your database
  7. Configure a webhook: POST /webhook/set/{instanceName}
  8. Send messages using the instanceName in the URL path
  9. Handle incoming messages via your webhook endpoint
  10. Monitor connection status if 'close', prompt user to re-scan QR
TIP: For production applications, use WebSockets (Evolution API supports them at /ws) instead of polling for connection status. This is more efficient and gives instant connection updates.

Quick Example: First Message

# 1. Create instance
curl -X POST https://whatsapp.nextmavens.cloud/instance/create \
  -H 'apikey: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "instanceName": "test-instance",
    "integration": "WHATSAPP-BAILEYS",
    "qrcode": true
  }'

# 2. Save the returned hash.apikey (instance token)

# 3. Wait for user to scan QR, then check status
curl -H 'apikey: YOUR_API_KEY' \
  https://whatsapp.nextmavens.cloud/instance/connectionState/test-instance

# 4. Send a message (use instance token as apikey)
curl -X POST https://whatsapp.nextmavens.cloud/message/sendText/test-instance \
  -H 'apikey: INSTANCE_TOKEN_FROM_STEP_2' \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "254712345678",
    "text": "Hello!",
    "delay": 1500
  }'

WhatsApp Best Practices

WhatsApp Best Practices

WhatsApp Best Practices

To avoid WhatsApp account bans, follow these critical rules:

  • Rate limiting: Max 1 message per second per phone number
  • Random delays: Add 15 second jitter between messages
  • Daily caps: Limit to 200300 messages/day per phone number
  • Content variation: Never send identical messages to >10 recipients
  • Instance activity: Keep active with 1 message/week
  • Phone number age: Use numbers >30 days old for automation
  • No URL shorteners: WhatsApp blocks them aggressively
  • Webhooks: Use HTTPS endpoints that respond <5 seconds

See WHATSAPP_BEST_PRACTICES.md in the project repository for complete guidelines.

NextMavens API v1

4.1 API v1 Architecture

The NextMavens API v1 sits in front of the Evolution API and provides:

  • Reseller JWT — Organization-scoped auth tokens (30-day validity) for managing sub-instances programmatically
  • Sub-instance management — Create, list, inspect, and delete dedicated WhatsApp instances per shop/branch
  • Message logging — Every send is automatically logged with status, error details, and timestamps
  • Usage analytics — Track messages sent, success rates, daily trends, and rate limit usage
  • Bulk messaging — Send to multiple recipients with built-in delays and per-recipient status tracking
  • Auto-healing — If an instance's API key expires, the system auto-refreshes and retries transparently
  • Phone formatting — Automatic international number normalization (strip leading 0, add +254 for Kenya)
  • Multi-tenant isolation — Each client can only access their own instances, messages, and stats

4.2 Authentication — Two Methods

Method A: Direct API Key (simple)

Use your client apikey for sending messages, viewing logs, and checking stats:

curl -X POST https://whatsapp.nextmavens.cloud/api/v1/whatsapp/send \
  -H "apikey: YOUR_CLIENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceName": "my-sales", "number": "254712345678", "text": "Hello!"}'

Method B: Reseller JWT (advanced, for multi-tenant platforms)

If you're building a system with multiple sub-accounts (shops, branches), use the reseller flow:

Step 1 — Exchange your API key for a 30-day reseller JWT:

POST https://whatsapp.nextmavens.cloud/api/v1/auth/token
apikey: YOUR_CLIENT_API_KEY

Response: { "token": "eyJ...", "expires_in": 2592000, "client_id": 1 }

Step 2 — Use the JWT (as Bearer token) for sub-instance management:

GET https://whatsapp.nextmavens.cloud/api/v1/whatsapp/reseller/sub-instances
Authorization: Bearer eyJ...

4.3 Reseller Endpoints (JWT Auth)

MethodEndpointDescription
POST/api/v1/whatsapp/reseller/sub-instancesCreate sub-instance
GET/api/v1/whatsapp/reseller/sub-instancesList all sub-instances
GET/api/v1/whatsapp/reseller/sub-instances/{id}Get sub-instance details
DELETE/api/v1/whatsapp/reseller/sub-instances/{id}Delete sub-instance
GET/api/v1/whatsapp/qrcode/{instanceName}Get QR code
GET/api/v1/whatsapp/status/{instanceName}Check connection status

Creating a sub-instance

POST /api/v1/whatsapp/reseller/sub-instances
Authorization: Bearer eyJ...
Content-Type: application/json

{
  "instanceName": "shop-branch-kilimani",
  "integration": "WHATSAPP-BAILEYS"
}

Response: {
  "instance_id": "shop-branch-kilimani",
  "instance_name": "shop-branch-kilimani",
  "api_key": "A1B2C3D4-...",
  "webhook_secret": "hmac-secret-here",
  "integration": "WHATSAPP-BAILEYS",
  "status": "pending"
}

4.4 Direct Send Endpoints (API Key Auth)

MethodEndpointDescription
POST/api/v1/whatsapp/sendSend text message
POST/api/v1/whatsapp/send-mediaSend image, video, document, audio
POST/api/v1/whatsapp/send-bulkSend to multiple recipients
GET/api/v1/whatsapp/messagesView message logs
GET/api/v1/whatsapp/statsUsage analytics

Send Text Message

POST /api/v1/whatsapp/send
apikey: YOUR_CLIENT_API_KEY
Content-Type: application/json

{
  "instanceName": "my-sales",
  "number": "254712345678",
  "text": "Hello from NextMavens!"
}

Send Media

POST /api/v1/whatsapp/send-media
apikey: YOUR_CLIENT_API_KEY
Content-Type: application/json

{
  "instanceName": "my-sales",
  "number": "254712345678",
  "mediaType": "image",
  "media": "https://example.com/photo.jpg",
  "caption": "Check this out!"
}

Bulk Send

POST /api/v1/whatsapp/send-bulk
apikey: YOUR_CLIENT_API_KEY
Content-Type: application/json

{
  "instanceName": "my-sales",
  "recipients": ["254712345678", "254723456789"],
  "message": "Hello everyone!",
  "delay": 2000
}

Message Logs

GET /api/v1/whatsapp/messages?limit=50&offset=0&instance=my-sales&status=sent
apikey: YOUR_CLIENT_API_KEY

Response: {
  "messages": [...],
  "total": 150
}

Usage Stats

GET /api/v1/whatsapp/stats
apikey: YOUR_CLIENT_API_KEY

Response: {
  "messages_today": 42,
  "total_sent": 1234,
  "total_attempts": 1250,
  "success_rate": "98.7%",
  "by_type": [{"message_type": "text", "count": 1100}, ...],
  "daily_last_30": [{"date": "2026-04-05", "count": 42}, ...],
  "rate_limit": 60
}
NOTE: Phone numbers are automatically formatted. You can send 0712345678, +254712345678, or 254712345678 — all will be normalized correctly.

Quick Reference Card

Quick Reference Card

Quick Reference Card

API v1 — NEXTMAVENS API
POST/api/v1/auth/tokenGet reseller JWT (30 days)
POST/api/v1/whatsapp/sendSend text (apikey auth)
POST/api/v1/whatsapp/send-mediaSend media (apikey auth)
POST/api/v1/whatsapp/send-bulkBulk send (apikey auth)
GET/api/v1/whatsapp/messagesMessage logs
GET/api/v1/whatsapp/statsUsage analytics
POST/api/v1/whatsapp/reseller/sub-instancesCreate sub-instance (JWT auth)
GET/api/v1/whatsapp/reseller/sub-instancesList sub-instances (JWT auth)
DELETE/api/v1/whatsapp/reseller/sub-instances/{id}Delete sub-instance (JWT auth)
INSTANCES (Legacy Evolution API)
POST/instance/createCreate new instance + QR
GET/instance/connect/{name}Get QR code (reconnect)
GET/instance/connectionState/{name}Get connection status
GET/instance/fetchInstancesList all instances
DELETE/instance/delete/{name}Delete instance
PUT/instance/restart/{name}Restart instance
PUT/instance/logout/{name}Log out (removes session)
MESSAGES
POST/message/sendText/{name}Send text message
POST/message/sendMedia/{name}Send image, video, document, audio
POST/message/sendWhatsAppAudio/{name}Send voice note (earpiece bubble)
POST/message/sendLocation/{name}Send location pin
POST/message/sendContact/{name}Send contact card
POST/message/sendSticker/{name}Send sticker
POST/message/sendPoll/{name}Send interactive poll
POST/message/sendButtons/{name}Send reply/url/call buttons
POST/message/sendReaction/{name}Add/remove emoji reaction
DELETE/chat/deleteMessage/{name}Delete message for everyone
CHAT & CONTACTS
POST/chat/whatsappNumbers/{name}Verify numbers on WhatsApp
POST/chat/findMessages/{name}Fetch chat history
POST/chat/markMessageAsRead/{name}Mark messages as read
GET/chat/fetchProfilePictureUrl/{name}Get profile picture
GROUPS
POST/group/create/{name}Create a group
GET/group/fetchAllGroups/{name}List all groups
PUT/group/updateParticipant/{name}Add/remove participants
WEBHOOK
POST/webhook/set/{name}Configure webhook
GET/webhook/find/{name}Get webhook config

Base URL: https://whatsapp.nextmavens.cloud | Auth Header: apikey: YOUR_KEY