The API Request Node
Calls an external HTTP endpoint, so a workflow can look something up, create a record, or trigger anything you already run elsewhere. A common sequence is an API Request, a Decision on the result, then a different Message on each branch.
Set the Method, the URL and the Headers#
Everything on the panel is optional except Method and URL.
| Setting | What to put in it |
|---|---|
| Method | GET, POST, PUT or DELETE |
| URL | The address, with {{variables}} interpolated before the request is sent, so https://api.example.com/orders/{{Order_Form.number}} carries a value from the conversation |
| Headers (JSON) | Where an API key goes, written as JSON. The editor formats and validates it |
The URL must be a public web address that starts with https:// or http://. Chatleadr refuses an address on a private network, such as localhost or 192.168.1.10, and follows a redirect only to another public address. A refused address leaves by the Error port, and the execution log says why.
Send a Payload With the Request#
A body is sent only for the methods that take one, and Payload Type chooses the encoding.
| Payload Type | What you fill in | Reach for it when |
|---|---|---|
| JSON (Base64 Encodes Files) | JSON Body Payload, which accepts {{variables}} and which the editor formats and validates | The endpoint takes JSON, which is most of them |
| Multipart Form Data | Form Data Fields, a key and a value per row, where a value may be a variable holding a file | The endpoint takes an upload |
Name the Fields You Need From the Response#
Expected Response Type is JSON, XML or Form Data, and it sets the Accept header on the request.
Under Extract Response Variables, each row maps a path in the response to a variable name:
data.user.email ➔ email
data.order.status ➔ statusThat produces <Label>.email and <Label>.status. Extract Headers works the same way, with the header name in place of the path. A node labelled Look up the order also writes Look_up_the_order.status_code, the HTTP status of a request that succeeded, and renaming the node renames every one of them. A request that failed saves nothing at all and leaves by Error, so handle a failure on that port rather than by checking the status. See variables in a workflow.
Connect the Error Port or the Run Ends Silently#
A request that fails, times out or returns an error status leaves by Error. A 404 and a 500 both go that way, so handle them there.
The execution log records the status of every attempt, and the error text when one fails. With nothing mapped, the whole response body is in the run's final state.
Account for What You Send and Who Can Read Your Keys#
Keys go in the headers field, and anyone in the workspace who can open the bot can read them. Editing the workflow is limited to an owner or an admin, but a headers typo quotes part of what you typed into the execution log, and every member who can open the bot reads that. Use a key scoped to what the workflow actually needs rather than an account-wide one.
Common Questions#
Can I Call an Endpoint That Needs OAuth?#
Only where you can supply a token in a header. There is no token refresh step, so an endpoint requiring a short-lived token needs something in front of it that holds the credentials.
What Is the Timeout?#
Each request is given 15 seconds. An endpoint that has not answered by then is abandoned and the node leaves by the Error port. See execution limits.
Can I Send the Whole Conversation?#
Not as a single variable. Send the values you need, named. A transcript is not in workflow state.
How Do I Debug a Failing Call?#
The execution log records the node, the status code and the response. Read the status first: a 401 is the key, a 404 is the URL, and a 400 is usually the body after interpolation left an empty variable in it.
Does a Failed Call Retry?#
No. It takes the Error port once. Build the retry as a loop back into the node where you need one, and remember the 100-step cap.