Skip to main content

WhatsApp Cloud API

Pro PlusEvents Manager ConnectConnect is an add-on included in the Pro Plus plan, with its own license. You also need a Meta business portfolio and a WhatsApp Business Account, and Meta bills WhatsApp messages separately.

This transport talks to WhatsApp directly through Meta's Cloud API, with no other provider in between. Booking notifications and reminders are sent as message templates you create and have approved in WhatsApp Manager. When a customer replies, Connect answers with buttons and lists that let them view, RSVP to and cancel their bookings.

If you would rather send WhatsApp messages through a Twilio account, see Twilio instead.

Before you start
  • Turn on international phone numbers. WhatsApp replies are matched to bookings by the exact stored number. See Phone numbers and consent.
  • Your site must be reachable at a public HTTPS address, so Meta can call its webhook.
  • Have a phone number for the business that isn't in use in the WhatsApp or WhatsApp Business phone apps. Use a dedicated number: every message sent to it is answered automatically by Connect.

What to set up at Meta​

Meta's dashboards change often. This list names what you need, and Meta's Cloud API get started guide walks through the screens.

You needWhat it is
A Meta business portfolioThe business account that owns everything else. Meta may ask you to verify the business before raising your sending limits.
A Meta app with the WhatsApp productCreated at developers.facebook.com. Adding WhatsApp to the app creates or links a WhatsApp Business Account and gives you a test number.
A registered phone numberAdded to the WhatsApp Business Account. Meta gives it a Phone number ID, a long number that is not the phone number itself.
The App SecretShown in the app's basic settings.
A permanent access tokenThe token on the API setup screen is temporary. For a live site, create a system user in your business settings and generate a token for it with the whatsapp_business_messaging and whatsapp_business_management permissions.
Approved message templatesCreated in WhatsApp Manager. See Message templates.

Enter your details in Connect​

  1. Go to Events then Settings then Connect and open the WhatsApp box under Connection Settings.

  2. Tick Enable WhatsApp.

  3. Fill in the four fields described below.

    The credentials at the top of the WhatsApp box. App Secret and Access Token hide what you type.

  4. Open the Twilio box and tick Enable Twilio as well, leaving its fields empty if you don't use Twilio. See the caution below.

  5. Click Save Changes (All).

FieldWhat to enter
Enable WhatsAppThe switch for this transport. Tick it.
Phone NumberYour WhatsApp business number, for example +1 555 010 0100. It is kept for reference.
Phone Number IDThe ID Meta assigned to that number. This is what Connect sends from.
App SecretYour app's secret. Connect uses it to check that incoming webhooks are from Meta, and it is also the verify token you give Meta in the next section.
Access TokenThe permanent token for your system user.
Enable Twilio too in Connect 1.0.2

In Connect 1.0.2 the WhatsApp Cloud API code is loaded outside wp-admin only when the Enable Twilio switch is on. Without it, the webhook address doesn't exist (so Meta can't verify it and replies go unanswered), reminders aren't sent, and bookings confirmed by an online payment get no message. Ticking Enable Twilio with empty Twilio fields is enough.

Verify the webhook​

Inside the WhatsApp box, Connect prints its callback address:

Your webhook Callback URL is - https://example.com/wp-json/events-manager/v1/connect/whatsapp/webhook, use your App Secret as the "verify token".

  1. Save your Connect settings first. Verification compares against the saved App Secret.

  2. In your Meta app, open the WhatsApp configuration page where the webhook is set.

  3. Paste the address from your own settings screen as the Callback URL.

  4. Paste your App Secret as the Verify token. It must be identical to the value in Connect's App Secret field.

  5. Confirm. Meta calls the address straight away, and Connect answers if the token matches.

  6. Subscribe the webhook to the messages field. Without it Meta sends nothing when customers reply.

After verification, Connect accepts only requests that Meta has signed with your App Secret. Unsigned or wrongly signed requests are ignored. Delivery and read receipts from Meta are acknowledged and not used.

Meta's own steps are in its webhook setup guide.

Message templates​

WhatsApp only lets a business start a conversation with a template that Meta has approved. Connect does not create, download or check templates. You build each one in WhatsApp Manager, wait for approval, and then type its name into Connect.

There are no fixed template names. You need one template for each message you want to send:

MessageSuggested template name
Booking confirmedbooking_confirmed
Booking pendingbooking_pending
Booking canceledbooking_canceled
Booking rejectedbooking_rejected
Reminderbooking_reminder

Template language​

Connect sends each template with a language code worked out from your site language, and Meta refuses the message if the template doesn't exist in that language. The code Connect will use is printed in the help text under Test WhatsApp in the WhatsApp box.

Site languageCode sentCreate the template as
Any English localeenEnglish (not English (US) or English (UK))
A regional language Meta lists, such as pt_BR, es_ES, es_MX or zh_CNThe same codeThat regional language
Other languages, such as German or FrenchThe two-letter code, such as de or frThat language
A language Meta doesn't offerenEnglish

Build a template Connect can fill​

Connect 1.0.2 sends a header value, a body value and a value for the first button with every notification, including when you leave one of its boxes empty. Meta rejects a message whose values don't match the template, so build every template with all three:

  • a text header containing one variable,
  • a body with at least one variable,
  • at least one button that takes a value: a quick-reply button, or a URL button with a variable in its address.

A worked example for the confirmed status:

PartIn WhatsApp Manager
CategoryUtility
Header (text)Your {{1}} booking
BodyHi {{1}}, we have reserved {{2}} spaces for you on {{3}}. Reply here to manage your booking.
Button 1 (quick reply)View booking
Button 2 (quick reply)Unsubscribe

Enter the template in Connect​

Open the WhatsApp box under Booking Status Notifications, tick Enable WhatsApp, and fill in the fields under the status heading.

Each status has a template name and three boxes of variables.

FieldWhat to enterFor the example
Template NameThe template's name exactly as it appears in WhatsApp Manager. Leave it empty to send nothing for this status.booking_confirmed
Header VariablesOne line for the header.#_EVENTNAME
Body VariablesOne line per body variable, in order.#_BOOKINGNAME, #_BOOKINGSPACES and #_EVENTDATES on three lines
Button VariablesOne line per button, in the order the buttons appear.booking-#_BOOKING_UUID and opt-out on two lines

The help text under Template Name refers to Twilio's Content Template Builder. That is a leftover from the Twilio settings: enter the name from WhatsApp Manager.

Each line can contain any booking, event or location placeholder. Some lines can also start with a type and a | character:

BoxLineResult
HeaderText and placeholdersFills a text header. WhatsApp limits a text header to 60 characters once filled.
HeaderlocationSends the event's location as a map pin. For templates with a location header.
Headertickets or invoiceAttaches the booking's PDF tickets or invoice. For templates with a document header. Needs Events Manager Pro.
Headerimage|https://example.com/poster.jpgFills an image header from a URL. video| and document| work the same way. The URL can contain placeholders.
BodyText and placeholdersFills the next body variable.
Bodydate_time|#_EVENTDATESFills the variable as a date and time value.
Buttonurl|#_BOOKINGIDFills the variable part of a URL button.
ButtonAnything elseBecomes the hidden value WhatsApp sends back when the customer taps a quick-reply button.

Make quick-reply buttons do something​

When a customer taps a quick-reply button, WhatsApp sends the button's hidden value to your webhook, and Connect treats it as a command. Useful values for Button Variables:

LineWhen tapped
booking-#_BOOKING_UUIDShows this booking with its options list.
bookingsLists the customer's upcoming bookings.
opt-outStops notifications for this customer.
#_BOOKING_X_COMMAND{rsvp,1}Records an RSVP of Yes. Use 0 for No and 2 for Maybe.
#_BOOKING_X_COMMAND{cancel}Cancels the booking, if cancellation is allowed.
#_BOOKING_X_COMMAND{tickets} or #_BOOKING_X_COMMAND{invoice}Sends the PDF. Needs Events Manager Pro.

The #_BOOKING_X_COMMAND values contain a security code that is valid for up to 24 hours. Tapped later, they show the booking with a fresh set of options instead of acting straight away.

The 24-hour window​

WhatsApp allows free-form messages only within 24 hours of the customer's last message to you. Outside that window, only templates are delivered. Connect doesn't track the window. It works like this:

  • Notifications and reminders are sent as templates. Connect treats Template Name as a template when it is a single word made of letters, digits and underscores. If you type a sentence there instead, it is sent as plain text, which WhatsApp delivers only inside the window.
  • Replies to customers are free-form messages with buttons or lists. They are always inside the window, because they answer a message the customer has sent.

Buttons, lists and reply texts​

When a customer writes to your number, Connect replies with interactive messages:

SituationWhat Connect sends
Greeting or unrecognized textA text with up to three reply buttons: View Bookings, Check Again and Unsubscribe
List of bookingsA list message opened with a View Bookings button, one row per booking
One bookingThe booking's details and an Options list with RSVP, booking and navigation actions
Ticket or invoiceA PDF document with a caption
LocationA map pin

Every text and button label is editable in the lower part of the WhatsApp box, under Reply Texts, Bookings, Buttons and List Headings. Button labels are cut to 20 characters and list headers to 60, which are WhatsApp's limits. The full flow is described in Customer commands.

Test your setup​

The test button in Connect 1.0.2

The Send Test WhatsApp button in the WhatsApp box doesn't send anything in Connect 1.0.2. Use the two tests below instead.

Test the webhook and replies​

  1. Make sure your own mobile number is on your WordPress user profile, or on a booking, in international format.
  2. From that phone, send any message, such as hello, to your WhatsApp business number.
  3. Within a few seconds you should get the greeting, beginning Hello! This is the Events Management service for and your site address, with the reply buttons.

If the reply is We cannot find any accounts or bookings registered to this contact method., the webhook works but your number didn't match any user or booking. No reply at all points to the webhook: see Troubleshooting.

Test a notification​

  1. Set up the template for the Confirmed status (or Pending, if your bookings need approval) as described above.
  2. Tick Enable booking status notifications and save.
  3. As a visitor, book a place on one of your events using your own WhatsApp number.
  4. The template should arrive on your phone with the event name and date filled in.

While your app uses Meta's test number, it can only send to recipient numbers you have added on the app's API setup screen.