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 (incl. sending media)
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.

Sending media (image, document, audio, video)

You can send a media file (image, PDF, audio, video) by providing a publicly accessible URL in the media_url field. The message is then used as the caption (optional for images/documents).

Request body:

Field	Type	Required	Description
recipient	string	Yes	Phone number (e.g. +22370123456) or group ID
message	string	No*	Text message or caption for the media. Required if media_url is omitted
media_url	string	No	Public URL of the file (image, document, audio, video)
is_group	boolean	No	true if recipient is a group
device_id	integer	No	Device to use; default device if omitted

Example – send image with caption:

{
    "recipient": "+22370123456",
    "message": "Check out this document",
    "media_url": "https://example.com/files/invoice.pdf"
}

Example – image only (optional caption):

{
    "recipient": "+22370123456",
    "message": "Here is the photo",
    "media_url": "https://example.com/images/photo.jpg"
}

Supported formats:

• Images: JPG, PNG, GIF, WebP
• Documents: PDF, DOC, XLS, etc.
• Audio: MP3, OGG, etc.
• Video: MP4, etc.

The file must be publicly downloadable (HTTP/HTTPS). The server fetches the file from the URL and sends it via WhatsApp. For large files, ensure the URL is fast and stable.

cURL example (media):

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": "Your caption (optional)",
    "media_url": "https://example.com/image.jpg"
  }'

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

Body:

{
    "messages": [
        { "recipient": "+22370123456", "message": "Hello" },
        { "recipient": "+22370987654", "message": "Caption", "media_url": "https://example.com/photo.jpg" }
    ],
    "device_id": 1
}

• Max 100 messages. 100ms delay between messages.
• Each item in messages can optionally include media_url (same as single send).

---

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.