WhatsApp Activities

Use the WhatsApp group to send messages and manage message templates through Meta's WhatsApp Business Cloud API. Every activity calls graph.facebook.com with the OAuth connection held by the WhatsApp resource.

Available activities

Activity	Purpose	Meta endpoint
WhatsApp	OAuth resource: signs in with Meta and holds the connection	—
Send Message	Sends a text, template, media, interactive, location, contacts or reaction message	`POST /v25.0/{phoneNumberId}/messages`
List Message Templates	Lists a WhatsApp Business Account's templates, one page at a time	`GET /v23.0/{wabaId}/message_templates`
Get Message Template	Reads one template by id, including why Meta rejected it	`GET /v23.0/{templateId}`
Create Message Template	Creates a template and submits it for Meta review	`POST /v23.0/{wabaId}/message_templates`
Edit Message Template	Replaces a template's components, category or TTL	`POST /v23.0/{templateId}`
Delete Message Template	Deletes a template by name, or one language version	`DELETE /v23.0/{wabaId}/message_templates`
List Phone Numbers	Lists the phone numbers registered on a WhatsApp Business Account	`GET /v23.0/{wabaId}/phone_numbers`

All of them are built on the REST Client: the host, method and path are preset, and the request body is filled in on the Input tab. Meta upgrades v23.0 calls to its current Graph API version automatically.

Before you begin

You need the following on the Meta side:

A Meta app with the WhatsApp use case (Meta for Developers → My Apps). The Studio signs in through the app's Facebook Login for Business.
A WhatsApp Business Account (WABA) with at least one phone number. A new app gets a free test number.
Access to the business portfolio that owns the WABA. Your Meta user must be a member of that business portfolio, with the WhatsApp account assigned to you. Without it, calls fail with error 100, subcode 33 (see Troubleshooting).
For a test number only: each recipient added to the test number's allowed list (up to five numbers) and verified with the code WhatsApp sends them.

Find your ids

The activities ask for two different ids. Neither is a phone number.

Id	Used by	Where to find it
Phone Number ID	Send Message	Meta app → Use cases → Connect with customers through WhatsApp → Customize → API Setup, under the From number. Also in WhatsApp Manager → Phone numbers.
WhatsApp Business Account ID (WABA ID)	List, Create and Delete Message Templates; List Phone Numbers	The same API Setup page, next to the Phone Number ID. Also in Business settings → Accounts → WhatsApp accounts.

Template ids, used by Get and Edit Message Template, are returned by Create Message Template and List Message Templates.

Connect WhatsApp

In your application, add a WhatsApp resource under Resources.
Keep the default scopes on Customized Scopes: whatsapp_business_management, whatsapp_business_messaging and business_management.
On Configuration, click Sign in with Meta.
In Meta's dialog, select the business portfolio that owns your WhatsApp account and opt in to its WhatsApp accounts. Then save the resource.
On each WhatsApp activity, open the Auth tab and drop this resource into WhatsApp Connection.

To review or change what the connection was granted, open Meta Business settings → Integrations → Business integrations.

Send a template message

A template is the only kind of message you can send to someone who hasn't messaged your business in the last 24 hours. hello_world is pre-approved on every WhatsApp Business Account, so it makes a good first test.

Add Send Message.
On Configuration, set:
- Phone Number ID: your sending number's id.
- To: the recipient with country code, digits only, for example 918720800616.
- Message Type: template.

On Input, map the template under body:

{
  "template": {
    "name": "hello_world",
    "language": { "code": "en_US" }
  }
}

Run the workflow. A successful send returns HTTP 200 with the message id in messages[0].id.

To fill a template's placeholders, add components, with one entry for each part of the template that has placeholders. For a template with named parameters:

{
  "template": {
    "name": "order_update",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "parameter_name": "first_name", "text": "Ashish" },
          { "type": "text", "parameter_name": "order_id", "text": "A1234" }
        ]
      }
    ]
  }
}

For a template with positional parameters ({{1}}, {{2}}), leave out parameter_name and list the parameters in order.

Send a text or media message

Free text is allowed only within 24 hours of the recipient's last message to your business. Outside that window, send a template instead.

On Configuration, set Message Type to text.

On Input, map:

{ "text": { "body": "Your order has shipped." } }

Images, video, documents and audio work the same way: set Message Type to the media type and map an object with either link (a public HTTPS URL) or id (a media id from Meta's media upload API):

{ "image": { "link": "https://example.com/receipt.jpg", "caption": "Your receipt" } }

Manage message templates

Create a template

Use Create Message Template with your WABA ID, and map the template on Input:

{
  "name": "order_update",
  "language": "en_US",
  "category": "UTILITY",
  "parameter_format": "named",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Order {{order_id}} update",
      "example": {
        "header_text_named_params": [{ "param_name": "order_id", "example": "A1234" }]
      }
    },
    {
      "type": "BODY",
      "text": "Hi {{first_name}}, your order has shipped. Thank you for shopping with us!",
      "example": {
        "body_text_named_params": [{ "param_name": "first_name", "example": "Ashish" }]
      }
    },
    { "type": "FOOTER", "text": "Sent by Koodisi" },
    {
      "type": "BUTTONS",
      "buttons": [{ "type": "QUICK_REPLY", "text": "Track order" }]
    }
  ]
}

Meta returns the new template's id with status PENDING. Review of a UTILITY template usually finishes within minutes.

Meta rejects the request if any of these rules is broken:

Name: lowercase letters, digits and underscores only, and not in use. A deleted template's name can't be reused for 30 days.
Placeholders at the edges: a header, body or footer text can't start or end with a placeholder. Order {{order_id}} fails, and so does arrive by {{eta}}., because the period doesn't count. Put words after the last placeholder.
Examples: every placeholder needs a matching entry under example.
Unused fields: leave out components and fields you don't use instead of sending them empty.

Check status and review results

List Message Templates returns up to 100 templates per page. Set Status Filter to PENDING, APPROVED or REJECTED to narrow the list, and pass paging.cursors.after from one response as After (cursor) to fetch the next page.
Get Message Template reads one template by id. Its rejected_reason explains a rejection, for example INVALID_FORMAT or PROMOTIONAL.

Edit or delete a template

Edit Message Template replaces the template's whole components array. Only APPROVED, REJECTED or PAUSED templates can be edited, and an approved template at most once per 24 hours and 10 times per 30 days. The name and language can't change.
Delete Message Template deletes by Template Name, in every language. Add Template ID (one language) to delete a single language version. DISABLED templates can't be deleted.

Troubleshooting

When Meta rejects a call, the step fails and its error details carry Meta's error.code, error.error_subcode and error.message.

Error	Meaning	Fix
`100`, subcode `33`: "Object with ID … does not exist, cannot be loaded due to missing permissions"	The id is the wrong kind (for example a WABA ID used as a Phone Number ID), or the connection can't access it.	Check the id on API Setup. Make sure your Meta user belongs to the business portfolio that owns the WABA, then sign in again on the WhatsApp resource.
`131030`: recipient not in allowed list	Sending from a test number to a number that isn't on its allowed list.	Add and verify the recipient on API Setup, under To.
`131047`: re-engagement message	A non-template message sent outside the 24-hour window.	Send an approved template instead.
`100`, subcode `2388299`: "Leading or trailing params not allowed"	A template text starts or ends with a placeholder.	Add words before or after the placeholder.
`100`: "violated JSON schema constraint 'enum' for the JSON field 'type'"	Message Type isn't a supported value.	Use one of `text`, `template`, `image`, `video`, `document`, `audio`, `sticker`, `interactive`, `location`, `contacts` or `reaction`.
`190`, or HTTP `401` from Meta	The connection's token has expired or been revoked.	Sign in again on the WhatsApp resource.
List returns `"data": []` although templates exist	A filter matched nothing, for example a wrong Status Filter or Name Filter value.	Clear the filters and list again.

Meta reference

Topic	Meta documentation
Getting started with the Cloud API	WhatsApp Cloud API Get Started
Messages API (request and response)	Messages reference
Sending messages and the 24-hour window	Service messages
Text messages	Text messages
Message templates	Template fundamentals
Template components	Template components
Media (upload, `id` and `link`)	Media reference
Phone numbers	Business phone numbers
Error codes	Error codes
Pricing	Pricing on the WhatsApp Business Platform
Facebook Login for Business	Facebook Login for Business
Graph API versions	Platform versioning

Available activities​

Before you begin​

Find your ids​

Connect WhatsApp​

Send a template message​

Send a text or media message​

Manage message templates​

Create a template​

Check status and review results​

Edit or delete a template​

Troubleshooting​

Meta reference​