> ## Documentation Index > Fetch the complete documentation index at: https://docs.wppfy.com/llms.txt > Use this file to discover all available pages before exploring further. # 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`, and `group` - explicit send: provide `recipients` to send only to specific numbers; the API keeps the valid ones and discards the invalid ones with a reason in `debug` - partial send: provide `max_recipients` to limit the audience or apply a safety cap on `recipients` - group status: provide `group` with the group JID (`@g.us`) ## Important note about `recipients` When `recipients` is provided, the API: - accepts numbers in WhatsApp format, `@s.whatsapp.net` JIDs, and `@lid` JIDs - when it receives `@lid`, tries to resolve that identifier to the PN (`@s.whatsapp.net`) using the links known by the instance - if the `@lid` cannot be resolved to a PN, that item is discarded with reason `lid_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 as `invalid_format`, `lid_unresolved`, `not_on_whatsapp`, `outside_status_audience`, and `duplicate` - the request only returns `400` when 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 `recipients` or `max_recipients` (returns `400`) - the response includes `Id`, `content`, `messageTimestamp`, and `status`, without `debug` ## Supported types - `text`: text with background color and font - `image`: image with optional caption - `video`: video with optional caption - `audio`: regular audio - `myaudio`: audio sent as voice - `ptt`: 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 yellow - `2`: pale yellow - `3`: vibrant orange yellow - `4`: vibrant green - `5`: moss green - `6`: light green - `7`: pool blue - `8`: deep blue - `9`: light grayish blue - `10`: light lilac - `11`: warm lilac - `12`: bluish purple - `13`: deep magenta - `14`: soft pink - `15`: pinkish salmon - `16`: light brown - `17`: light bluish gray - `18`: medium gray - `19`: default deep gray Quick example: - `7`: pool blue - `13`: deep magenta - `19`: deep gray (default) ## Valid fonts for `type=text` Currently accepted values: `0`, `1`, `2`, `6`, `7`, `8`, `9`, `10`. ## Limits - `text`: maximum of 656 characters - `max_recipients`: cannot be negative - `recipients`: accepts numbers, `@s.whatsapp.net` JIDs, and `@lid` JIDs - `@lid` is only included in the send when it can be resolved locally to a valid PN; otherwise, it is discarded - for media types, `file` is required - `group`: group JID (`@g.us`) Explicit send example: ```json { "type": "text", "text": "Novidades chegando!", "recipients": [ "5511999999999", "5511888888888@s.whatsapp.net" ] } ``` Partial send example: ```json { "type": "text", "text": "Novidades chegando!", "background_color": 7, "font": 1, "max_recipients": 100 } ``` Group status example: ```json { "type": "image", "file": "https://exemplo.com/status.jpg", "text": "Aviso para o grupo", "group": "120363123456789012@g.us" } ``` ## OpenAPI ````yaml /openapi-en.json post /send/status openapi: 3.1.0 info: title: WppFy - WhatsApp API version: 1.0.0 description: > API for managing WhatsApp instances and communications. ## Important Recommendation: WhatsApp Business **It is HIGHLY RECOMMENDED to use WhatsApp Business accounts** instead of regular WhatsApp for integration; regular WhatsApp may present inconsistencies, disconnections, limitations, and instability when used with our API. ## Authentication - Regular endpoints require a 'token' header with the instance token ## Instance States Instances can be in the following states: - `disconnected`: Disconnected from WhatsApp - `connecting`: Connection in progress - `connected`: Successfully connected and authenticated servers: - url: https://api.wppfy.com security: - token: [] tags: - name: Instance description: | Operations related to an instance's lifecycle, such as connecting, disconnecting, and checking status. - name: Proxy description: > WppFy uses an internal proxy by default. You can keep this default, configure your own proxy via `proxy_url`, or use your Android phone as a proxy by installing the app from https://github.com/WppFy/silver_proxy_apk (direct APK: https://github.com/WppFy/silver_proxy_apk/raw/refs/heads/main/silver_proxy.apk). If nothing is sent, we keep using the internal proxy. IPs are Brazilian; for international clients, consider a proxy in the client's region. - name: Profile description: | Operations related to the WhatsApp instance profile, such as changing the profile name and picture. - name: Business description: | ⚠️ **EXPERIMENTAL** - Endpoints not yet fully tested. Operations related to the WhatsApp Business business profile. Allows querying and updating business profile data such as description, address, email, categories, and managing the product catalog. **Requirements:** - The currently connected account must be a **WhatsApp Business** account - Personal WhatsApp accounts do not have a business profile **Note:** These endpoints may not work as expected. Report any problems found. - name: Calls description: | Operations related to WhatsApp calls. Allows making and rejecting calls programmatically. - name: Send Message description: > Endpoints for sending WhatsApp messages with different content types. ## Common Optional Fields All message sending endpoints support the following optional fields: - **`delay`** *(integer)*: Delay in milliseconds before sending - During the delay, "Typing..." or "Recording audio..." will appear depending on the type - Example: `5000` (5 seconds) - **`readchat`** *(boolean)*: Mark chat as read after sending - Removes the unread message counter from the chat - Example: `true` - **`readmessages`** *(boolean)*: Mark last received messages as read - Marks the last 10 **received** messages (not sent by you) as read - Useful to confirm reading pending messages before replying - Different from `readchat` which only removes the unread counter - Example: `true` - **`replyid`** *(string)*: ID of the message to reply to - Creates a reply linked to the original message - Support varies by message type - Example: `"3A12345678901234567890123456789012"` - **`mentions`** *(string)*: Numbers to mention (only for group sending) - Specific numbers: `"5511999999999,5511888888888"` - Mention all: `"all"` - **`forward`** *(boolean)*: Marks the message as forwarded in WhatsApp - Adds the "Forwarded" indicator to the message - Example: `true` - **`track_source`** *(string)*: Message tracking source - Identifies the system or source sending the message - Useful for integrations (e.g., "chatwoot", "crm", "chatbot") - Example: `"chatwoot"` - **`track_id`** *(string)*: ID for message tracking - Free identifier to track the message in external systems - Allows correlating messages between different platforms - **Note**: The system accepts duplicate values - there is no uniqueness validation - Use the same ID in multiple messages if it makes sense for your integration - Example: `"msg_123456789"` ### Sending to Groups - **`number`** *(string)*: To send a message to a group, use the group ID ending with `@g.us` - Example: `"120363012345678901@g.us"` - **How to get the Group ID:** - Use the `chatid` from the webhook received when someone sends a message in the group - Use the `GET /group/list` endpoint to list all groups and their IDs ## Available Placeholders All message sending endpoints support dynamic placeholders for automatic personalization: ### Name Fields - **`{{name}}`**: Consolidated chat name, using the first available option: 1. Lead name (`lead_name`) 2. Lead full name (`lead_fullName`) 3. WhatsApp contact name (`wa_contactName`) 4. WhatsApp profile name (`wa_name`) - **`{{first_name}}`**: First valid word of the consolidated name (minimum 2 characters) ### WhatsApp Fields - **`{{wa_name}}`**: WhatsApp profile name - **`{{wa_contactName}}`**: Contact name as saved in WhatsApp ### Lead Fields - **`{{lead_name}}`**: Lead name - **`{{lead_fullName}}`**: Lead full name - **`{{lead_personalid}}`**: Personal ID (SSN, CPF, CNPJ, etc) - **`{{lead_email}}`**: Lead email - **`{{lead_status}}`**: Current lead status - **`{{lead_notes}}`**: Lead notes - **`{{lead_assignedAttendant_id}}`**: ID of the assigned attendant ### Custom Fields Fields added via custom fields are accessible using `{{lead_field01}}` to `{{lead_field20}}` or use `{{fieldname}}` defined in `/instance/updateFieldsMap`. ### Usage Example ``` Hello {{name}}! I saw you work at {{company}}. Is your email {{lead_email}} correct? ``` **πŸ’‘ Tip**: Use `/chat/find` to fetch chat data and see available fields before sending messages with placeholders. - name: Async Message description: > Operational controls for the internal asynchronous send queue used when a send endpoint receives `async=true`. This section is used to: - check the current state of the async queue - configure the delay between messages sent with `async=true` - clear pending backlog and cancel messages not yet completed Scope: - covers only the internal queue of async direct messages - does not change messages already sent successfully - name: Message Actions and Search - name: Chats - name: Contacts - name: Blocklist - name: Labels - name: Groups and Communities - name: Newsletters and Channels description: > Operations for reading and following WhatsApp channels (newsletters). Main use cases: - list posts already published in a channel - edit recent posts in a channel - delete recent posts in a channel - check post views and reactions - integrate channels without needing to persist messages locally Notes: - `/newsletter/messages` returns the post content - `/newsletter/messages/edit` edits the content of recent posts - `/newsletter/messages/delete` deletes recent posts - views (`viewsCount`) and reactions (`reactionCounts`) come in each post of `/newsletter/messages`, not via webhook event - `/newsletter/updates` is deprecated: WhatsApp does not respond and the API returns 504 - newsletters use their own routes and must not use `/message/edit` or `/message/delete` - name: Quick Replies description: > Management of quick replies to streamline service. **⚠️ Important**: This feature is only useful if you use a custom frontend/interface to register and use the replies. The API only stores the replies, but does not apply them automatically. ### How it works: - **Create**: Register pre-defined responses with titles and content - **List**: Retrieve all registered responses to display in your interface - **Use**: Your frontend system can use these responses to speed up typing ### Use cases: - Custom web service interfaces - Mobile apps with reply suggestions - CRM systems with message templates - Productivity tools for attendants **Not a chatbot**: For automatic responses, use Chatbot features. - name: CRM description: > Complete customer relationship management system integrated with the API. **πŸ’Ύ Internal Storage**: All lead data is saved directly in the API, eliminating the need for external databases. Your application can focus only on the interface and business logic. ### Available Features: - **πŸ“‹ 20+ customizable fields**: Name, phone, email, company, notes, etc. - **🏷️ Label System**: Organize and categorize your contacts - **πŸ” Advanced Search**: Filter by any field or label - **πŸ“Š Complete History**: All interactions are registered automatically ### 🎯 Placeholders in messages: Use dynamic variables in messages for automatic personalization: ``` Hello {{name}}! I saw you work at {{company}}. Is your email {{email}} correct? Notes: {{notes}} ``` ### Typical Flow: 1. **Capture**: Leads arrive via WhatsApp or forms 2. **Enrichment**: Add data using `/chat/editLead` 3. **Segmentation**: Organize with labels 4. **Communication**: Send personalized messages with placeholders 5. **Follow-up**: History is saved automatically **Ideal for**: Sales, marketing, support, lead qualification - name: Chatwoot Integration description: > **🚧 BETA INTEGRATION - Chatwoot integration system for unified service** **⚠️ WARNING**: This integration is in BETA phase. Use at your own risk. We recommend testing in a non-production environment before use in production. This category contains resources to configure and manage integration with Chatwoot, an open-source customer service platform. The integration allows centralizing WhatsApp conversations in Chatwoot. ### Available Features: - πŸ”§ **Complete Configuration**: Configure URL, tokens, and Chatwoot credentials - πŸ“¬ **Bidirectional Sync**: New messages between WhatsApp and Chatwoot are synced automatically - πŸ“± **Contact Management**: Automatic sync of names and phones - πŸ”„ **LIDβ†’PN Update**: Automatic migration from Local ID to Phone Number - 🏷️ **Smart Names**: Name system with tilde (~) for automatic update - 🚫 **Group Separation**: Option to ignore groups in sync - πŸ‘€ **Message Signature**: Agent identification in sent messages - πŸ”— **Automatic Webhook**: URL generated automatically to configure in Chatwoot ### 🏷️ Smart Name System: - **Names with tilde (~)**: Updated automatically when contact modifies name in WhatsApp - **Specific names**: For fixed name, remove tilde (~) from name in Chatwoot - **Example**: "~John Doe" = automatic, "John Doe" = fixed - **LIDβ†’PN Migration**: No conversation duplication during transition - **Native responses**: Appear directly in Chatwoot without external markings ### ⚠️ Known Limitations: - **History sync**: Not implemented - only new messages are synced ### Use Cases: - Centralized service in Chatwoot - Support teams with multiple agents - CRM integration via Chatwoot - Communication channel centralization - Automatic contact and name management **Ideal for**: Companies with service teams, call centers, technical support (in test environment) **Requires**: Configured Chatwoot instance, API tokens, and test environment **🚧 Remember**: BETA integration - features may change without prior notice - name: Server-Sent Events (SSE) paths: /send/status: post: tags: - Send Message summary: Send status (stories) description: > Sends a WhatsApp status with support for text, image, video, and audio. This endpoint has 4 usage modes: - normal send: omit `recipients`, `max_recipients`, and `group` - explicit send: provide `recipients` to send only to specific numbers; the API keeps the valid ones and discards the invalid ones with a reason in `debug` - partial send: provide `max_recipients` to limit the audience or apply a safety cap on `recipients` - group status: provide `group` with the group JID (`@g.us`) ## Important note about `recipients` When `recipients` is provided, the API: - accepts numbers in WhatsApp format, `@s.whatsapp.net` JIDs, and `@lid` JIDs - when it receives `@lid`, tries to resolve that identifier to the PN (`@s.whatsapp.net`) using the links known by the instance - if the `@lid` cannot be resolved to a PN, that item is discarded with reason `lid_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 as `invalid_format`, `lid_unresolved`, `not_on_whatsapp`, `outside_status_audience`, and `duplicate` - the request only returns `400` when 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 `recipients` or `max_recipients` (returns `400`) - the response includes `Id`, `content`, `messageTimestamp`, and `status`, without `debug` ## Supported types - `text`: text with background color and font - `image`: image with optional caption - `video`: video with optional caption - `audio`: regular audio - `myaudio`: audio sent as voice - `ptt`: 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 yellow - `2`: pale yellow - `3`: vibrant orange yellow - `4`: vibrant green - `5`: moss green - `6`: light green - `7`: pool blue - `8`: deep blue - `9`: light grayish blue - `10`: light lilac - `11`: warm lilac - `12`: bluish purple - `13`: deep magenta - `14`: soft pink - `15`: pinkish salmon - `16`: light brown - `17`: light bluish gray - `18`: medium gray - `19`: default deep gray Quick example: - `7`: pool blue - `13`: deep magenta - `19`: deep gray (default) ## Valid fonts for `type=text` Currently accepted values: `0`, `1`, `2`, `6`, `7`, `8`, `9`, `10`. ## Limits - `text`: maximum of 656 characters - `max_recipients`: cannot be negative - `recipients`: accepts numbers, `@s.whatsapp.net` JIDs, and `@lid` JIDs - `@lid` is only included in the send when it can be resolved locally to a valid PN; otherwise, it is discarded - for media types, `file` is required - `group`: group JID (`@g.us`) Explicit send example: ```json { "type": "text", "text": "Novidades chegando!", "recipients": [ "5511999999999", "5511888888888@s.whatsapp.net" ] } ``` Partial send example: ```json { "type": "text", "text": "Novidades chegando!", "background_color": 7, "font": 1, "max_recipients": 100 } ``` Group status example: ```json { "type": "image", "file": "https://exemplo.com/status.jpg", "text": "Aviso para o grupo", "group": "120363123456789012@g.us" } ``` requestBody: required: true content: application/json: schema: type: object properties: type: type: string enum: - text - image - video - audio - myaudio - ptt description: Status type. example: text text: type: string description: Main text or caption. example: News coming soon! background_color: type: integer minimum: 1 maximum: 19 description: Background color index for text status. example: 7 font: type: integer enum: - 0 - 1 - 2 - 6 - 7 - 8 - 9 - 10 description: Font accepted for `type=text`. example: 1 file: type: string description: URL or base64 of the media file. example: https://example.com/video.mp4 thumbnail: type: string description: >- Field accepted in the payload; the API generates the thumbnail automatically when needed. example: https://example.com/thumb.jpg mimetype: type: string description: File MIME type, when needed. example: video/mp4 recipients: type: array description: >- 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. items: type: string example: - '5511999999999' - 5511888888888@s.whatsapp.net max_recipients: type: integer minimum: 0 description: >- 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. example: 100 group: type: string description: >- 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 required: - type examples: text: summary: Text status value: type: text text: Novidades chegando! image: summary: Image status value: type: image file: https://exemplo.com/status.jpg text: Confira a novidade audio: summary: Audio status value: type: audio file: https://exemplo.com/audio.mp3 group: summary: Group status value: type: image file: https://exemplo.com/status.jpg text: Aviso para o grupo group: 120363123456789012@g.us responses: '200': description: Status sent successfully content: application/json: schema: type: object properties: Id: type: string description: Message ID when an actual send occurs. example: ABCD1234 content: type: object description: Processed message content when there is an actual send. messageTimestamp: type: integer description: Timestamp in milliseconds when there is an actual send. example: 1672531200000 status: type: string description: Send status when there is an actual send. example: Pending debug: type: object description: >- Aggregated metrics of the audience and the applied selection. properties: status_privacy_type: type: string example: contacts audience_recipient_count: type: integer example: 245 total_contacts_in_store: type: integer example: 300 contacts_with_full_name: type: integer example: 245 contacts_with_push_name_only: type: integer example: 32 contacts_with_business_name_only: type: integer example: 23 used_default_privacy_fallback: type: boolean example: false privacy_lookup_error: type: string example: privacy unavailable explicit_recipients: type: boolean example: true requested_recipient_count: type: integer example: 25 resolved_recipient_count: type: integer example: 20 discarded_recipient_count: type: integer example: 5 discarded_recipients: type: array items: type: object properties: input: type: string example: 144637553594388@lid reason: type: string example: lid_unresolved max_recipients: type: integer example: 100 selected_recipient_count: type: integer example: 100 partial_send: type: boolean example: true '400': description: Invalid request content: application/json: schema: type: object properties: error: type: string example: Invalid font debug: type: object description: >- Present especially when `recipients` was provided, to indicate which items were discarded before concluding that no valid recipient remained. '401': description: Unauthorized '500': description: Internal server error content: application/json: schema: type: object properties: error: type: string example: 'failed to determine status audience: privacy unavailable' components: securitySchemes: token: name: token type: apiKey in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.