Looking things up in your own system

What this does

A customer writes “I need my invoice”. Before anything can be sent, somebody has to answer which invoice — and only your system knows.

A lookup tool points the assistant at one of your own endpoints that returns rows of data, and the assistant reads those rows back to the customer:

I found 5 invoices for you:

1. S5-4-1311 — 1 Aug — 412.50 SAR — unpaid
2. S5-4-1206 — 12 Jul — 180.00 SAR — paid …

Which one would you like?

It is the natural partner to sending documents: the lookup lets the customer choose, the document tool delivers what they chose.

Setting one up

Go to Chatbot → AI Contexts → New, and pick Look something up as the type.

The action

Short name — how the action is identified internally, e.g. my_invoices. Lower-case letters, numbers and underscores.

When should the assistant use this? — what the assistant reads when deciding whether to call it. Be specific about what it is for:

Look up this customer’s own recent invoices. Use it whenever they ask about a bill, a receipt or a payment. Read the list back with the number, the date and the total, and ask which one they mean before sending anything.

What the assistant must supply — optional here, unlike a document tool. Most lookups need no input at all: the customer’s phone number is already known, and that is what scopes the query. Add an input only when the assistant genuinely has a choice to make, such as how many records to return.

The endpoint

API URL — your endpoint, with placeholders:

https://erp.example.com/api/invoices?mobile={{phone}}&limit={{limit}}

Placeholder	Comes from
{{phone}} (or {{phone_number}})	The customer in the conversation. Not something the assistant can choose.
{{limit}} (or {{args.limit}})	An input you declared above, supplied by the assistant.

Headers — where your token goes. Saved encrypted and shown as *** afterwards; leave the *** in place when editing and your saved token is kept.

The answer

Where the records are — the path to the array in your response, e.g. data.invoices. Leave it empty if your endpoint answers with the array itself. A single object is accepted too and treated as one record.

Which fields to show — the heart of the configuration. List the fields the assistant is allowed to see, in the order you want them read out, each with an optional friendlier label:

Field	Shown as
invoice_id	id
invoice_number	number
date	date
total	total
paid	paid

Everything else your endpoint returns is discarded. Nothing outside this list ever reaches the assistant.

How many records — 1 to 20, five by default. A WhatsApp reply is read on a phone; twenty invoices is not a list anyone chooses from.

When there is nothing — your own wording for an empty result, e.g. “No invoices found for this number.” Optional.

Example: invoices from an ERP

Given an endpoint that answers

{
  "ok": true,
  "data": {
    "invoices": [
      { "invoice_id": 1269104, "invoice_number": "S5-4-1311", "date": "2026-08-01",
        "total": 412.5, "paid": false, "internal_note": "…" }
    ],
    "pagination": { "page": 1 }
  }
}

configure:

Field	Value
Short name	my_invoices
API URL	https://erp.example.com/api/invoices?mobile={{phone}}
Headers	{"Authorization": "Bearer …"}
Records are at	data.invoices
Fields	invoice_id → id, invoice_number → number, date, total, paid
How many	5

Pair it with a document tool that fetches one invoice by invoice_id, and the whole conversation works end to end.

What we check before the assistant sees anything

This is the one place where text from your system reaches the assistant, so what comes back is treated as data written by a stranger — never as instructions:

• Only the fields you listed are used. Internal notes, staff comments and anything else your system happens to hold stay where they are. This is the main control: an assistant that read every column would be steerable by anyone who can type into your ERP.
• Values are cleaned. Line breaks, invisible characters and the Unicode direction overrides that make text display as something other than what it says are removed, and each value is capped at 200 characters.
• Objects and lists inside a record are dropped. A lookup returns a table, not a tree.
• The whole answer is capped. Records are dropped from the end until it fits, and the assistant is told how many went, so it offers to narrow the search rather than quietly showing a short list.
• The assistant is told these are records, not instructions, every time.
• Each customer can run at most 20 lookups an hour.
• Internal addresses are refused, redirects are re-checked at every hop, and your token is dropped the moment a redirect crosses to a different host — exactly as for document tools.

تنبيه

If your endpoint answers in a shape we cannot read — the wrong path to the records, or field names that match nothing — the assistant is told the lookup failed, not that the customer has no records. “You have no invoices” is the one answer a misconfiguration must never produce, so it is never given by accident.

Permissions

Creating or editing a lookup tool requires the chatbot settings write permission, because it configures an outbound call carrying your credentials. Ordinary knowledge contexts are unaffected.