This guide is oriented to teach you about our API-tools and what you can do with Dynamic Block and External Request. Ideally, after this guide you will have a new level of understanding for these tools and will be able to resolve any problems you might encounter.
It's also important to understand that DevTools are not similar to other instruments in Manychat. When Growth Tools and Flow Builder were created by our hands, DevTools are similar to those API-instruments that are used all around Internet.
To use them, you need to understand the basics of programming, client-server connection, API usage and API-requests structure. We'll cover all of them below.
To troubleshoot them, you need to understand all the same things and remember that problems with them are not connected to Manychat systems by itself — those are the problems that you would find in any other similar instrument in any other service.
1. What is API (Application programming interface)?
API is a method of interaction of different apps or inside a single app. API is the base of our (Manychat's) interaction with Facebook. There's great documentation on API by Facebook that you can refer to for more info.
API is used to connect with the application from outside and change/modify/send something within it. The base of API is a set of methods. The interface is characterized by methods.
2. What are nodes?
Flows consist of nodes. There's a content node (send message node). It consists of blocks. This node is what we use for sending messages to MC contacts. We disassemble the nodes into pieces, change them into the format understandable to Facebook and send to Facebook through API.
3. What is a Dynamic Node?
It's a process when Manychat interrupts the flow processing, goes to other actions (like an outside server request, some action, etc.) and then gets back to the flow.
4. Request consists of
1. Method or request type (GET/POST/etc),
2. link,
3. optionally - header (including API-keys and authorization),
4. optionally - body (with the content inside) if it's POST request type.
There are two things that complete the format of data in the request:
1. Protocol version that we use (currently it's v2).
2. Content: messages, actions, Quick Replies, etc. This is the exact same way as MC's content node looks. MC supports only the actions available in MC. Here they are as examples.
The fallback option activates in case of the wrong server response in Dynamic Block — usually when the server returns an error. If an admin chooses some content in the Fallback, this content will be delivered to those contacts for whom the request failed.
If there's no Fallback and the request fails, then the rest of the flow will not be processed and everything will stop. We recommend using Fallback to notify users that something went wrong on the server but not to build the flow logic on it: Fallback is used in exceptional situations.
5. What is the JSON path?
It's a protocol the format of which is used to extract the reply from an external system and record it in Custom Field: the server returns a response that consists of properties and their values.
Response mapping allows you to save some of the values to Custom fields by entering JSON Path to those values.
All of our integrations (Hubspot, ConvertKit) and Facebook itself uses it.
6. How are our Public API is used?
It helps to change the state of contacts at any moment and send them messages — basically, it lets you perform certain actions from outside Manychat. It serves for external events which Manychat doesn't know about and about which it has to notify the contacts.
For example, you have a delivery service. The tracking info of the product has updated and you know whose order this is. You call the method for this specific contact to notify them, and they receive the message.
7. What are the POST and GET methods?
POST method changes contact's data, for example with "Set Custom Field", "Send Message", "Set Bot Field". POST method is also used to pass parameters to the server that are needed to perform certain actions.
Let's take the "setCustomField" API as an example — if you want to set a Custom Field to a specific value for a specific contact, you need to let the server know the contact's ID, the field's name, and the value you want it to set to.
GET method is used to obtain the contact's or the page's info through "Get user", "Get Bot Field", etc. requests. In requests like that, we wait for a request from the external server right away. GET request doesn't have a Body.
A more simple example: GET will find and return the value of Custom Field, POST will change or send the value of Custom Field somewhere.
"SendContent" method request accepts incoming messages in the same JSON format that is used for Dynamic Block.
Note: POST and GET methods can be used for similar actions and requests, but it's commonly agreed that GET gets the data from somewhere and POST modifies/sends data.
8. What Dynamic Block does?
The most basic purpose of the Dynamic Block is to go to the outside server, get the JSON-code there, transform it into the message and send this message to the user.
Dynamic Block can be used for triggering our API, but it's not its main purpose, and we do not guarantee that will work correctly and our API may not return anything to Dynamic Block. Almost all requests set this way may be duplicated through the native internal interface.
An important note about using Node_Buttons: if Dynamic Block tries to reach our Public API with the code that includes the "Go To Node" button/quick reply, it will not work. Dynamic Block works inside the context of the Flow, but when it's triggering Public API, it goes out of that context and Flow will not be found.
9. What External Request does?
The most basic goal of the External Request is to go to the outside server and
1. Save some data there;
2. Change data there;
3. Get some data there and return it to Manychat with Request Mapping.
4. Some or all of the above.
External Request can also be used to trigger our Public API with some pre-defined values inside. For example, to send the value of the Custom Field from one user to another within one bot.
Example of the notification.
10. What is API Key?
It's a code used to identify the user, developer, or calling program for a website. Manychat provides API Key (PRO-feature) to use with the Account Public API. Public API Key can be found in Settings ⇒ API.
There is also a Profile Public API that's used for connection to non-bot-specific things like Templates. It requires a different key that can be found here.
Troubleshooting
Specific errors and setup advice will be covered below, here we will elaborate the introduction and dig further into the troubleshooting.
1. If you don't know what's happening, google the error.
Not joking: you will often find the solution at Stack Overflow forums or at any programming website, including Facebook Support forums; Remember that DevTools errors are not unique to Manychat: they are common for all tools like this. Here's the list of common error status codes of HTTP protocol for the orientation.
2. It's strongly recommended to familiarize yourself with our available API requests and JSON code examples.
Those two links are the answer to every question about the possibilities of our Public API. If you cannot see a method that you are looking for, then there isn't a method like this. But you can post a feature request here.
3. You may need Jsonlint to check that there's nothing wrong with the JSON code that our checker might have missed, but that happens rarely. Remember that you might need to disable the "Encode to JSON" checkbox and there is no need to encase inserted Custom Fields into "".
What is the "Encode to JSON" checkbox?
All websites have a certain protocol for accepting requests. Most of them have tons of flags, filters, and decoders that will transfer the JSON code sent from our side to something that the website can understand. Some of them accept only strict JSON code. Encode to JSON allows you to transform value in the fields into JSON — that is also required when you are having only variables in the Response Body, like with {{Full Subscriber Data}}.
4. This website will allow you to check and quickly test any API request.
5. Links that will help you to resolve any JSON path (Request Mapping) question:
- JSON formatter will help you to format the JSON string into more code easy to read and understand.
- This JSON path will tell you all about JSON path commands, their correct formatting and will provide some examples.
- This website will help you to quickly test a specific JSON path vs. the given JSON code.
Tips and limits:
1. If you want to see how Dynamic Block works with a message from an external server, you can create your own in a matter of minutes — follow the steps in this article.
2. You can also test an API call (to Manychat or the customer's service) in your own MC account.
If it's a POST method, you can edit the request body in your account until you find a working solution.
If it's a call to Manychat API, you will need your own API token in the header, and if it's the customer's service that requires authorization, use the same headers that the customer set in their dev tool.
3. If the customer's server doesn't require authorization and you want to see what response it returns in a new tab, you can install a Google Chrome extension like JSON Formatter to see it structured in lines:
4. You can also copy the response from the tab or the dev tool after testing the request and use an online JSON formatter like this one to get it structured in lines:
It will also let you see what certain brackets belong to in the code.
5. Play around with our dev tools as much as you can to understand how they work better — try creating requests that would do the same in the MC interface, like send a message, set custom field, etc.
Things you should know:
1. Request URL’s length is limited to 2,000 symbols.
2. If you populate a CUF inside the contact's card, the limit is 4,000 characters. But if you save the value from the contact's message in Messenger with User Input, the limit is about 20,000 — it's the character limit for a message in Messenger. For API and Bot fields, there is no actual limit.
3. Timeout is limited to 10 seconds. It cannot be changed.
4. "https://" in request address is necessary in the Request URL box, even if there is a field that already contains that.
5. Request URL supports "https" only.
6. It’s not possible to map the error message if the returned code is not 200 OK and somehow react to each specific error.
7. It’s not possible to map the response values when testing the request — it’s only successful when you test the dev tool as a contact or preview the Flow.
8. It's only possible to map the JSON code, XML or anything like that. Other codes can be sent as a text string inside the JSON code at best, and it's only a bad workaround.
9. "\n" lets you to add line breaks to your message inside "content" > "messages".
Setup examples
1. This Flow will help to demonstrate how you can send a notification to the non-admin user of your bot.
2. This Flow demonstrates how you can launch a random number generator.
3. You can get the current contact's status by using this API method. You need field status in data object. Active contact has status = active.