Answer \"where is my order?\"
A worked example: your API, one action, and an agent that stops saying it doesn't know.
"Where is my order" is the single most common message any shop receives, and knowledge alone can never answer it — the answer is in your database, not on your website.
By the end of this you will have an agent that looks the order up and answers, and refuses to do it for a stranger.
1. Build an endpoint that takes an order number
Keep it narrow. This will be called by a model on behalf of a member of the public, so it should do exactly one thing.
app.post("/agent/order-status", express.json(), async (req, res) => {
// Shared secret, checked before anything else.
if (req.get("X-Agent-Secret") !== process.env.AGENT_SECRET) {
return res.status(401).json({ error: "unauthorised" });
}
const { orderNumber, email } = req.body ?? {};
if (!orderNumber || !email) {
return res.status(400).json({ error: "orderNumber and email required" });
}
// BOTH must match. See the warning below — this line is the whole
// security model of this endpoint.
const order = await db.orders.findOne({
number: String(orderNumber).replace(/^#/, ""),
email: String(email).toLowerCase().trim(),
});
if (!order) {
// Deliberately identical whether the order does not exist or the email
// does not match. Anything else tells a stranger which orders are real.
return res.json({ found: false });
}
return res.json({
found: true,
status: order.status,
carrier: order.carrier ?? null,
trackingUrl: order.trackingUrl ?? null,
expected: order.expectedLabel ?? null,
});
});
Warning
Require two facts, not one. An order number alone is guessable — they are usually sequential. Asking for the number and the email on the order means a stranger typing
#10432learns nothing.Return the same
found: falsefor "no such order" and "wrong email". A different response for each is an oracle for which order numbers exist.
2. Add it as an action
On the agent's Actions page, add a custom HTTP action.
| Field | Value |
|---|---|
| Name | order_status |
| Method | POST |
| URL | https://shop.example.com/agent/order-status |
| Header secret | X-Agent-Secret: … |
Describe it in the words the model needs:
Look up a customer's order. Requires BOTH the order number and the email
address on the order. If the customer has given only one, ask for the other
before calling this. Returns found: false when the pair does not match —
say you could not find it and ask them to check both, never say the order
does not exist.
Tip
That last sentence is worth writing. Without it a model will helpfully report "that order doesn't exist", which is both wrong and an information leak.
3. Try it in the Playground
Test all four cases, not just the happy one:
| You say | It should |
|---|---|
| "Where is order 10432?" | Ask for the email on the order |
| Order number + correct email | Give the status |
| Order number + wrong email | Say it could not find it — not that the order exists |
| "Where is my order?" | Ask for both |
4. Ship it
The action works identically on WhatsApp and Telegram — you configured it once, on the agent.
Doing better: skip the questions entirely
If the customer is signed in and verified, your server already knows who they are. Send their customer id along with the request and the agent can list their recent orders without asking anything.
That is the difference between a bot that interrogates people and one that recognises them.
What good looks like
A real exchange
Customer where's my order
Agent Happy to check. What's the order number, and the email address
you used?
Customer 10432, [email protected]
Agent Order #10432 shipped on Monday with BlueDart and is due Tuesday.
Tracking: https://…
