WhatsApp API Integration Guide for Developers

Overview

This guide explains how to integrate with the WhatsApp API using API keys. The API provides endpoints for sending individual and bulk WhatsApp messages, managing devices, and checking message status.

Table of Contents

  1. Getting Started
  2. Authentication
  3. Device Management
  4. Message Endpoints
  5. Error Handling
  6. Rate Limits & Quotas
  7. Code Examples
  8. Best Practices

Getting Started

Prerequisites

  1. Active Company Account
  2. API Key
  3. Active Subscription (WhatsApp quota)
  4. WhatsApp Device (added and authenticated)

Device Setup Workflow

  1. Add Device → 2. Get QR Code → 3. Scan QR → 4. Verify authenticated → 5. Set Default (optional)

Base URL

Production: https://prosendi.com/api
Development: http://localhost:8000/api

Authentication

API key must be active, not expired, belong to your company, and service type whatsapp.

Example:

curl -X POST https://prosendi.com/api/whatsapp/send \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"recipient": "+22370123456", "message": "Hello World"}'

Device Management

List Devices – GET /api/whatsapp/devices

Returns devices with status: pending, qr_ready, authenticated, disconnected, error.

Create Device – POST /api/whatsapp/devices

Body: { "name": "My WhatsApp Device" }

Get QR Code – GET /api/whatsapp/devices/{id}/qr

Returns qr_code and device_status.

Check Status – GET /api/whatsapp/devices/{id}/status

Returns status and phone_number when available.

Set Default – POST /api/whatsapp/devices/{id}/set-default

Sets chosen device as company default.

Update Device – PUT /api/whatsapp/devices/{id}

Update name, is_active.

Delete Device – DELETE /api/whatsapp/devices/{id}

Removes device and sessions.

Message Endpoints

Send – POST /api/whatsapp/send

Body:

{
    "recipient": "+22370123456",
    "message": "Your message",
    "is_group": false,
    "device_id": 1
}

Returns chat_id, message_id, device_id, and quota info.

Send Bulk – POST /api/whatsapp/send-bulk

Body:

{
    "messages": [{ "recipient": "+22370123456", "message": "Hello" }],
    "device_id": 1
}

Max 100 messages. 100ms delay between messages.

Error Handling

Common codes: invalid_api_key, company_inactive, key_expired, quota_exceeded, device_not_found, device_not_ready, invalid_phone_number, message_too_long, service_type_mismatch.

HTTP: 200, 400, 401, 403, 404, 422, 429, 500, 503.

Rate Limits & Quotas

  • Monthly reset
  • 1 unit per message
  • Hard stop when exhausted
  • Quota returned in send responses

Code Examples

Python

import requests
headers = {"X-API-Key": "your_api_key_here", "Content-Type": "application/json"}
requests.post("https://prosendi.com/api/whatsapp/send", json={"recipient":"+22370123456","message":"Hello"}, headers=headers)

Node.js

const axios = require("axios");
axios.post(
    "https://prosendi.com/api/whatsapp/send",
    { recipient: "+22370123456", message: "Hello" },
    {
        headers: {
            "X-API-Key": "your_api_key_here",
            "Content-Type": "application/json",
        },
    }
);

PHP

<?php
$headers = ['X-API-Key: your_api_key_here','Content-Type: application/json'];
$ch = curl_init('https://prosendi.com/api/whatsapp/send');
curl_setopt_array($ch,[CURLOPT_POST=>true,CURLOPT_HTTPHEADER=>$headers,CURLOPT_POSTFIELDS=>json_encode(['recipient'=>'+22370123456','message'=>'Hello']),CURLOPT_RETURNTRANSFER=>true]);
echo curl_exec($ch);
curl_close($ch);

cURL

API_KEY="your_api_key_here"
curl -X POST "https://prosendi.com/api/whatsapp/send" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" -d '{"recipient":"+22370123456","message":"Hello"}'

Best Practices

  • Keep a device authenticated
  • Set a default device
  • Monitor status and quota
  • Secure API keys; rotate regularly

Support & Changelog

Support: [email protected]

Version 1.0.0 – Initial release, device management, quota, error handling.