Listicle of things missing from Facebook Messenger Chatbot Platform’s documentation

One of the reasons Chatbots don’t live up to their hype is because it’s ridiculously hard to develop them for Facebook. In case you were developing your own middleware and functions to send and receive messages from the Facebook Messenger Platform, here are some tips you will find pretty useful, but probably couldn’t discover in their rushed and unsystematic documentation (most of these items are in fact documented, but easy to miss).

Note: some of the items on this list might have been updated/changed/removed by Facebook already. Please let me know you can validate any of these concerns, so I can stop whatever I was doing and rush to update all my code I’ve ever wrote for Facebook Messenger Platform.

Designers need to deal with inconsistencies within Facebook’s Messenger platform. View on iOS vs Chrome (desktop) — via Chatbot-Academy
  • If you are using images or URLs for templates from different domains, you will have to whitelist them first, otherwise the Messenger API could refuse to send them.
  • There is a limit for the number of elements and buttons you can add to all the templates. There is also a limit for the length of messages and captions there can be. Upon exceeding these limits, instead of simply having your text trimmed, you will receive an error and the API will refuse to send your message (or at least in some cases). Maximum length of characters are 80 for titles and subtitles (descriptions), while 320 for text messages. You can have 10 items among your generic templates with 3 buttons for each maximum. For quick messages, you can have 11 different buttons but each of them can consist of 20 characters tops.
  • When connecting your Chatbot to a page, you can subscribe to certain events, such as “message_echoes” or “message_reads” and so on. It might be tempting to simply subscribe to each and every one of these options, thinking you could get more data from your user. Don’t do it! You will only increase the number of requests to your server and make debugging harder. If you are still experiencing with the Messenger Platform and wanted to write a simple echo service, you could end up receiving the same message through message_echo and resending it to the user, just to receive it once again, thus creating a Chatbot equivalent of an ever growing hydra.
  • If your server doesn’t respond in a few seconds with a 200 response code, Facebook will attempt to resend the message. If you have implemented something that requires a lot of time to finish running (a search engine Chatbot for example) you can end up DDoS-ing your own server by having the same request sent to it multiple times for not being responsive enough. To work around this, you can check if you have already received the very same message with the exact same timestamp and discard the repeated ones. If your server fails to respond with a 200 code for a longer period of time, Facebook will increase the time interval between repeated messages. After a while, it will unsubscribe you from the webhook and you will have to resubscribe manually. If the App dashboard doesn’t allow you to resubscribe, delete the old webhook and create a new one (you will probably need to generate a new Access Token at this point).
  • If you are responding to Verify Tokens manually, keep in mind that Facebook doesn’t only check these tokens once when you first establish the connection. It will continuously recheck the credentials from time to time so your server should be able to send back the same Verify Token whenever required.
  • Some variables to be sent to the Facebook Messenger API are optional, but can only have one specific value (“messenger_extensions”: true). If you’ve casually added these variables to other JSON objects, because you would rather use the same object for similar calls or god forbid you just wanted to future proof your code, you would get an error, saying there are extra variables in your JSON that shouldn’t be present (without further specifying which ones they are). Why anyone thinks this is a good idea at Facebook is beyond me.
  • You can enable “get started” buttons for you bot. However, you can not change the title of the button, as its caption is based on the user’s language. It is good practice to crawl user data right after this button was pressed and cache it on your server. However, some users’s profile can not be accessed so make sure to handle exceptions and use fallbacks. Remember, you can only get a small amount of information from user’s profiles via Messenger by default. You can also set the greeting message from API or from the Page’s Messaging Settings.
  • You can create a menu for your Chatbot. Although I love the idea behind it, it is worth noting that menus will block the entire text input field on Smartphones. If you want to allow users to still send you text messages, it is probably a better idea UX-wise to turn the confusing and ugly thing off. You can tell how rushed this whole concept is when inspecting the JSON objects for buttons, and you reckon that each and every button you can send, including the menu buttons differs in some way. If you are having trouble with adding a menu, read this article. Sometimes sending a menu delete request will not remove the menu from your Chatbot. In this case, try removing and re-enabling the “get started” button as well.
  • If you are developing an unreleased Chatbot subscribed to a page, page admin’s won’t be able to access it by default. You will have to grant them developer or tester rights at the App’s Roles tab. The difference between a Facebook App and a Facebook Page admin is that users will have to register as an App developer in addition to get access to admin tools.
  • You might think that users can only send text messages and attachments via Messenger. THINK AGAIN. Some versions of Messenger will allow users to change the color and the like button in the conversation, even if they should not be able to do so. This will still send some undocumented events to your Chatbot so rev up those exception handling and logging skills if you want those 200 response codes to be still sent. Did you know there is also a god damn basketball Easter-egg minigame in Messenger? Did you know users can actually play it “against” your Chatbot? Well I sure didn’t!
  • When pressing the “like” button at the bottom right, you are actually sending a “like” sticker. This isn’t the same as the “like” or thumbs up emoji, the (y) text that turns into a “like” emoji or the other stickers you can get from the sticker shop that also contain “like”. So if you want your bot to respond to getting a “like” well good luck handling all of these. However, if you only want to handle “likes” that are triggered by pressing the button on the bottom left, be aware that there are actually 3 different sizes of those and all of them have different sticker IDs! Sounds fun right? But wait, aren’t there only 2 of those, you might ask? A smaller and a bigger “like” button where you get the bigger one by pressing down the button for longer? Surprise! There are actually 3 of them, because there is one that is almost as big as the huge one but slightly smaller! Their sticker IDs are the following: 369239263222822 for the small one, 369239383222810 for the big one and 369239343222814 for the medium one. Or so I hope. Can’t wait until Facebook adds the option to change the “like” button to anything else in the conversation. 👍👍👍
  • Talking of likes, you are going to need at least 25 likes on your Page before you can get a specific username for your Page and for your Chatbot in Messenger.
  • Make sure to use large profile pictures both for your Page and for the APP (1024x1024). You can get a Messenger QR Code via an API call or by using the OLD VERSION OF YOUR PAGE INBOX, going to messages tab, clicking on the small (i) button on the bottom left, under the list of messages and downloading it from the modal window. Easy, isn’t it? I have yet to find such button on the new, improved inbox for Pages though.
  • Once you think you are done with your Chatbot and had it tested by trolls, specialized in giving tricky questions to AIs, you can submit your Chatbot for Approval at the App review tab at your App dashboard. You will be asked to fill in a form describing the basic functionality of the Chatbot and responses for certain keywords. If you don’t have any hard-coded responses for certain keywords you can ignore some parts of the form and explain this in detail. The reviewers will actually read it and accept it as an answer. Soon you will get a few messages from Facebook test users and your Chatbot will be approved if everything goes well. This could take less than 24 hours, which is pretty much one of the the fastest approval processes I have seen on Facebook, so kudos for that! If you also want “pages_messaging_subscriptions” rights, you will need to record a demo of your Chatbot in a scenario where users are given the options to subscribe and unsubscribe from messages sent long after user interaction.

So there you have it. Things I wish I have known before starting development for Facebook Messenger. Hope it helps and saves you time.