This guide will teach you about our API tools and what you can do with dynamic blocks and external requests. Ideally, after reading it, you will have a new level of understanding of 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. Whereas triggers and flow builder were created by our hands, DevTools are similar to those API instruments that are used all around the Internet.
To use them, you need to understand the basics of programming, client-server connection, API usage, and API request 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 themselves—those are the problems that you would find in any similar instrument in any other service.
This article will cover the following questions:
- What is an API?
- What are nodes?
- What is a dynamic node?
- Request structure
- What is a JSON path?
- How is our Public API used?
- What are POST and GET methods?
- What does a dynamic block do?
- What does an external request do?
- What is an API Key?
- Troubleshooting
- Tips and limits
- Things you should know
What is an API?
API is the acronym for Application Programming Interface, a method of interaction between different apps or inside a single app. API is the base of our (Manychat's) interaction with Meta. There's great documentation on API by Meta that you can refer to for more information.
API is used to connect with an application from outside and change/modify/send something within it. The base of API is a set of methods, and the interface is characterized by methods.
What are nodes?
Automations consist of nodes. There's a content node (“Send Message” node), which consists of blocks. We use this node to send messages to Manychat contacts. We disassemble the nodes into pieces, change them into a format understandable to Meta, and send them to Meta through API.
What is a dynamic node?
It's a process when Manychat interrupts the automation processing, goes to other actions (like an outside server request, some action, etc.), and then returns to the automation.
Request structure
A request consists of:
- Method or request type (GET/POST/etc)
- Link
- Optionally - Headers (including authorization and API keys)
- Optionally - Body (with the content inside) if it's the POST request type
Two things complete the format of data in the request:
- The protocol version that we use (currently, it's v2)
- Content: messages, actions, quick replies, etc. This is exactly the same way the Manychat content nodes look. Manychat supports only the actions available in Manychat. Here they are as examples.
The fallback option activates in case of a wrong server response in a dynamic block — usually when the server returns an error. If a team member specifies 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 automation 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 automation logic on it. Fallback is used in exceptional situations.
What is a JSON path?
JSON path is a protocol whose format is used to extract a reply from an external system and save it in a custom user 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 user fields by entering the JSON path to those values.
Our integrations (Hubspot, ConvertKit, etc.) and Meta use it.
How is our Public API used?
Our Public API can be used to change the state of contacts at any moment and send them messages— basically, it allows you to perform certain actions from outside Manychat. It serves for external events that Manychat doesn't know about and about which it has to notify the contacts.
For example, you have a delivery service. The product's tracking information has been updated, and you know whose order it is. You call a method for that specific contact to notify them, and they receive a message.
What are POST and GET methods?
The POST method changes account or contact data, for example, with Set Custom Field, Send Content, or Set Bot Field. It is also used to pass parameters to the server to perform certain actions.
Let's take the setCustomField API as an example. If you want to set a custom user field to a specific value for a specific contact, you need to let the server know the contact ID, the field name, and the value you want to set it to.
The GET method obtains account or contact information through Get Info, Get Bot Fields, etc. In requests like that, we wait for a request from the external server immediately. A GET request doesn't have a body.
A more simple example: GET will find and return the value of a custom user field, and POST will change or send the value of the custom user field somewhere.
The SendContent method request accepts messages in the same JSON format used for Dynamic Block.
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 the data.
What does a dynamic block do?
The most basic purpose of the dynamic block is to go to the outside server, get the JSON code there, transform it into a message, and send this message to a contact.
The dynamic block can be used for triggering our API, but that's not its main purpose. We do not guarantee that it will work correctly, and our API may not return anything to the dynamic block. Almost all requests set this way can be created in the native internal interface.
An important note about using node buttons: if a dynamic block tries to reach our Public API with the code that includes a Go To Node button/quick reply, it will not work. Dynamic block works inside the context of automation, but when it triggers the Public API, it goes out of that context, and the automation will not be found.
💡 You can see error and warning logs related to the dynamic block requests in Settings → Logs.
What does an external request do?
The most basic goal of the external request is to go to the outside server and:
- Save some data there
- Change data there
- Get some data there and return it to Manychat with the request mapping
- Some or all of the above
External requests can also be used to trigger our Public API with some pre-defined values inside. For example, to send the value of a custom user field from one contact to another within one bot.
What is an API Key?
API Key is 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 on the introduction and dig further into the troubleshooting.
If you don't know what's happening, look up the error online. You will often find the solution on Stack Overflow forums or any programming website, including Meta 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.
It's strongly recommended to familiarize yourself with our available API requests and JSON code examples.
Those two links answer every question about the possibilities of our Public API. If you cannot see a method you are looking for, then there isn't a method like that. However, you can post a feature request here.
You may need to use JSON Lint or a similar tool to check that the JSON code is correct, which 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 user 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 have only variables in the Request Body, like with {{Full Contact Data}}.
Postman will allow you to check and quickly test any API request.
Links that will help you resolve any JSON path (Request mapping) question:
- JSON formatter will help you format the JSON string into a code that is easy to read and understand
- This JSON path documentation will explain JSON path commands and their correct formatting and provide some examples
- This JSONPath Expression Tester will help you quickly test a specific JSON path with a JSON code
Tips and limits
If you want to see how a 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.
If a server that you’re calling 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:
You can also copy the response from the tab or the DevTool 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.
Things you should know
- The Request URL’s length is limited to 2,000 symbols.
- If you populate a custom user field inside the contact's card, the limit is 4,000 characters. But if you save the value from a contact's message in Messenger with a Data Collection block, the limit is about 20,000 — it's the character limit for a message in Messenger. There is no actual limit for API and bot fields.
- Timeout is limited to 10 seconds. It cannot be changed.
- "https://" in the request address is necessary in the Request URL box, even if a field already contains that.
- The Request URL supports https links only.
- It’s not possible to map an error message if the returned code is not 200 OK and somehow react to each specific error.
- It’s not possible to map the response values when testing the request. It’s only successful when you trigger the DevTool as a contact or preview the automation.
- It's only possible to map a JSON code. Other formats are not supported.