manage_whatsapp_campaigns
Universal WhatsApp campaign management tool that handles all campaign operations through action-based parameters. Supports search, create, update, start, stop, and delete operations for WhatsApp bulk messaging campaigns. Perfect for comprehensive WhatsApp marketing automation.
What a campaign sends depends on the number. Its connector, reported by get_whatsapp_devices and health_check, says which kind it is: cloud for WhatsApp Cloud API, web for a number linked by QR.
WhatsApp Cloud API (WABA) numbers: a pre-approved template is required, and it only reaches phone numbers, never groups. Pass template { name, language } and give each recipient the values its variables need. Read the template first with list_whatsapp_templates: every variable it reports has a location (header, body or buttons) and, for buttons, a buttonIndex starting at 0. Send each value with its component, and for a button variable use button_url_N or button_copy_code_N with that index.
Numbers linked by QR: a message, optionally with a file. Personalize it with placeholders: {{ name }} is the recipient's name, {{ phone }} their number, and each key in a recipient's variables fills {{ key }}. For example message "Hi {{ name }}, your order {{ order }} has shipped" with variables [{ key: "order", value: "A-1043" }]. Write keys and placeholders in lowercase. A placeholder a recipient has no value for disappears from their message; {{ order | on its way }} prints the text after the bar instead.
To send it: create with activate true, which needs settings.date and at least one recipient, or create first and then start, which asks for the same two. If activation fails during create, the campaign is deleted and you have to create it again.
Recipients: pass them on create, up to 2000 per request. To add or remove them afterwards use manage_whatsapp_campaign_contacts. The total a campaign can hold depends on the plan, from 100 on trial to 2000.
What it will cost: before launching a template campaign, estimate_cost gives the price Meta lists per message for each country, in costs: one line per country (or dialling code) with the category of the template and how many messages go there.
Payment problems: when Meta reports one on a Cloud API number's WhatsApp Business account, the templates it sends are rejected (error 131042). A Cloud API number that needs reconnecting stops the same way, because its messages fail until it is reconnected. The three ways to send a campaign (create with activate true, update with activate true, and the start action) then refuse, say why and write nothing. Tell the user, and only repeat the call with confirmPaymentIssue true if they say the payment is already fixed or want to send anyway.
Things that do not undo: delete removes a campaign for good, and stop does not recall messages already handed to WhatsApp.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Uploaded file ID. On a template campaign this is the header media, and only for a template whose header is an image, video or document: on a template without a media header the API sends a header the template does not have and Meta rejects it. Upload the file first with upload_whatsapp_file_from_url | |
| name | No | Campaign name (required for create action) | |
| page | No | Results page number (for search action) | |
| size | No | Results page size (for search action, max 100) | |
| after | No | Filter campaigns created after this date (for search action) | |
| costs | No | For estimate_cost: one line per country of the recipients, with the template category and the number of messages. Up to 100 lines | |
| group | No | Filter campaigns by group IDs (for search action) | |
| owner | No | Filter by owner user IDs (for search action) | |
| phone | No | Filter campaigns by recipient phone numbers (for search action) | |
| action | Yes | Action to perform on WhatsApp campaigns | |
| before | No | Filter campaigns created before this date (for search action) | |
| device | No | WhatsApp device ID (required for create action) | |
| status | No | Filter campaigns by status (for search action) | |
| message | No | Campaign message, for numbers linked by QR. On a WhatsApp Cloud API number use template instead. Personalize it with {{ name }}, {{ phone }} and {{ key }} for each key in the recipients' variables | |
| activate | No | Start the campaign right after creating it. Needs settings.date and at least one recipient; without them the campaign is created and left as a draft | |
| contacts | No | Campaign recipients, for the create action only. Max 2000 per request, and the total a campaign can hold depends on the plan (100 on trial, 500 to 2000 otherwise). To add or remove recipients later use manage_whatsapp_campaign_contacts | |
| settings | No | Campaign delivery settings (for create/update actions) | |
| template | No | Pre-approved template to send. Required on WhatsApp Cloud API numbers, and not accepted on numbers linked by QR | |
| campaignId | No | WhatsApp campaign ID (required for get, update, start, stop, delete actions) | |
| unsubscribe | No | Unsubscribe settings (for create/update actions) | |
| confirmPaymentIssue | No | Only after telling the user that Meta reports a payment problem on the number, or that it needs reconnecting: true to activate or start the campaign anyway, because they say it is already fixed or reconnected, or want to send regardless |