WHATSAPP API

WhatsApp API Reference

Send WhatsApp text messages, media, and templates via Evolution API integration. WhatsApp messages are delivered through configured Evolution API instances.

How it works

WhatsApp messages are sent through Evolution API instances running in Docker. Your application authenticates with SMS Gateway, which then routes messages through the configured Evolution API provider. Delivery status is tracked and available via webhooks or the status endpoint.

Endpoints

POST

/admin/api/whatsapp/send-text

Send text message

POST

/admin/api/whatsapp/send-media

Send media (single or multi)

POST

/admin/api/whatsapp/upload-media

Upload a file for media messages

POST

/admin/api/whatsapp/send-template

Send a pre-approved template

POST

/admin/api/whatsapp/bulk

Bulk send (text or media)

GET

/admin/api/whatsapp/inspect/{`{message_id}`}

Inspect message details

Send Text Message

Send a plain text WhatsApp message to a recipient.

POST /admin/api/whatsapp/send-text

Parameter	Type	Required	Description
to	string	Required	Recipient phone number in E.164 format
message	string	Required	Text message content

Send WhatsApp text

curl -X POST "https://api.yourdomain.com/admin/api/whatsapp/send-text" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+265888123456",
    "message": "Hello from SMS Gateway WhatsApp API!"
  }'

200 OK

{
  "success": true,
  "message_id": "wa_msg_abc123",
  "status": "sent",
  "provider": "evolution",
  "instance": "default"
}

Send Media Message

Send an image, document, video, or audio via WhatsApp. Supports both single media and multi-media payloads.

POST /admin/api/whatsapp/send-media

media_type values

imagevideoaudiodocument

Base64 note: When media_url starts with /, the backend reads the local file at that path and base64-encodes it before sending. The fileName is automatically derived from the file path.

Single Media

Parameter	Type	Required	Description
to	string	Required	Recipient phone number in E.164 format
media_url	string	Required	URL of the media file, or local path starting with /
media_type	string	Required	One of: "image", "video", "audio", "document"
caption	string	Optional	Caption for the media
file_name	string	Optional	Filename for documents (auto-derived for local files)

Send a single image

curl -X POST "https://api.yourdomain.com/admin/api/whatsapp/send-media" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+265888123456",
    "media_url": "https://example.com/image.jpg",
    "media_type": "image",
    "caption": "Check out this image!"
  }'

Multi-Media

Parameter	Type	Required	Description
to	string	Required	Recipient phone number in E.164 format
media_items	array	Required	Array of media objects, each with media_url, media_type, caption, file_name
caption	string	Optional	Overall caption for the message

Send multiple media files

curl -X POST "https://api.yourdomain.com/admin/api/whatsapp/send-media" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+265888123456",
    "media_items": [
      {
        "media_url": "https://example.com/photo1.jpg",
        "media_type": "image",
        "caption": "First photo"
      },
      {
        "media_url": "https://example.com/video.mp4",
        "media_type": "video",
        "caption": "A video"
      }
    ],
    "caption": "Here are some files for you"
  }'

Upload Media

Upload a file to the server for use in media messages. Returns a local path that can be used as media_url in the send-media endpoint.

POST /admin/api/whatsapp/upload-media

Parameter	Type	Required	Description
file	file	Required	The file to upload (multipart/form-data)

Upload a file

curl -X POST "https://api.yourdomain.com/admin/api/whatsapp/upload-media" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@/path/to/image.jpg"

200 OK

{
  "success": true,
  "path": "/uploads/whatsapp/image_abc123.jpg",
  "file_name": "image.jpg"
}

Send Template Message

Send a pre-approved WhatsApp Business template. Templates are required for initiating conversations with users who haven't messaged you first.

POST /admin/api/whatsapp/send-template

Parameter	Type	Required	Description
to	string	Required	Recipient phone number
template_name	string	Required	Name of the approved template
language	string	Optional	Template language code (default: "en")
variables	array	Optional	Template variable values
namespace	string	Optional	Template namespace

Send a template

curl -X POST "https://api.yourdomain.com/admin/api/whatsapp/send-template" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+265888123456",
    "template_name": "order_confirmation",
    "language": "en",
    "variables": ["John", "ORD-12345"]
  }'

Bulk Send

Send text or media messages to multiple recipients in a single request. Optionally schedule delivery for a future time.

POST /admin/api/whatsapp/bulk

Parameter	Type	Required	Description
recipients	array	Required	Array of recipient phone numbers in E.164 format
message	string	Required	Text message content
media_url	string	Optional	URL or local path of media to attach
media_type	string	Optional	One of: "image", "video", "audio", "document"
caption	string	Optional	Caption for the media
file_name	string	Optional	Filename for documents
scheduled_at	string	Optional	ISO 8601 timestamp to schedule delivery

Bulk send text

curl -X POST "https://api.yourdomain.com/admin/api/whatsapp/bulk" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["+265888123456", "+265888654321"],
    "message": "Hello everyone!"
  }'

Bulk send with media

curl -X POST "https://api.yourdomain.com/admin/api/whatsapp/bulk" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["+265888123456", "+265888654321"],
    "message": "Here is the brochure",
    "media_url": "https://example.com/brochure.pdf",
    "media_type": "document",
    "file_name": "brochure.pdf"
  }'

Inspect Message

Retrieve detailed information about a specific WhatsApp message, including delivery status and metadata.

GET /admin/api/whatsapp/inspect/{message_id}

200 OK

{
  "success": true,
  "data": {
    "message_id": "wa_msg_abc123",
    "status": "delivered",
    "recipient": "+265888123456",
    "sent_at": "2026-01-13T10:30:00Z",
    "delivered_at": "2026-01-13T10:30:12Z",
    "provider": "evolution",
    "instance": "default"
  }
}

Status Values

Status	Description
`pending`	Queued for delivery
`sent`	Sent to WhatsApp servers
`delivered`	Delivered to recipient's device
`read`	Read by recipient
`failed`	Delivery failed