WhatsApp Notifications

Send WhatsApp messages to customers for notifications, customer service, and marketing campaigns via the Ping API.

The WhatsApp model

The WhatsApp notification model contains all the information about WhatsApp messages sent through the Ping platform.

Properties

Name
public_id
Type
string
Description
Unique identifier for the WhatsApp notification.
Name
to_phone
Type
string
Description
Recipient phone number in E.164 international format (e.g., +263771234567).
Name
message
Type
string
Description
WhatsApp message content (text messages only within 24-hour customer service window).
Name
template_name
Type
string
Description
WhatsApp template name (required for messages outside the 24-hour window).
Name
template_data
Type
object
Description
Variables for template personalization.
Name
status
Type
string
Description
Delivery status: sent, delivered, read, failed.
Name
wa_message_id
Type
string
Description
WhatsApp Business API message ID for tracking.
Name
created_at
Type
timestamp
Description
Timestamp of when the message was created.

POST/v1/notification/api/whatsapp/send

Send WhatsApp message

Send a WhatsApp message to one or multiple recipients. Free-form text messages can only be sent within the 24-hour customer service window. For messages outside this window, use an approved template.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key with whatsapp permission.
Name
Content-Type
Type
string
Description
Must be application/json.

Required attributes

Name
to_phone
Type
string | array
Description
Recipient phone number or array of phone numbers in E.164 format (e.g., "+263771234567").
Name
message
Type
string
Description
WhatsApp message content (for free-form text messages).

Optional attributes

Name
media_url
Type
string
Description
URL to media file (image, video, document, audio) to send with the message.
Name
interactive
Type
object
Description
Send an interactive message (buttons or list) instead of plain text. See Send interactive message for details.
Name
recipient_group_id
Type
string
Description
Send to all members of a recipient group instead of individual phone numbers.

Request

POST

/v1/notification/api/whatsapp/send

curl -X POST https://api.ping.co.zw/v1/notification/api/whatsapp/send \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to_phone": "+263771234567",
    "message": "Your order #12345 has been shipped!"
  }'

Response

{
  "result": "success",
  "message": "WhatsApp message sent successfully",
  "wa_message_id": "wamid.HBgLMjYzNzcxMjM0NTY3FQIAERgSQUIyM0Y0NTY3ODkwQUJDRAA"
}

POST/v1/notification/api/whatsapp/send

Send interactive message

Send an interactive WhatsApp message with reply buttons (max 3) or a list menu (max 10 items). Interactive messages give recipients tappable options instead of requiring them to type a response.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key with whatsapp permission.
Name
Content-Type
Type
string
Description
Must be application/json.

Required attributes

Name
to_phone
Type
string
Description
Recipient phone number in E.164 format.
Name
interactive
Type
object
Description
Interactive message configuration. Must include type, body, and type-specific fields.

Interactive object

Name
type
Type
string
Description
Either buttons (reply buttons) or list (list menu).
Name
body
Type
string
Description
Message body text (max 1024 characters).
Name
header
Type
string
Description
Optional header text (max 60 characters).
Name
footer
Type
string
Description
Optional footer text (max 60 characters).
Name
buttons
Type
array
Description
For buttons type only. Array of 1-3 button objects, each with id (string, max 256 chars) and title (string, max 20 chars).
Name
button_text
Type
string
Description
For list type only. Text shown on the list menu button (max 20 chars).
Name
sections
Type
array
Description
For list type only. Array of section objects, each with title and rows (array of row objects with id, title, and optional description). Max 10 rows total across all sections.

Request

POST

/v1/notification/api/whatsapp/send

curl -X POST https://api.ping.co.zw/v1/notification/api/whatsapp/send \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to_phone": "+263771234567",
    "interactive": {
      "type": "buttons",
      "body": "Your order #12345 is ready for pickup. Would you like to confirm?",
      "header": "Order Ready",
      "footer": "Reply within 24 hours",
      "buttons": [
        {"id": "confirm_pickup", "title": "Confirm"},
        {"id": "reschedule", "title": "Reschedule"},
        {"id": "cancel_order", "title": "Cancel"}
      ]
    }
  }'

Response

{
  "result": "success",
  "message": "WhatsApp message sent successfully",
  "wa_message_id": "wamid.HBgLMjYzNzcxMjM0NTY3FQIAERgSQUIyM0Y0NTY3ODkwQUJDRAA"
}

POST/v1/notification/api/whatsapp/send

Send template message

Send a WhatsApp message using an approved template. Templates are required for messaging outside the 24-hour customer service window and support personalization through variables.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key with whatsapp and templates permissions.
Name
Content-Type
Type
string
Description
Must be application/json.

Required attributes

Name
to_phone
Type
string
Description
Recipient phone number in E.164 format.
Name
template_name
Type
string
Description
Name of the approved WhatsApp template.
Name
template_data
Type
object
Description
Template personalization data with language and component parameters.

Request

POST

/v1/notification/api/whatsapp/send

curl -X POST https://api.ping.co.zw/v1/notification/api/whatsapp/send \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to_phone": "+263771234567",
    "template_name": "order_update",
    "template_data": {
      "language": "en",
      "components": [
        {
          "type": "body",
          "parameters": [
            {"type": "text", "text": "ORD-12345"},
            {"type": "text", "text": "shipped"}
          ]
        }
      ]
    }
  }'

Response

{
  "result": "success",
  "message": "Template message sent successfully",
  "wa_message_id": "wamid.HBgLMjYzNzcxMjM0NTY3FQIAERgSQUIyM0Y0NTY3ODkwQUJDRAA"
}

GET/v1/notification/api/history/whatsapp

List WhatsApp history

Retrieve a paginated list of WhatsApp messages sent through your account.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key.

Optional parameters

Name
skip
Type
integer
Description
Number of records to skip (default: 0).
Name
limit
Type
integer
Description
Maximum number of records to return (default: 50, max: 100).

Request

GET

/v1/notification/api/history/whatsapp

curl -G https://api.ping.co.zw/v1/notification/api/history/whatsapp \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -d limit=10 \
  -d skip=0

Response

{
  "result": "success",
  "notifications": [
    {
      "public_id": "wa_abc123def456",
      "recipient": "+263771234567",
      "message": "Your order #12345 has been shipped!",
      "template_name": null,
      "status": "delivered",
      "wa_message_id": "wamid.HBgLMjYzNzcxMjM0NTY3FQIAERgSQUIyM0Y0NTY3ODkwQUJDRAA",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}

Customer Service Window

WhatsApp enforces a 24-hour Customer Service Window (CSW) after a customer messages you. Within this window:

✅ Send free-form text messages
✅ Send media (images, videos, documents)
✅ No template required
✅ Free messaging (service category)

After the 24-hour window expires:

❌ Cannot send free-form text
✅ Must use approved templates only
💰 Charged per template category (utility, marketing, authentication)

Best Practice: Monitor conversation status and use templates for re-engagement after the CSW expires.