API Version 1.1

WhatsApp Integration API

Send messages, manage contacts, and monitor instances programmatically with our powerful REST API

Get Started View Examples Postman Collection
99.9%
Uptime
5000+
Requests/Hour
24/7
Support

Overview

This guide explains how to integrate your application with our WhatsApp messaging platform using API keys. With our Integration API, you can send messages, manage contacts, and monitor instances programmatically.

Fast & Reliable

Queue-based processing with automatic retries ensures message delivery

Secure

API key authentication with granular permissions and rate limiting

Scalable

Handle thousands of messages per hour with our robust infrastructure

Getting Started

Prerequisites

  • An active account on the platform
  • At least one connected WhatsApp instance
  • Basic understanding of REST APIs

Base URLs

Dashboard API
https://app.wessaal.com/api/v1/dashboard
Integration API
https://app.wessaal.com/integration/v1

Authentication

Using API Keys

All Integration API requests require an API key for authentication. Include your API key in the request header:

HTTP Header 
X-API-Key: sk_live_your_api_key_here

Authentication Flow

1

Generate API Key

Create an API key via Dashboard API (requires user authentication)

2

Store API Key

Save the key securely - it's shown only once!

3

Use API Key

Include the key in all Integration API requests

Send Message

Send Single Message

Send a WhatsApp message to a single recipient.

POST
/integration/v1/messages/send

Required Permission

send_message

Parameters

Parameter Type Required Description
instance string Required Instance ID or name
recipient string Required Phone number in E.164 format
message_type string Optional Type of message (default: "text")
content string Required Message text content
Note: The message is queued for processing. Use the status endpoint to check delivery status.

Send Bulk Messages

Send Multiple Messages

Send multiple messages in one request (max 100).

POST
/integration/v1/messages/send-bulk

Required Permission

send_message

Request Body

JSON 
{
  "instance": "my-instance",
  "messages": [
    {
      "recipient": "+966501234567",
      "content": "Hello Customer 1!"
    },
    {
      "recipient": "+966509876543",
      "content": "Hello Customer 2!"
    }
  ]
}

Response

JSON 
{
  "success": true,
  "message": "Bulk messages queued for sending",
  "data": {
    "total": 2,
    "queued_count": 2,
    "message_ids": [12345, 12346]
  }
}
Note: All messages are queued for processing. Use the status endpoint to check individual delivery status.

Send Poll Message

Send Interactive Poll

Send interactive poll messages to engage users with questions.

POST
/integration/v1/messages/send-poll

Required Permission

send_message

Parameters

Parameter Type Required Description
instance string Required Instance ID or name
recipient string Optional Phone number in E.164 format
contact_id integer Optional Contact ID from your contacts
name string Required Poll question (max 255 characters)
values array Required Array of poll options (minimum 2)
selectable_count integer Optional Number of selectable options (default: 1)

Request Example

JSON 
{
  "instance": "my-instance",
  "recipient": "+966501234567",
  "name": "What's your favorite color?",
  "values": ["Red", "Blue", "Green", "Yellow"],
  "selectable_count": 1
}

Response

JSON 
{
  "success": true,
  "message": "Poll message queued successfully",
  "data": {
    "message_id": 12347,
    "status": "pending",
    "recipient": "+966501234567",
    "poll": {
      "question": "What's your favorite color?",
      "options": ["Red", "Blue", "Green", "Yellow"],
      "selectable_count": 1
    }
  }
}

Send List Message

Send Interactive List Menu

Send interactive list menus with multiple options organized in sections.

POST
/integration/v1/messages/send-list

Required Permission

send_message

Parameters

Parameter Type Required Description
instance string Required Instance ID or name
recipient string Optional Phone number in E.164 format
contact_id integer Optional Contact ID from your contacts
title string Required List title (max 255 characters)
description string Required List description
button_text string Required Button text (max 20 characters)
footer_text string Optional Footer text
sections array Required Array of sections with rows

Request Example

JSON 
{
  "instance": "my-instance",
  "recipient": "+966501234567",
  "title": "Choose a Service",
  "description": "Select from our services",
  "button_text": "View Options",
  "footer_text": "Thank you!",
  "sections": [
    {
      "title": "Customer Services",
      "rows": [
        {
          "title": "Technical Support",
          "description": "Get help with issues",
          "rowId": "tech_support"
        },
        {
          "title": "Sales Inquiry",
          "description": "Talk to sales",
          "rowId": "sales"
        }
      ]
    }
  ]
}

Response

JSON 
{
  "success": true,
  "message": "List message queued successfully",
  "data": {
    "message_id": 12348,
    "status": "pending",
    "recipient": "+966501234567"
  }
}

Send Reaction

React to Message

React to a specific message with an emoji.

POST
/integration/v1/messages/send-reaction

Required Permission

send_message

Parameters

Parameter Type Required Description
instance string Required Instance ID or name
message_key object Required Message key object with remoteJid, fromMe, and id
reaction string Required Emoji to react with (max 10 characters)

Request Example

JSON 
{
  "instance": "my-instance",
  "message_key": {
    "remoteJid": "966501234567@s.whatsapp.net",
    "fromMe": false,
    "id": "3EB0C6A4F0B5E8D9C2A1"
  },
  "reaction": "👍"
}

Response

JSON 
{
  "success": true,
  "message": "Reaction queued successfully",
  "data": {
    "message_id": 12349,
    "status": "pending",
    "reaction": "👍"
  }
}
Note: To get the message key, you need to receive webhook notifications for incoming messages or store message keys when sending messages.

Get Message Status

Check Delivery Status

Check the delivery status of a sent message.

GET
/integration/v1/messages/{messageId}/status

Required Permission

read_messages

Response

JSON 
{
  "success": true,
  "data": {
    "message_id": 12345,
    "status": "sent",
    "recipient": "+966501234567",
    "sent_at": "2025-12-23T16:05:00.000000Z",
    "delivered_at": "2025-12-23T16:05:15.000000Z"
  }
}

Possible Status Values

pending Queued for sending
processing Being sent
sent Successfully sent
failed Failed to send

List Messages

Get Paginated Messages

Get a paginated list of sent messages.

GET
/integration/v1/messages

Required Permission

read_messages

Response

JSON 
{
  "success": true,
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 12345,
        "recipient_number": "+966501234567",
        "content": "Hello from our API!",
        "status": "sent",
        "created_at": "2025-12-23T16:05:00.000000Z"
      }
    ],
    "per_page": 50,
    "total": 150
  }
}

Instance Management

List Instances

Get all your WhatsApp instances.

GET
/integration/v1/instances

Required Permission

manage_instances

Response

JSON 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "instance_name": "my-instance",
      "connection_status": "open",
      "phone_number": "+966501234567",
      "created_at": "2025-12-01T10:00:00.000000Z"
    }
  ]
}

Get Instance Details

Get detailed information about a specific instance.

GET
/integration/v1/instances/{instanceId}

Required Permission

manage_instances

Get Instance Status

Check the connection status of an instance.

GET
/integration/v1/instances/{instanceId}/status

Required Permission

manage_instances

Contact Management

List Contacts

Get all your contacts.

GET
/integration/v1/contacts

Required Permission

manage_contacts

Create Contact

Add a new contact to your list.

POST
/integration/v1/contacts

Required Permission

manage_contacts

Request Body

JSON 
{
  "phone_number": "+966501234567",
  "name": "John Doe",
  "group_id": 5
}

Update Contact

Update an existing contact's information.

PUT
/integration/v1/contacts/{contactId}

Required Permission

manage_contacts

Delete Contact

Remove a contact from your list.

DELETE
/integration/v1/contacts/{contactId}

Required Permission

manage_contacts

Code Examples

Ready-to-use code examples in multiple programming languages.

PHP / Laravel 
use Illuminate\Support\Facades\Http;

$apiKey = 'sk_live_your_api_key_here';

$response = Http::withHeaders([
    'X-API-Key' => $apiKey,
    'Content-Type' => 'application/json',
])->post('https://app.wessaal.com/integration/v1/messages/send', [
    'instance' => 'my-instance',
    'recipient' => '+966501234567',
    'content' => 'Hello from PHP!',
]);

if ($response->successful()) {
    $data = $response->json();
    echo "Message sent! ID: " . $data['data']['message_id'];
} else {
    echo "Error: " . $response->json()['message'];
}
JavaScript / Node.js 
const axios = require('axios');

const apiKey = 'sk_live_your_api_key_here';

async function sendMessage() {
  try {
    const response = await axios.post(
      'https://app.wessaal.com/integration/v1/messages/send',
      {
        instance: 'my-instance',
        recipient: '+966501234567',
        content: 'Hello from Node.js!'
      },
      {
        headers: {
          'X-API-Key': apiKey,
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log('Message sent!', response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

sendMessage();
Python 
import requests

api_key = 'sk_live_your_api_key_here'

headers = {
    'X-API-Key': api_key,
    'Content-Type': 'application/json'
}

payload = {
    'instance': 'my-instance',
    'recipient': '+966501234567',
    'content': 'Hello from Python!'
}

response = requests.post(
    'https://app.wessaal.com/integration/v1/messages/send',
    json=payload,
    headers=headers
)

if response.status_code == 201:
    data = response.json()
    print(f"Message sent! ID: {data['data']['message_id']}")
else:
    print(f"Error: {response.json()['message']}")
cURL 
curl -X POST https://app.wessaal.com/integration/v1/messages/send \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "instance": "my-instance",
    "recipient": "+966501234567",
    "content": "Hello from cURL!"
  }'

Rate Limiting

Each API key has a rate limit (default: 1000 requests/hour).

Rate Limit Headers

Header Description
X-RateLimit-Limit Maximum requests per hour
X-RateLimit-Remaining Requests remaining
X-RateLimit-Reset Timestamp when limit resets

Error Handling

HTTP Status Codes

200 Success
201 Created
202 Accepted (Queued)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
422 Validation Error
429 Rate Limit Exceeded
500 Server Error

Best Practices

Security

  • Never expose API keys in client-side code
  • Store keys securely using environment variables
  • Use HTTPS for all API requests
  • Rotate keys regularly

Performance

  • Use bulk sending for multiple messages
  • Implement retry logic with exponential backoff
  • Cache instance information
  • Monitor rate limits

Error Handling

  • Always check response status
  • Implement proper error logging
  • Handle rate limiting gracefully
  • Validate data before sending

Support

Need help? We're here for you 24/7.

Documentation

Check this comprehensive guide for answers

Email Support

Contact our team for technical assistance

Community

Join our developer community forum