curl --request POST \
--url https://api.wppfy.com/send/status \
--header 'Content-Type: application/json' \
--header 'token: <api-key>' \
--data '
{
"type": "text",
"text": "Novidades chegando!"
}
'{
"Id": "ABCD1234",
"content": {},
"messageTimestamp": 1672531200000,
"status": "Pending",
"debug": {
"status_privacy_type": "contacts",
"audience_recipient_count": 245,
"total_contacts_in_store": 300,
"contacts_with_full_name": 245,
"contacts_with_push_name_only": 32,
"contacts_with_business_name_only": 23,
"used_default_privacy_fallback": false,
"privacy_lookup_error": "privacy unavailable",
"explicit_recipients": true,
"requested_recipient_count": 25,
"resolved_recipient_count": 20,
"discarded_recipient_count": 5,
"discarded_recipients": [
{
"input": "144637553594388@lid",
"reason": "lid_unresolved"
}
],
"max_recipients": 100,
"selected_recipient_count": 100,
"partial_send": true
}
}{
"error": "Invalid font",
"debug": {}
}{
"error": "failed to determine status audience: privacy unavailable"
}Send Message
Send status (stories)
Sends a WhatsApp status with support for text, image, video, and audio.
This endpoint has 4 usage modes:
- normal send: omit
recipients,max_recipients, andgroup - explicit send: provide
recipientsto send only to specific numbers; the API keeps the valid ones and discards the invalid ones with a reason indebug - partial send: provide
max_recipientsto limit the audience or apply a safety cap onrecipients - group status: provide
groupwith the group JID (@g.us)
Important note about recipients
When recipients is provided, the API:
- accepts numbers in WhatsApp format,
@s.whatsapp.netJIDs, and@lidJIDs - when it receives
@lid, tries to resolve that identifier to the PN (@s.whatsapp.net) using the links known by the instance - if the
@lidcannot be resolved to a PN, that item is discarded with reasonlid_unresolved - validates whether the recipient exists on WhatsApp using the same verification flow as the normal send, batched to avoid one remote call per recipient
- cross-references the verified recipients with the audience allowed by the status privacy settings, accepting PN/LID equivalence when that link is known
- discarded recipients appear in
debug.discarded_recipients, with reasons such asinvalid_format,lid_unresolved,not_on_whatsapp,outside_status_audience, andduplicate - the request only returns
400when no valid recipient remains to send to
Important note about max_recipients
The max_recipients field was added as an operational mitigation.
We have observed cases where WhatsApp immediately blocks status sending when the audience is very large
(for example, address books with thousands of contacts, such as ~3,000).
The exact cause is not yet fully clear, so the recommendation is to start with smaller limits and increase them gradually.
Group status
With group, the status is published to the group and appears to members in the Status tab, instead of the account status. The account must be a member of the group. This applies to text, image, and video: audio (audio, ptt, and myaudio) does not work in group status and returns 400.
- cannot be combined with
recipientsormax_recipients(returns400) - the response includes
Id,content,messageTimestamp, andstatus, withoutdebug
Supported types
text: text with background color and fontimage: image with optional captionvideo: video with optional captionaudio: regular audiomyaudio: audio sent as voiceptt: audio sent as voice
Background colors
Provide a value from 1 to 19. The API converts this index to the color used by WhatsApp.
1: soft greenish yellow2: pale yellow3: vibrant orange yellow4: vibrant green5: moss green6: light green7: pool blue8: deep blue9: light grayish blue10: light lilac11: warm lilac12: bluish purple13: deep magenta14: soft pink15: pinkish salmon16: light brown17: light bluish gray18: medium gray19: default deep gray
Quick example:
7: pool blue13: deep magenta19: deep gray (default)
Valid fonts for type=text
Currently accepted values: 0, 1, 2, 6, 7, 8, 9, 10.
Limits
text: maximum of 656 charactersmax_recipients: cannot be negativerecipients: accepts numbers,@s.whatsapp.netJIDs, and@lidJIDs@lidis only included in the send when it can be resolved locally to a valid PN; otherwise, it is discarded- for media types,
fileis required group: group JID (@g.us)
Explicit send example:
{
"type": "text",
"text": "Novidades chegando!",
"recipients": [
"5511999999999",
"5511888888888@s.whatsapp.net"
]
}
Partial send example:
{
"type": "text",
"text": "Novidades chegando!",
"background_color": 7,
"font": 1,
"max_recipients": 100
}
Group status example:
{
"type": "image",
"file": "https://exemplo.com/status.jpg",
"text": "Aviso para o grupo",
"group": "120363123456789012@g.us"
}
POST
/
send
/
status
curl --request POST \
--url https://api.wppfy.com/send/status \
--header 'Content-Type: application/json' \
--header 'token: <api-key>' \
--data '
{
"type": "text",
"text": "Novidades chegando!"
}
'{
"Id": "ABCD1234",
"content": {},
"messageTimestamp": 1672531200000,
"status": "Pending",
"debug": {
"status_privacy_type": "contacts",
"audience_recipient_count": 245,
"total_contacts_in_store": 300,
"contacts_with_full_name": 245,
"contacts_with_push_name_only": 32,
"contacts_with_business_name_only": 23,
"used_default_privacy_fallback": false,
"privacy_lookup_error": "privacy unavailable",
"explicit_recipients": true,
"requested_recipient_count": 25,
"resolved_recipient_count": 20,
"discarded_recipient_count": 5,
"discarded_recipients": [
{
"input": "144637553594388@lid",
"reason": "lid_unresolved"
}
],
"max_recipients": 100,
"selected_recipient_count": 100,
"partial_send": true
}
}{
"error": "Invalid font",
"debug": {}
}{
"error": "failed to determine status audience: privacy unavailable"
}Authorizations
Body
application/json
Status type.
Available options:
text, image, video, audio, myaudio, ptt Example:
"text"
Main text or caption.
Example:
"News coming soon!"
Background color index for text status.
Required range:
1 <= x <= 19Example:
7
Font accepted for type=text.
Available options:
0, 1, 2, 6, 7, 8, 9, 10 Example:
1
URL or base64 of the media file.
Example:
"https://example.com/video.mp4"
Field accepted in the payload; the API generates the thumbnail automatically when needed.
Example:
"https://example.com/thumb.jpg"
File MIME type, when needed.
Example:
"video/mp4"
Explicit list of recipients. Accepts numbers in WhatsApp format, @s.whatsapp.net JIDs and @lid JIDs. The API validates item by item, discards invalid ones with a reason in debug and sends to the remaining valid subset. @lid entries depend on a known resolution to PN.
Example:
[
"5511999999999",
"5511888888888@s.whatsapp.net"
]
Limits sending to a deterministic subset of the audience. When recipients is provided, it works as a safety cap on the already validated explicit list.
Required range:
x >= 0Example:
100
Group JID (@g.us). Publishes the status to the group, for its members, instead of the account status. Cannot be combined with recipients or max_recipients. Only text, image and video: audio returns 400.
Example:
"120363123456789012@g.us"
Response
Status sent successfully
Message ID when an actual send occurs.
Example:
"ABCD1234"
Processed message content when there is an actual send.
Timestamp in milliseconds when there is an actual send.
Example:
1672531200000
Send status when there is an actual send.
Example:
"Pending"
Aggregated metrics of the audience and the applied selection.
Show child attributes
Show child attributes