API tools in a flow

Let a flow step look up stock, prices, orders or documents in your own system, answer with the real values, and send a document as a file.

Last updated
On this page
On this page

An API tool lets a flow step ask your own system for something (stock, a price, an order, an invoice) and answer the customer with the real value. You add the tool once, then use it on any message, question or condition step. This page shows how to add a tool, use it on a step, and send a document it returns as a file.

Adding an API tool

  1. Open AI Knowledge Hub, then the API tools tile, and choose Add API tool.
  2. Give it a Name and say in What it looks up what it answers.
  3. Under Request, enter the https address. Put {{order_no}}-style variables in the path or query to fill them from what the flow collected. To send the customer’s or the chat’s details, use Insert value (below).
  4. Add any Headers your system needs, such as an API key. Their values are stored encrypted.
  5. Under Save to variables, pick the values later steps need, for example invoice_no ← invoice_id.
  6. Run Test request with sample values. It shows what was Sent and what was Received. Then Save.

Editing an API tool: name, request, saved variables and test

Using the tool on a step

  1. In the flow designer, open the step. Under Tool, set Tool type to API tool and pick it in Select API tool.
  2. The panel lists what it Needs from earlier steps and what it Saves for later steps. Collect the needed variables before this step.
  3. Write the step’s message the way you want the answer to read; the step fills in the real values.

Every tool also saves <tool>_status (ok, error or missing_input) and <tool>_http_code, so a later condition can branch on them. When a request fails or is skipped, the values it saves are emptied, so a later step never shows an earlier answer.

If the request fails What the customer sees Default for
Reply honestly and continue The bot says it couldn’t check right now, never makes up a value, and the flow moves on Tools that look something up (GET)
Hand off to a human The bot says it couldn’t check right now and hands the conversation to your team Tools that send or create something (POST), like an order

A request that gets no answer from your server within 15 seconds counts as failed and follows this setting. The customer’s reply waits for the tool, so a server that answers within a few seconds keeps the chat feeling quick.

The Tool section of a message step with an API tool

Values that can be empty or sent as a list

Every {{value}} in the request must be filled in, or the request is skipped. Under Values in the request, each value has its own ticks:

Tick What it does
Can be empty When the value is blank, N/A, none, null or -, the request still goes out without it: its field is left out of the body, it is left out of the address, or its header is not sent. A value in the address path can’t be left out; move it to the query, like ?ref={{ref}}.
Send as a list (JSON) For a value in the body of a POST request. It is sent as a real list, such as several order lines. Write it without quotes, like "items": {{items}}, and let an AI step write the list. If the value isn’t a valid list, the request is skipped.

Values in the request: note and postcode can be empty, items is sent as a list

Sending the customer’s and the chat’s details

Insert value: the Customer group with Contact ID, Name, Phone, Email and the workspace's contact fields

A request can carry details the platform already knows, such as the customer’s contact ID or the chat number, instead of asking the customer for them.

  1. Click in the address, a header value or the body, where the value should go.
  2. Click Insert value and pick the value. Type in Search values to find one quickly.

The value is added where your cursor was, like {"contactId": "{{contact.id}}"}, and every chat fills it with its real value.

Group Value What it sends
Customer Contact ID The customer’s ID, the number in the address of their contact page
Customer Name, Phone, Email The customer’s name, phone number and email
Customer Your contact fields The customer’s value for that contact field
Chat Chat number The chat’s number, the one your team sees on the chat
Chat Inbox ID The ID of the inbox the chat came in on
Chat Message ID The ID of the customer’s latest message in the chat
Workspace Workspace ID Your workspace’s ID

A detail the customer doesn’t have is sent empty, and the request still goes out.

Note: Pick values from Insert value instead of typing them. A typed name the menu doesn’t offer, like {{contact.ID}}, can’t be saved.

Testing with sample values

Test request with sample boxes for contact.id and conversation.id

Test request isn’t a chat, so it has no customer or chat to take the values from. It lists each value you inserted with its own box.

  1. Type a sample in each box, such as a real contact ID from your system.
  2. Click Test. Sent shows the request with your samples in place.

Nothing you type here is saved. In a chat, the real values are used.

Trying it in the Playground

Test scenario: the contact's name, phone number and email

In the Playground, the values come from the test chat and its Scenario:

Value What the Playground sends
Contact ID The customer you loaded with Load from a conversation. With no customer loaded, the Playground’s own test customer
Name, Phone, Email What you filled in under Contact in the Scenario
Chat number, Message ID The Playground’s own test chat, never the chat you loaded
Inbox ID The inbox in the Scenario, otherwise the test chat’s

So a test run never looks up or changes the real chat you loaded.

Sending a document as a file

When the tool returns a link to a document, such as an invoice or a receipt, a Send message step can send the document itself instead of the link.

  1. Under the API tool, open Send a document from this tool and pick the document’s link. The link the tool brings back is listed first and marked (suggested), like Invoice link (suggested).
  2. The File name fills itself in, like Invoice {invoice_no}.pdf. To add another saved value, click it under Add to the name:, such as + Customer name. You can also type the name yourself. A blank name sends Document.pdf; a name with no extension gets .pdf.
  3. Check the Customer gets: line. It shows the file name the customer will see.

The customer gets the step’s message, then the file. The message never shows the link. If the tool returns no link, no file goes out and the bot says the document isn’t ready yet. We keep a copy (up to 10 MB), so your team can still open it after the link from your system expires.

WhatsApp, Messenger, Instagram, Telegram and web chat receive the file. Email, SMS, TikTok, Line and API inboxes get the link instead.

A Playground reply: the message, then the invoice as a PDF file

Frequently asked questions

Is the contact ID sent as a number?

Yes, it’s the customer’s numeric ID. Inside quotes, like "{{contact.id}}", it arrives as text that holds only digits, so check what your system expects.

Why did a value arrive empty?

The customer doesn’t have that detail, or the request was sent from Test request without a sample in its box.

How long does the tool wait for my server?

Up to 15 seconds for the answer, after up to 5 seconds to connect, and never more than 20 seconds in total. Test request waits the same way. A slower answer counts as a failed request.

Can a request be sent twice?

No. Each request is sent once, including POST requests that create something, so your system never gets the same order or record twice from one step.

What happens when my server is down?

After 3 requests in a row get no answer, the tool pauses for 2 minutes. During the pause, steps that use it don’t wait: they follow If the request fails straight away, then requests start again. Test request still reaches your server during a pause, so you can check it as soon as it’s back. A workspace also runs at most 5 API tool requests at the same time; one more at that moment counts as failed.

How do I show a value from the response in a message?

Under Save to variables, map the response field to a variable, like next_missing ← nextMissing. Then write {next_missing} in a later step’s message.