# WhatsApp

> Send WhatsApp messages from your business number (text, templates, media, buttons and lists), manage message templates and your business profile.

App · Messaging · 19 actions. Web page: https://docs.lodol.com/docs/integrations/whatsapp

## Actions

### Block users

Block WhatsApp users from messaging your business number. WhatsApp only lets you block someone who messaged you in the last 24 hours; any it refuses are listed with the reason.

**Inputs**

- Phone numbers (`users`, list, required): The phone numbers to block, with country code, up to 1000.
- Business phone number (`phone_number_id`, text): Which of your business numbers to use. Leave empty to use the one saved on the connection.

**Outputs**

- `blocked_count` (number)
- `blocked_users` (list)
- `failed_count` (number)
- `failed_users` (list)
- `phone_number_id` (text)

**Example output**

```json
{
  "blocked_count": 1,
  "blocked_users": [
    {
      "input": "+16505551234",
      "wa_id": "16505551234"
    }
  ],
  "failed_count": 0,
  "failed_users": [],
  "phone_number_id": "106540352242922"
}
```

### Create a message template

Submit a UTILITY or MARKETING message template for Meta's review. Placeholders are written {{1}}, {{2}} or {{first_name}} in the text, with one example value each. Review usually finishes within minutes and can take up to 24 hours; until then the template is PENDING and cannot be sent.

**Inputs**

- Template name (`name`, text, required): Lowercase letters, digits and underscores; spaces become underscores.
- Category (`category`, text, required): UTILITY for updates about something the customer did (orders, bookings); MARKETING for promotions. One of: `UTILITY`, `MARKETING`. Default: `UTILITY`.
- Body (`body_text`, text, required): The message text, up to 1024 characters, such as 'Hi {{1}}, your order {{2}} has shipped.'
- Body example values (`body_examples`, list): One example value per placeholder in the body, in the order they first appear. Meta's reviewers read these.
- Language code (`language_code`, text): Such as en_US, en or es. Defaults to en_US. Default: `en_US`.
- Header (`header_text`, text): Optional bold header line, up to 60 characters.
- Header example value (`header_example`, text): An example value if the header has a placeholder.
- Footer (`footer_text`, text): Optional small grey footer, up to 60 characters.
- Quick reply buttons (`quick_reply_buttons`, list): Up to 10 button labels, each up to 25 characters.

**Outputs**

- `template` (object)

**Example output**

```json
{
  "template": {
    "category": "UTILITY",
    "id": "1234567890123456",
    "language": "en_US",
    "name": "order_update",
    "parameter_format": "POSITIONAL",
    "status": "PENDING"
  }
}
```

### Delete a message template

Delete a message template. Without a template ID every language of that name is deleted. The name of a deleted approved template cannot be reused for 30 days, and a disabled template cannot be deleted.

**Inputs**

- Template name (`template_name`, text, required): The name of the template to delete.
- Template ID (`template_id`, text): Optionally, the id of one language version, to delete only that one.

**Outputs**

- `all_languages` (true/false)
- `deleted` (true/false)
- `template_id` (text)
- `template_name` (text)

**Example output**

```json
{
  "all_languages": false,
  "deleted": true,
  "template_id": "1234567890123456",
  "template_name": "order_update"
}
```

### Get a message template

Read one message template, including whether it has been approved yet and, if not, why it was rejected.

**Inputs**

- Template ID (`template_id`, text, required): The template's numeric id, as List message templates or Create a message template returns it.

**Outputs**

- `template` (object)

**Example output**

```json
{
  "template": {
    "body_text": "Hi {{1}}, your order {{2}} has shipped.",
    "category": "UTILITY",
    "components": [
      {
        "text": "Hi {{1}}, your order {{2}} has shipped.",
        "type": "BODY"
      }
    ],
    "id": "1234567890123456",
    "language": "en_US",
    "name": "order_update",
    "parameter_format": "POSITIONAL",
    "quality_score": "GREEN",
    "rejected_reason": "NONE",
    "status": "APPROVED"
  }
}
```

### Get a phone number

Read one business phone number's status, quality rating, display name review status and the business's messaging limit tier.

**Inputs**

- Business phone number (`phone_number_id`, text): Which of your business numbers to use. Leave empty to use the one saved on the connection.

**Outputs**

- `phone_number` (object)

**Example output**

```json
{
  "phone_number": {
    "account_mode": "LIVE",
    "code_verification_status": "VERIFIED",
    "display_phone_number": "+1 555-005-1310",
    "id": "106540352242922",
    "messaging_limit_tier": "TIER_1K",
    "name_status": "APPROVED",
    "quality_rating": "GREEN",
    "status": "CONNECTED",
    "verified_name": "Lodol Demo"
  }
}
```

### Get business profile

Read the public business profile customers see: about text, description, address, email, websites and industry.

**Inputs**

- Business phone number (`phone_number_id`, text): Which of your business numbers to use. Leave empty to use the one saved on the connection.

**Outputs**

- `business_profile` (object)
- `phone_number_id` (text)

**Example output**

```json
{
  "business_profile": {
    "about": "Workflows that run themselves.",
    "address": "1 Market St, San Francisco, CA 94105",
    "description": "Lodol automates the busywork between your tools.",
    "email": "hello@example.com",
    "profile_picture_url": "https://pps.whatsapp.net/v/t61.24694-24/example.jpg",
    "vertical": "PROF_SERVICES",
    "websites": [
      "https://www.example.com/"
    ]
  },
  "phone_number_id": "106540352242922"
}
```

### List message templates

List the WhatsApp Business Account's message templates with each one's status, category, language and body text.

**Inputs**

- Name (`name`, text): Only return templates with this name.
- Status (`status`, text): Only return templates in this status. One of: `APPROVED`, `PENDING`, `REJECTED`, `PAUSED`, `DISABLED`, `IN_APPEAL`, `LIMIT_EXCEEDED`, `ARCHIVED`, `PENDING_DELETION`, `DELETED`.
- Maximum results (`max_results`, number): How many rows to return (1-500). Defaults to 25. From 1 to 500. Default: `25`.

**Outputs**

- `count` (number): How many were returned.
- `templates` (list)

**Example output**

```json
{
  "count": 1,
  "templates": [
    {
      "body_text": "Hi {{1}}, your order {{2}} has shipped.",
      "category": "UTILITY",
      "components": [
        {
          "text": "Hi {{1}}, your order {{2}} has shipped.",
          "type": "BODY"
        }
      ],
      "id": "1234567890123456",
      "language": "en_US",
      "name": "order_update",
      "parameter_format": "POSITIONAL",
      "quality_score": "GREEN",
      "rejected_reason": "NONE",
      "status": "APPROVED"
    }
  ]
}
```

### List phone numbers

List the business phone numbers on the WhatsApp Business Account, with each one's id, status and quality rating.

**Inputs**

- Maximum results (`max_results`, number): How many rows to return (1-500). Defaults to 25. From 1 to 500. Default: `25`.

**Outputs**

- `count` (number): How many were returned.
- `phone_numbers` (list)

**Example output**

```json
{
  "count": 1,
  "phone_numbers": [
    {
      "account_mode": "LIVE",
      "code_verification_status": "VERIFIED",
      "display_phone_number": "+1 555-005-1310",
      "id": "106540352242922",
      "messaging_limit_tier": "TIER_1K",
      "name_status": "APPROVED",
      "quality_rating": "GREEN",
      "status": "CONNECTED",
      "verified_name": "Lodol Demo"
    }
  ]
}
```

### React to a message

Put an emoji reaction on a message in the chat. WhatsApp accepts the call even when the reaction cannot be shown (a message over 30 days old, deleted, or itself a reaction); that failure is only reported by webhook. WhatsApp only delivers this to someone who messaged your number in the last 24 hours; outside that window, send a template message instead.

**Inputs**

- To (`to`, text, required): The recipient's WhatsApp number with its country code, such as +16505551234. Spaces, dashes and brackets are fine; a wa_id from a webhook works as-is.
- Message ID (`message_id`, text, required): The wamid.… id of the message to react to.
- Emoji (`emoji`, text, required): The emoji to react with, such as 👍.
- Business phone number (`phone_number_id`, text): Which of your business numbers to use. Leave empty to use the one saved on the connection.

**Outputs**

- `message_id` (text)
- `message_status` (text)
- `recipient_wa_id` (text)
- `to` (text)

**Example output**

```json
{
  "message_id": "wamid.HBgLMTY1MDU1NTEyMzQVAgARGBI4QzY3RjQ0RUQ3QjA1NEM2OQA=",
  "message_status": "accepted",
  "recipient_wa_id": "16505551234",
  "to": "+16505551234"
}
```

### Send a document

Send a document (PDF, Word, Excel, PowerPoint or text, up to 100 MB) by public URL. WhatsApp only delivers this to someone who messaged your number in the last 24 hours; outside that window, send a template message instead.

**Inputs**

- To (`to`, text, required): The recipient's WhatsApp number with its country code, such as +16505551234. Spaces, dashes and brackets are fine; a wa_id from a webhook works as-is.
- Media URL (`media_url`, text): A public http(s) link to the file for WhatsApp to download. Give this or a media ID.
- Media ID (`media_id`, text): The id of media already uploaded to WhatsApp, instead of a URL. Uploaded media ids expire after 30 days.
- Caption (`caption`, text): Optional caption, up to 1024 characters.
- File name (`filename`, text): The name shown to the recipient, with its extension, such as invoice.pdf.
- Reply to message ID (`reply_to_message_id`, text): Optionally quote an earlier message (its wamid.… id) so this one shows as a reply to it.
- Business phone number (`phone_number_id`, text): Which of your business numbers to use. Leave empty to use the one saved on the connection.

**Outputs**

- `message_id` (text)
- `message_status` (text)
- `recipient_wa_id` (text)
- `to` (text)

**Example output**

```json
{
  "message_id": "wamid.HBgLMTY1MDU1NTEyMzQVAgARGBI4QzY3RjQ0RUQ3QjA1NEM2OQA=",
  "message_status": "accepted",
  "recipient_wa_id": "16505551234",
  "to": "+16505551234"
}
```

### Send a list message

Send a message with a button that opens a list of up to ten options to pick from. WhatsApp only delivers this to someone who messaged your number in the last 24 hours; outside that window, send a template message instead.

**Inputs**

- To (`to`, text, required): The recipient's WhatsApp number with its country code, such as +16505551234. Spaces, dashes and brackets are fine; a wa_id from a webhook works as-is.
- Message (`body`, text, required): The message text, up to 4096 characters.
- Button label (`button_label`, text, required): The label of the button that opens the list, up to 20 characters.
- Options (`rows`, list, required): Up to 10 options. Each is a title (up to 24 characters), optionally followed by ' | ' and a description (up to 72).
- List heading (`section_title`, text): Heading above the options, up to 24 characters. Defaults to the button label.
- Header (`header_text`, text): Optional bold header line, up to 60 characters.
- Footer (`footer_text`, text): Optional small grey footer, up to 60 characters.
- Reply to message ID (`reply_to_message_id`, text): Optionally quote an earlier message (its wamid.… id) so this one shows as a reply to it.
- Business phone number (`phone_number_id`, text): Which of your business numbers to use. Leave empty to use the one saved on the connection.

**Outputs**

- `message_id` (text)
- `message_status` (text)
- `recipient_wa_id` (text)
- `to` (text)

**Example output**

```json
{
  "message_id": "wamid.HBgLMTY1MDU1NTEyMzQVAgARGBI4QzY3RjQ0RUQ3QjA1NEM2OQA=",
  "message_status": "accepted",
  "recipient_wa_id": "16505551234",
  "to": "+16505551234"
}
```

### Send a location

Send a map pin with an optional name and address. WhatsApp only delivers this to someone who messaged your number in the last 24 hours; outside that window, send a template message instead.

**Inputs**

- To (`to`, text, required): The recipient's WhatsApp number with its country code, such as +16505551234. Spaces, dashes and brackets are fine; a wa_id from a webhook works as-is.
- Latitude (`latitude`, number, required): Latitude in decimal degrees, -90 to 90. From -90 to 90.
- Longitude (`longitude`, number, required): Longitude in decimal degrees, -180 to 180. From -180 to 180.
- Place name (`name`, text): Optional name shown above the pin.
- Address (`address`, text): Optional street address shown under the name.
- Reply to message ID (`reply_to_message_id`, text): Optionally quote an earlier message (its wamid.… id) so this one shows as a reply to it.
- Business phone number (`phone_number_id`, text): Which of your business numbers to use. Leave empty to use the one saved on the connection.

**Outputs**

- `message_id` (text)
- `message_status` (text)
- `recipient_wa_id` (text)
- `to` (text)

**Example output**

```json
{
  "message_id": "wamid.HBgLMTY1MDU1NTEyMzQVAgARGBI4QzY3RjQ0RUQ3QjA1NEM2OQA=",
  "message_status": "accepted",
  "recipient_wa_id": "16505551234",
  "to": "+16505551234"
}
```

### Send a template message

Send a pre-approved message template. This is the only kind of message you can send to someone who has not messaged you in the last 24 hours. Every new account has the approved hello_world template (language en_US).

**Inputs**

- To (`to`, text, required): The recipient's WhatsApp number with its country code, such as +16505551234. Spaces, dashes and brackets are fine; a wa_id from a webhook works as-is.
- Template name (`template_name`, text, required): The template's name, as List message templates shows it.
- Language code (`language_code`, text): The template's language code, such as en_US, en or es. Defaults to en_US. Default: `en_US`.
- Header value (`header_parameter`, text): The value for the placeholder in the template's text header, if it has one.
- Body values (`body_parameters`, list): One value per {{1}}, {{2}}, ... placeholder in the template body, in order.
- Named body values (`named_body_parameters`, object): For a template with named placeholders such as {{first_name}}: each placeholder name and its value.
- Components (advanced) (`components`, list): The raw template components JSON, for button or media-header parameters. Use instead of the value fields above.
- Reply to message ID (`reply_to_message_id`, text): Optionally quote an earlier message (its wamid.… id) so this one shows as a reply to it.
- Business phone number (`phone_number_id`, text): Which of your business numbers to use. Leave empty to use the one saved on the connection.

**Outputs**

- `message_id` (text)
- `message_status` (text)
- `recipient_wa_id` (text)
- `to` (text)

**Example output**

```json
{
  "message_id": "wamid.HBgLMTY1MDU1NTEyMzQVAgARGBI4QzY3RjQ0RUQ3QjA1NEM2OQA=",
  "message_status": "accepted",
  "recipient_wa_id": "16505551234",
  "to": "+16505551234"
}
```

### Send a text message

Send a plain text WhatsApp message. WhatsApp only delivers this to someone who messaged your number in the last 24 hours; outside that window, send a template message instead.

**Inputs**

- To (`to`, text, required): The recipient's WhatsApp number with its country code, such as +16505551234. Spaces, dashes and brackets are fine; a wa_id from a webhook works as-is.
- Message (`body`, text, required): The text to send, up to 4096 characters.
- Show link preview (`preview_url`, true/false): Show a preview of the first link in the message. Default: `false`.
- Reply to message ID (`reply_to_message_id`, text): Optionally quote an earlier message (its wamid.… id) so this one shows as a reply to it.
- Business phone number (`phone_number_id`, text): Which of your business numbers to use. Leave empty to use the one saved on the connection.

**Outputs**

- `message_id` (text)
- `message_status` (text)
- `recipient_wa_id` (text)
- `to` (text)

**Example output**

```json
{
  "message_id": "wamid.HBgLMTY1MDU1NTEyMzQVAgARGBI4QzY3RjQ0RUQ3QjA1NEM2OQA=",
  "message_status": "accepted",
  "recipient_wa_id": "16505551234",
  "to": "+16505551234"
}
```

### Send a video

Send an MP4 or 3GP video (H.264 and AAC, up to 16 MB) by public URL. WhatsApp only delivers this to someone who messaged your number in the last 24 hours; outside that window, send a template message instead.

**Inputs**

- To (`to`, text, required): The recipient's WhatsApp number with its country code, such as +16505551234. Spaces, dashes and brackets are fine; a wa_id from a webhook works as-is.
- Media URL (`media_url`, text): A public http(s) link to the file for WhatsApp to download. Give this or a media ID.
- Media ID (`media_id`, text): The id of media already uploaded to WhatsApp, instead of a URL. Uploaded media ids expire after 30 days.
- Caption (`caption`, text): Optional caption, up to 1024 characters.
- Reply to message ID (`reply_to_message_id`, text): Optionally quote an earlier message (its wamid.… id) so this one shows as a reply to it.
- Business phone number (`phone_number_id`, text): Which of your business numbers to use. Leave empty to use the one saved on the connection.

**Outputs**

- `message_id` (text)
- `message_status` (text)
- `recipient_wa_id` (text)
- `to` (text)

**Example output**

```json
{
  "message_id": "wamid.HBgLMTY1MDU1NTEyMzQVAgARGBI4QzY3RjQ0RUQ3QjA1NEM2OQA=",
  "message_status": "accepted",
  "recipient_wa_id": "16505551234",
  "to": "+16505551234"
}
```

### Send an image

Send a JPEG or PNG image (up to 5 MB) by public URL, with an optional caption. WhatsApp only delivers this to someone who messaged your number in the last 24 hours; outside that window, send a template message instead.

**Inputs**

- To (`to`, text, required): The recipient's WhatsApp number with its country code, such as +16505551234. Spaces, dashes and brackets are fine; a wa_id from a webhook works as-is.
- Media URL (`media_url`, text): A public http(s) link to the file for WhatsApp to download. Give this or a media ID.
- Media ID (`media_id`, text): The id of media already uploaded to WhatsApp, instead of a URL. Uploaded media ids expire after 30 days.
- Caption (`caption`, text): Optional caption, up to 1024 characters.
- Reply to message ID (`reply_to_message_id`, text): Optionally quote an earlier message (its wamid.… id) so this one shows as a reply to it.
- Business phone number (`phone_number_id`, text): Which of your business numbers to use. Leave empty to use the one saved on the connection.

**Outputs**

- `message_id` (text)
- `message_status` (text)
- `recipient_wa_id` (text)
- `to` (text)

**Example output**

```json
{
  "message_id": "wamid.HBgLMTY1MDU1NTEyMzQVAgARGBI4QzY3RjQ0RUQ3QjA1NEM2OQA=",
  "message_status": "accepted",
  "recipient_wa_id": "16505551234",
  "to": "+16505551234"
}
```

### Send reply buttons

Send a message with up to three tap-to-reply buttons. The customer's choice comes back as a reply carrying the button title. WhatsApp only delivers this to someone who messaged your number in the last 24 hours; outside that window, send a template message instead.

**Inputs**

- To (`to`, text, required): The recipient's WhatsApp number with its country code, such as +16505551234. Spaces, dashes and brackets are fine; a wa_id from a webhook works as-is.
- Message (`body`, text, required): The message text, up to 1024 characters.
- Button titles (`buttons`, list, required): One to three button titles, each up to 20 characters and unique.
- Header (`header_text`, text): Optional bold header line, up to 60 characters.
- Footer (`footer_text`, text): Optional small grey footer, up to 60 characters.
- Reply to message ID (`reply_to_message_id`, text): Optionally quote an earlier message (its wamid.… id) so this one shows as a reply to it.
- Business phone number (`phone_number_id`, text): Which of your business numbers to use. Leave empty to use the one saved on the connection.

**Outputs**

- `message_id` (text)
- `message_status` (text)
- `recipient_wa_id` (text)
- `to` (text)

**Example output**

```json
{
  "message_id": "wamid.HBgLMTY1MDU1NTEyMzQVAgARGBI4QzY3RjQ0RUQ3QjA1NEM2OQA=",
  "message_status": "accepted",
  "recipient_wa_id": "16505551234",
  "to": "+16505551234"
}
```

### Unblock users

Unblock WhatsApp users so they can message your business number again. Any WhatsApp refuses are listed with the reason.

**Inputs**

- Phone numbers (`users`, list, required): The phone numbers to unblock, with country code, up to 1000.
- Business phone number (`phone_number_id`, text): Which of your business numbers to use. Leave empty to use the one saved on the connection.

**Outputs**

- `failed_count` (number)
- `failed_users` (list)
- `phone_number_id` (text)
- `unblocked_count` (number)
- `unblocked_users` (list)

**Example output**

```json
{
  "failed_count": 0,
  "failed_users": [],
  "phone_number_id": "106540352242922",
  "unblocked_count": 1,
  "unblocked_users": [
    {
      "input": "+16505551234",
      "wa_id": "16505551234"
    }
  ]
}
```

### Update business profile

Change fields of the public business profile. Only the fields you fill in are changed.

**Inputs**

- About (`about`, text): Short status text, up to 139 characters.
- Description (`description`, text): Business description, up to 256 characters.
- Address (`address`, text): Up to 256 characters.
- Email (`email`, text): Contact email address.
- Websites (`websites`, list): Up to 2 http(s) URLs. Replaces the current list.
- Industry (`vertical`, text): The business's industry. One of: `OTHER`, `AUTO`, `BEAUTY`, `APPAREL`, `EDU`, `ENTERTAIN`, `EVENT_PLAN`, `FINANCE`, `GROCERY`, `GOVT`, and 11 more.
- Business phone number (`phone_number_id`, text): Which of your business numbers to use. Leave empty to use the one saved on the connection.

**Outputs**

- `phone_number_id` (text)
- `updated` (true/false)
- `updated_fields` (list)

**Example output**

```json
{
  "phone_number_id": "106540352242922",
  "updated": true,
  "updated_fields": [
    "about"
  ]
}
```