WhatsApp Specification

This is a brief overview of building a bot in Whatsapp (through Facebook) using the ‘Automate’ feature in our dashboard.This document explains the various components supported in our dashboard and how they will render/work in the platform, as well as any limitations.

Common Glossary :

With Click-to-WhatsApp advertising, you can add a “Send Message” button to your ads on Facebook or Instagram that opens a conversation in WhatsApp. This way, customers can start a WhatsApp chat with your company by clicking on the button in your ad.

The ads are not much different from other ads you can run on Facebook or Instagram. Only the call-to-action button is different. It says “Send Message” and opens not a landing page, but WhatsApp App or WhatsApp Web.

This is well suited, for example, when orders or appointments are to be coordinated, a consultation is to be started directly, or you want to conduct simple surveys or lead generation via chatbot.

User Experience :

Supported Message Components :

Text, Image, Video, File, Audio, Gallery, Stickers

Complex message components (buttons, galleries) and how they are rendered on the platform:

Notes :

1. Videos applicable.
2. Audios applicable.
3. No GIFs applicable.
4. Stickers applicable.

WhatsApp supports sending and receiving images, audio, PDF files, stickers and video. The following formats are currently supported:

• Images: JPG, JPEG, PNG, WEBP*
• Audio: OGG**, AMR, 3GP, AAC, MPEG
• Documents: PDF, DOC, DOCX, PPTX, XLSX
• Video: MP4 (with H.264 video codec and AAC audio), HEIC
• Static Stickers: WEBP format (512 x 512 pixels, transparent background, file size less than 100 KB)
• Animated Stickers: APNG format (512 x 512 pixels, file size less than 500 KB, up to 3 seconds with a looping animation)
• Contacts: vCard (.vcf)
• The recommended aspect ratio for images is 1.91:1

  Whatsapp Chatbot Build Specification
  	Character Limit	Type/Size	Type/Size
  Image	<5MB	N.A	500*500 (Square)
  Video	<15MB	N.A	N.A
  Audio	N.A	N.A	<5MB
  Stickers (Animated)	N.A	N.A	<500KB
  Stickers (Static)	N.A	N.A	<100KB

Quick Replies:

• Quick Replies in WA are rendered as an ‘interactive list’ with clickable options.
• Generally, we split the QRs into a separate message that is rendered as text plus a button label. The actual QRs can be viewed when the user taps on the button label. See examples in row 2 and 3 in the table above.
• These 2 fields (text and button label) have default values “Choose an Option” and “Options:” respectively (See row 3 example in table).

User Experience :

Please note : Quick Reply Limits:

NOTE: Only go-to quick replies are allowed (no location or phoneNumber QRs)

Button Types:

• Goto Buttons: All the clickable buttons shown in the examples in the table above are “goto buttons”. This is the only button type that is directly supported by Whatsapp’s platform and can actually render as a button.
•  Url Buttons: Url buttons can be created, but they will be rendered as part of the original text message in the format <label>:<url> They will be appended to the end of the text message, with each ‘url’ button’ on a new line. For text messages, you can use these with or without goto buttons, and for galleries, only in combination with goto buttons (see gallery rules)

User Experience :

In these examples the url button is rendered below the text as part of the same message. The label is bolded; the url follows. Any goto buttons are rendered below that.

Button Limits:

Stickers: 

Currently, our WhatsApp chatbots don’t natively support sending stickers directly through the 'Automate' feature. However, it’s technically possible to send stickers via a custom message flow by manually inputting the JSON message format in the bot builder. For received stickers, WhatsApp provides a sticker_id in the webhook and stores the sticker URL as an ImageAttachment, which allows us to handle these as standard images. Stickers can be sent in .webp format, provided they stay within WhatsApp's 500KB file size limit. 

Gallery :

The generic gallery or template is a simple structured message that includes a title, subtitle, image, and up to three buttons. You may also specify adefault_actionobject that sets a URL that will be opened in the Messenger webview when the template is tapped.

We can create multiple structured message just like above linked with each other which will be presented to user in carousel format and user can scroll from left to right.

Gallery Limits :

• A gallery message must always have a title. Image and subtitle are supported but optional.
• A Gallery message must have at least one Goto button (and max 3); otherwise, Whatsapp does not allow it. 
• If you want to send an image+text and no goto buttons, don’t use gallery. Create two separate messages (image and text) one after the other.
• Similarly, if you want to use only url button(s) and no Goto buttons , don’t use gallery. Create two separate messages (image and text) and add the url buttons to the text message.
• See above section for button limits (basically, 3 buttons max, and 20 characters each)
• Gallery messages can only have one gallery item per message. If separate items are needed, create separate gallery messages. 
• A gallery message can have quick replies as well (it will render the same as QR example above). See ‘Quick Reply Rules/Limits’ section for limits.

Urls in Text:

• By default urls in WhatsApp text messages do not have the preview option. However you can use the platformOptions field “preview_url” for a text message, to ensure the url preview shows up:

• The preview is clickable so it may be an easier user experience than having to click the url.
• This option only exists for text messages. Url in galleries for eg. cannot be previewed.
• If there are multiple links in a text message, and ‘preview_url’ is set, the *first* url will be previewed, and the others will not:

Only the first url in each message shows up in the preview. In the last message, preview_url is not set (default).