# WhatsApp Business

Send WhatsApp messages: text, media, buttons, lists and approved templates. From your WhatsApp Business number, and upload and download media.

## Connect WhatsApp Business

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `whatsapp business` and choose **WhatsApp Business**.
3. Fill in the fields. Each one says **Required** or **Optional**.
4. Press **Test and save**. GoRunner checks the connection before it saves anything.

The sheet asks for:

- **Access token · Required**: A system user’s access token (lasting), or a temporary one from API Setup for a first test (it ends within a day).
- **WhatsApp Business Account ID · Required**: The WABA ID shown on API Setup (a number).
- **Phone number ID · Required**: The ID of the phone number messages are sent from (API Setup › From; not the phone number itself).
- **App secret · Optional**: The Meta app’s secret (App settings › Basic), which Meta signs its webhooks with. Optional; steps do not use it.

From your Meta app with the WhatsApp product (developers.facebook.com › your app › WhatsApp › API Setup): a system user’s access token (Meta Business Settings › System users › Generate token, with whatsapp_business_messaging and whatsapp_business_management; it does not expire), the WhatsApp Business Account ID and the sending phone number’s ID. Meta signs the webhooks it sends with the app secret (App settings › Basic); steps do not need it.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Start a workflow

Add a trigger and choose **WhatsApp Business**. The trigger uses the same connection as the steps.

### On Message or Status

Starts a run when the connection's WhatsApp number receives a message, or (if chosen) when a message it sent is sent, delivered, read or fails. Publishing points that number's own webhook address at this workflow (the connection needs the app secret, and the Meta app's webhooks must include the WhatsApp Business Account's messages field); while published, the number's messages come here instead of the app's or the account's webhook address, and unpublishing gives them back. Meta signs every delivery with the app secret: an unsigned or wrongly signed request starts nothing, and a delivery Meta sends again starts no second run. One delivery can carry several messages: they are all under messages.

- **Trigger On · Required**: Which updates start a run. Options: Incoming messages, Status of sent messages (sent, delivered, read, failed).
- **Take Over · Optional**: If the number already has its own webhook address (another workflow or tool), or its WhatsApp Business Account has an alternate address, point the number here anyway. Unpublishing gives the account's alternate address back, but not a number address taken over: Meta checks an address with its owner's verify token, which only the owner knows. Off by default.

A later step can use its data, such as `{{trigger.business_account}}`, `{{trigger.contacts}}`, `{{trigger.from}}` and 5 more. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Do things in WhatsApp Business

Add a **WhatsApp Business** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Message](https://docs.gorunner.io/apps/whatsapp-business#fields-f-message): Send · Send Template · Mark as Read
- [Media](https://docs.gorunner.io/apps/whatsapp-business#fields-f-media): Upload · Get Media URL · Download · Delete
- [Template](https://docs.gorunner.io/apps/whatsapp-business#fields-f-template): Get Many
- [Phone Number](https://docs.gorunner.io/apps/whatsapp-business#fields-f-phonenumber): Get · Get Many

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from WhatsApp Business can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When WhatsApp Business says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, WhatsApp Business is `pieceId: "whatsapp"` with `actionId: "whatsapp"`, set by `resource` and an `operation_…` field, such as `operation_media`. Its trigger is `whatsapptrigger` / `whatsapp_update`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### WhatsApp Business › Message

### Send

- **Sender Phone Number · Optional**: The business number to use. Empty: the connection's phone number.
- **Recipient's Phone Number · Required**: The number in international form, such as +4915112345678.
- **Type · Required**: What to send. Outside 24 hours after the person last wrote, only a template can be sent (Send Template). Options: Text, Image, Video, Audio, Document, Sticker, Location, Reply buttons, List, Link button, Reaction. Default: Text.
- **Latitude · Required**: Shows when **Type** is **Location**.
- **Media From · Optional**: A file from an earlier step (uploaded first), a public link, or the id of media uploaded before. Options: File, Link, Media ID. Default: File. Shows when **Type** is **Image**, **Video**, **Audio**, **Document** or **Sticker**.
- **React To · Required**: The id (wamid.…) of the message to react to. Shows when **Type** is **Reaction**.
- **Text · Required**: The message, up to 4,096 characters (*bold*, _italic_, ~strike~ work). For buttons and link buttons: up to 1,024. Shows when **Type** is **Text**, **Reply buttons**, **List** or **Link button**.
- **Emoji · Optional**: The emoji, such as 👍. Empty removes your reaction. Shows when **Type** is **Reaction**.
- **Longitude · Required**: Shows when **Type** is **Location**.
- **File · Required**: Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). Images up to 5 MB (JPEG, PNG), video and audio up to 16 MB, documents up to 100 MB, stickers (WebP) up to 500 KB. Shows when **Type** is **Image**, **Video**, **Audio**, **Document** or **Sticker** and **Media From** is **File**.
- **Media ID · Required**: The id Media › Upload returned. Shows when **Type** is **Image**, **Video**, **Audio**, **Document** or **Sticker** and **Media From** is **Media ID**.
- **Link · Required**: A public https address of the file. Shows when **Type** is **Image**, **Video**, **Audio**, **Document** or **Sticker** and **Media From** is **Link**.
- **Show Link Preview · Optional**: Show a preview of the first link in the text. Off by default. Shows when **Type** is **Text**.
- **Header · Optional**: A bold first line (up to 60 characters). Shows when **Type** is **Reply buttons**, **List** or **Link button**.
- **Place Name · Optional**: The place's name. Shows when **Type** is **Location**.
- **Caption · Optional**: Text shown with the image, video or document. Shows when **Type** is **Image**, **Video** or **Document**.
- **Footer · Optional**: A small last line (up to 60 characters). Shows when **Type** is **Reply buttons**, **List** or **Link button**.
- **Address · Optional**: The place's address. Shows when **Type** is **Location**.
- **Filename · Optional**: The document's name as the person sees it. Shows when **Type** is **Document**.
- **Buttons · Required**: One to three button labels, one per line (up to 20 characters each). A reply to a button carries its label, with its number (1, 2, 3) as the reply's id. Shows when **Type** is **Reply buttons**.
- **Button Label · Required**: The link button's label (up to 20 characters). Shows when **Type** is **Link button**.
- **Menu Button · Required**: The label of the button that opens the list (up to 20 characters). Shows when **Type** is **List**.
- **Button Link · Required**: The https address the button opens. Shows when **Type** is **Link button**.
- **Sections · Required**: The list: [{"title": "Shipping", "rows": [{"id": "express", "title": "Express", "description": "1–2 days"}]}]. Up to 10 rows in all; titles up to 24 characters. Shows when **Type** is **List**.
- **Reply To · Optional**: Send it as a reply to this message id (wamid.…).

### Send Template

- **Sender Phone Number · Optional**: The business number to use. Empty: the connection's phone number.
- **Recipient's Phone Number · Required**: The number in international form, such as +4915112345678.
- **Template · Required**: An approved template of the account.
- **Language · Optional**: The template's language code (such as en_US), when Template is a name alone.
- **Parameters · Optional**: The values for the template's placeholders, as Meta's components: [{"type": "body", "parameters": [{"type": "text", "text": "Ada"}, {"type": "text", "text": "1042"}]}]. Empty for a template without placeholders.
- **Reply To · Optional**: Send it as a reply to this message id (wamid.…).

### Mark as Read

- **Sender Phone Number · Optional**: The business number to use. Empty: the connection's phone number.
- **Message ID · Required**: The incoming message's id (wamid.…) to mark as read (its blue ticks show).

### WhatsApp Business › Media

### Upload

- **Sender Phone Number · Optional**: The business number to use. Empty: the connection's phone number.
- **File · Required**: Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). Images up to 5 MB, video and audio up to 16 MB, documents up to 100 MB, stickers up to 500 KB. Meta keeps it 30 days.

### Get Media URL and Download

- **Media ID · Required**: The media's id (from an upload, or an incoming message's image/document/audio id).

### Delete

- **Media ID · Required**: The id of the uploaded media to delete.

### WhatsApp Business › Template

### Get Many

- **Status · Optional**: Only templates in this state. Empty: all. Options: APPROVED, PENDING, REJECTED, PAUSED, DISABLED, IN_APPEAL.
- **Name · Optional**: Only templates whose name contains this.
- **Return All · Optional**: Read every template, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many templates to return (1–1000). Default: 50. Shows when **Return All** is off.

### WhatsApp Business › Phone Number

### Get

- **Phone Number · Optional**: The number to read. Empty: the connection's.

### Get Many

- **Return All · Optional**: Read every phone number, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many phone numbers to return (1–1000). Default: 50. Shows when **Return All** is off.

Source: https://docs.gorunner.io/apps/whatsapp-business