WhatsApp

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

Actions

Action	What it does
Block users	Block WhatsApp users from messaging your business number.
Create a message template	Submit a UTILITY or MARKETING message template for Meta's review.
Delete a message template	Delete a message template.
Get a message template	Read one message template, including whether it has been approved yet and, if not, why it was rejected.
Get a phone number	Read one business phone number's status, quality rating, display name review status and the business's messaging limit tier.
Get business profile	Read the public business profile customers see: about text, description, address, email, websites and industry.
List message templates	List the WhatsApp Business Account's message templates with each one's status, category, language and body text.
List phone numbers	List the business phone numbers on the WhatsApp Business Account, with each one's id, status and quality rating.
React to a message	Put an emoji reaction on a message in the chat.
Send a document	Send a document (PDF, Word, Excel, PowerPoint or text, up to 100 MB) by public URL.
Send a list message	Send a message with a button that opens a list of up to ten options to pick from.
Send a location	Send a map pin with an optional name and address.
Send a template message	Send a pre-approved message template.
Send a text message	Send a plain text WhatsApp message.
Send a video	Send an MP4 or 3GP video (H.264 and AAC, up to 16 MB) by public URL.
Send an image	Send a JPEG or PNG image (up to 5 MB) by public URL, with an optional caption.
Send reply buttons	Send a message with up to three tap-to-reply buttons.
Unblock users	Unblock WhatsApp users so they can message your business number again.
Update business profile	Change fields of the public business profile.

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 numbersuserslistRequired: The phone numbers to block, with country code, up to 1000.
Business phone numberphone_number_idtext: Which of your business numbers to use. Leave empty to use the one saved on the connection.

Outputs

blocked_countnumber
blocked_userslist
failed_countnumber
failed_userslist
phone_number_idtext

Example output

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

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 namenametextRequired: Lowercase letters, digits and underscores; spaces become underscores.
CategorycategorytextRequired: UTILITY for updates about something the customer did (orders, bookings); MARKETING for promotions.One of: UTILITY, MARKETING. Default: UTILITY.
Bodybody_texttextRequired: The message text, up to 1024 characters, such as 'Hi {{1}}, your order {{2}} has shipped.'
Body example valuesbody_exampleslist: One example value per placeholder in the body, in the order they first appear. Meta's reviewers read these.
Language codelanguage_codetext: Such as en_US, en or es. Defaults to en_US.Default: en_US.
Headerheader_texttext: Optional bold header line, up to 60 characters.
Header example valueheader_exampletext: An example value if the header has a placeholder.
Footerfooter_texttext: Optional small grey footer, up to 60 characters.
Quick reply buttonsquick_reply_buttonslist: Up to 10 button labels, each up to 25 characters.

Outputs

templateobject

Example output

{
  "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 nametemplate_nametextRequired: The name of the template to delete.
Template IDtemplate_idtext: Optionally, the id of one language version, to delete only that one.

Outputs

all_languagestrue/false
deletedtrue/false
template_idtext
template_nametext

Example output

{
  "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 IDtemplate_idtextRequired: The template's numeric id, as List message templates or Create a message template returns it.

Outputs

templateobject

Example output

{
  "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 numberphone_number_idtext: Which of your business numbers to use. Leave empty to use the one saved on the connection.

Outputs

phone_numberobject

Example output

{
  "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 numberphone_number_idtext: Which of your business numbers to use. Leave empty to use the one saved on the connection.

Outputs

business_profileobject
phone_number_idtext

Example output

{
  "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

Namenametext: Only return templates with this name.
Statusstatustext: Only return templates in this status.One of: APPROVED, PENDING, REJECTED, PAUSED, DISABLED, IN_APPEAL, LIMIT_EXCEEDED, ARCHIVED, PENDING_DELETION, DELETED.
Maximum resultsmax_resultsnumber: How many rows to return (1-500). Defaults to 25.From 1 to 500. Default: 25.

Outputs

countnumber: How many were returned.
templateslist

Example output

{
  "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 resultsmax_resultsnumber: How many rows to return (1-500). Defaults to 25.From 1 to 500. Default: 25.

Outputs

countnumber: How many were returned.
phone_numberslist

Example output

{
  "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

TototextRequired: 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 IDmessage_idtextRequired: The wamid.… id of the message to react to.
EmojiemojitextRequired: The emoji to react with, such as 👍.
Business phone numberphone_number_idtext: Which of your business numbers to use. Leave empty to use the one saved on the connection.

Outputs

message_idtext
message_statustext
recipient_wa_idtext
totext

Example output

{
  "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

TototextRequired: 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 URLmedia_urltext: A public http(s) link to the file for WhatsApp to download. Give this or a media ID.
Media IDmedia_idtext: The id of media already uploaded to WhatsApp, instead of a URL. Uploaded media ids expire after 30 days.
Captioncaptiontext: Optional caption, up to 1024 characters.
File namefilenametext: The name shown to the recipient, with its extension, such as invoice.pdf.
Reply to message IDreply_to_message_idtext: Optionally quote an earlier message (its wamid.… id) so this one shows as a reply to it.
Business phone numberphone_number_idtext: Which of your business numbers to use. Leave empty to use the one saved on the connection.

Outputs

message_idtext
message_statustext
recipient_wa_idtext
totext

Example output

{
  "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

TototextRequired: 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.
MessagebodytextRequired: The message text, up to 4096 characters.
Button labelbutton_labeltextRequired: The label of the button that opens the list, up to 20 characters.
OptionsrowslistRequired: Up to 10 options. Each is a title (up to 24 characters), optionally followed by ' | ' and a description (up to 72).
List headingsection_titletext: Heading above the options, up to 24 characters. Defaults to the button label.
Headerheader_texttext: Optional bold header line, up to 60 characters.
Footerfooter_texttext: Optional small grey footer, up to 60 characters.
Reply to message IDreply_to_message_idtext: Optionally quote an earlier message (its wamid.… id) so this one shows as a reply to it.
Business phone numberphone_number_idtext: Which of your business numbers to use. Leave empty to use the one saved on the connection.

Outputs

message_idtext
message_statustext
recipient_wa_idtext
totext

Example output

{
  "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

TototextRequired: 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.
LatitudelatitudenumberRequired: Latitude in decimal degrees, -90 to 90.From -90 to 90.
LongitudelongitudenumberRequired: Longitude in decimal degrees, -180 to 180.From -180 to 180.
Place namenametext: Optional name shown above the pin.
Addressaddresstext: Optional street address shown under the name.
Reply to message IDreply_to_message_idtext: Optionally quote an earlier message (its wamid.… id) so this one shows as a reply to it.
Business phone numberphone_number_idtext: Which of your business numbers to use. Leave empty to use the one saved on the connection.

Outputs

message_idtext
message_statustext
recipient_wa_idtext
totext

Example output

{
  "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

TototextRequired: 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 nametemplate_nametextRequired: The template's name, as List message templates shows it.
Language codelanguage_codetext: The template's language code, such as en_US, en or es. Defaults to en_US.Default: en_US.
Header valueheader_parametertext: The value for the placeholder in the template's text header, if it has one.
Body valuesbody_parameterslist: One value per {{1}}, {{2}}, ... placeholder in the template body, in order.
Named body valuesnamed_body_parametersobject: For a template with named placeholders such as {{first_name}}: each placeholder name and its value.
Components (advanced)componentslist: The raw template components JSON, for button or media-header parameters. Use instead of the value fields above.
Reply to message IDreply_to_message_idtext: Optionally quote an earlier message (its wamid.… id) so this one shows as a reply to it.
Business phone numberphone_number_idtext: Which of your business numbers to use. Leave empty to use the one saved on the connection.

Outputs

message_idtext
message_statustext
recipient_wa_idtext
totext

Example output

{
  "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

TototextRequired: 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.
MessagebodytextRequired: The text to send, up to 4096 characters.
Show link previewpreview_urltrue/false: Show a preview of the first link in the message.Default: false.
Reply to message IDreply_to_message_idtext: Optionally quote an earlier message (its wamid.… id) so this one shows as a reply to it.
Business phone numberphone_number_idtext: Which of your business numbers to use. Leave empty to use the one saved on the connection.

Outputs

message_idtext
message_statustext
recipient_wa_idtext
totext

Example output

{
  "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

TototextRequired: 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 URLmedia_urltext: A public http(s) link to the file for WhatsApp to download. Give this or a media ID.
Media IDmedia_idtext: The id of media already uploaded to WhatsApp, instead of a URL. Uploaded media ids expire after 30 days.
Captioncaptiontext: Optional caption, up to 1024 characters.
Reply to message IDreply_to_message_idtext: Optionally quote an earlier message (its wamid.… id) so this one shows as a reply to it.
Business phone numberphone_number_idtext: Which of your business numbers to use. Leave empty to use the one saved on the connection.

Outputs

message_idtext
message_statustext
recipient_wa_idtext
totext

Example output

{
  "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

TototextRequired: 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 URLmedia_urltext: A public http(s) link to the file for WhatsApp to download. Give this or a media ID.
Media IDmedia_idtext: The id of media already uploaded to WhatsApp, instead of a URL. Uploaded media ids expire after 30 days.
Captioncaptiontext: Optional caption, up to 1024 characters.
Reply to message IDreply_to_message_idtext: Optionally quote an earlier message (its wamid.… id) so this one shows as a reply to it.
Business phone numberphone_number_idtext: Which of your business numbers to use. Leave empty to use the one saved on the connection.

Outputs

message_idtext
message_statustext
recipient_wa_idtext
totext

Example output

{
  "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

TototextRequired: 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.
MessagebodytextRequired: The message text, up to 1024 characters.
Button titlesbuttonslistRequired: One to three button titles, each up to 20 characters and unique.
Headerheader_texttext: Optional bold header line, up to 60 characters.
Footerfooter_texttext: Optional small grey footer, up to 60 characters.
Reply to message IDreply_to_message_idtext: Optionally quote an earlier message (its wamid.… id) so this one shows as a reply to it.
Business phone numberphone_number_idtext: Which of your business numbers to use. Leave empty to use the one saved on the connection.

Outputs

message_idtext
message_statustext
recipient_wa_idtext
totext

Example output

{
  "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 numbersuserslistRequired: The phone numbers to unblock, with country code, up to 1000.
Business phone numberphone_number_idtext: Which of your business numbers to use. Leave empty to use the one saved on the connection.

Outputs

failed_countnumber
failed_userslist
phone_number_idtext
unblocked_countnumber
unblocked_userslist

Example output

{
  "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

Aboutabouttext: Short status text, up to 139 characters.
Descriptiondescriptiontext: Business description, up to 256 characters.
Addressaddresstext: Up to 256 characters.
Emailemailtext: Contact email address.
Websiteswebsiteslist: Up to 2 http(s) URLs. Replaces the current list.
Industryverticaltext: The business's industry.One of: OTHER, AUTO, BEAUTY, APPAREL, EDU, ENTERTAIN, EVENT_PLAN, FINANCE, GROCERY, GOVT, and 11 more.
Business phone numberphone_number_idtext: Which of your business numbers to use. Leave empty to use the one saved on the connection.

Outputs

phone_number_idtext
updatedtrue/false
updated_fieldslist

Example output

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

ActionsCopy Anchor Link

Block usersCopy Anchor Link

Inputs

Outputs

Create a message templateCopy Anchor Link

Inputs

Outputs

Delete a message templateCopy Anchor Link

Inputs

Outputs

Get a message templateCopy Anchor Link

Inputs

Outputs

Get a phone numberCopy Anchor Link

Inputs

Outputs

Get business profileCopy Anchor Link

Inputs

Outputs

List message templatesCopy Anchor Link

Inputs

Outputs

List phone numbersCopy Anchor Link

Inputs

Outputs

React to a messageCopy Anchor Link

Inputs

Outputs

Send a documentCopy Anchor Link

Inputs

Outputs

Send a list messageCopy Anchor Link

Inputs

Outputs

Send a locationCopy Anchor Link

Inputs

Outputs

Send a template messageCopy Anchor Link

Inputs

Outputs

Send a text messageCopy Anchor Link

Inputs

Outputs

Send a videoCopy Anchor Link

Inputs

Outputs

Send an imageCopy Anchor Link

Inputs

Outputs

Send reply buttonsCopy Anchor Link

Inputs

Outputs

Unblock usersCopy Anchor Link

Inputs

Outputs

Update business profileCopy Anchor Link

Inputs

Outputs

On this page

Actions

Block users

Create a message template

Delete a message template

Get a message template

Get a phone number

Get business profile

List message templates

List phone numbers

React to a message

Send a document

Send a list message

Send a location

Send a template message

Send a text message

Send a video

Send an image

Send reply buttons

Unblock users

Update business profile