🚀 NextMavens WhatsApp API

🔐 Authentication

All API requests require your API key in the request header:

apikey: YOUR_NEXTMAVENS_API_KEY

📱 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"
}

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}

1.4 Fetch All Instances

GET /instance/fetchInstances

1.5 Delete an Instance

DELETE /instance/delete/{instanceName}

💬 Sending Messages

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
}

2.5 Send Buttons (Interactive)

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": "reply", "displayText": "No", "id": "btn_no" }
  ]
}

🔔 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}

{
  "enabled": true,
  "url": "https://yourapp.com/webhook/whatsapp",
  "webhookByEvents": false,
  "webhookBase64": false,
  "events": [
    "MESSAGES_UPSERT",
    "MESSAGES_UPDATE",
    "CONNECTION_UPDATE",
    "QRCODE_UPDATED",
    "SEND_MESSAGE"
  ]
}

3.2 Webhook Event Reference

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"
  }
}

👥 Contact & Chat Management

4.1 Check if Number Exists on WhatsApp

POST /chat/whatsappNumbers/{instanceName}

{
  "numbers": ["254712345678", "254700112233"]
}

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

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

📦 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

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

To avoid WhatsApp account bans, follow these critical rules:

• Rate limiting: Max 1 message per second per phone number
• Random delays: Add 1–5 second jitter between messages
• Daily caps: Limit to 200–300 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.

📋 Quick Reference Card

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

🔧 Evolution Manager Web UI

Evolution API ships with a built-in web interface for admin management.

• 🔗 Access: https://whatsapp.nextmavens.cloud/manager
• 🔐 Login: Use your master AUTHENTICATION_API_KEY

The manager lets you visually:

• Create and manage WhatsApp instances
• View and download QR codes
• Check connection status
• Browse sent/received messages
• Monitor system health