Actions — let the assistant use your APIs

What an action is

Knowledge answers questions whose answers live in your documents. An action answers questions whose answers live in your systems — “where is my order?”, “what plan am I on?”. You register an HTTP endpoint as a tool; the assistant decides when a customer's question needs it, calls your endpoint server-side with the verified customer identity, and answers from what your endpoint returns.

Actions are read-only in this version: they look things up, they do not change anything. Set them up under Actions in the dashboard (Pro and Scale).

Shopify store? Connect it, no code

If you sell on Shopify, you don't need to build anything. Connect your store on the Actions page and the assistant can start answering your shoppers' order questions — “what are my orders?”, “where is order #1001?” — with live status and tracking.

It answers signed-in shoppers only, and each shopper sees just their own orders. It is read-only: the assistant looks orders up, it never changes anything.

• Connect: Actions → Shopify → enter your store address → approve.
• That's it — order lookups turn on automatically once the store is connected.

1. Define a custom tool

Give the tool a name, a clear description, and the parameters it needs. The description is the most important field: the assistant reads it to decide when to call the tool, so be specific about what it does and when it applies.

• Name: lowercase with underscores, e.g. track_order. The model refers to it by this name.
• Description: “Look up the status and delivery estimate of a customer's order by order number.” — concrete, not vague.
• Parameters: only what the assistant must collect from the customer (for example order_number). Keep them minimal.
• Require verified identity for anything that reads a customer's own data.

2. Write the endpoint

AskBrew calls your endpoint from its servers (never the browser) with a JSON body: the tool name, the collected arguments, and the verified visitor identity. Your endpoint must scope its response to that identity — return only the authenticated customer's data, never trust an id from the arguments alone.

{
  "tool": "track_order",
  "arguments": { "order_number": "A-2001" },
  "identity": {
    "customerId": "cust_1001",
    "email": "olivia@example.com",
    "verified": true
  },
  "conversation_id": "…"
}

app.post("/askbrew/track-order", (req, res) => {
  const { identity, arguments: args } = req.body;
  // Scope to the authenticated customer — never trust args alone.
  const order = db.findOrder(identity.customerId, args.order_number);
  if (!order) return res.status(404).json({ message: "No such order." });
  res.json({ status: order.status, eta: order.eta });
});

3. Secure the endpoint

Add an auth header (for example Authorization: Bearer …) so only AskBrew can call your endpoint. The value is encrypted at rest and sent only from our servers. The endpoint URL must be https and must not resolve to a private or internal address.

4. Test, then enable

A tool cannot go live until a test call passes. Open the tool's Test panel, enter a real customer id from your system (an identity-scoped endpoint will reject an unknown one), run the test, and review the response. When it passes, enable the tool.

• Passed means your endpoint returned 200 (or a clean 404).
• 403/Failed usually means the customer id isn't recognised, or the auth header is wrong.
• Editing a tool turns it off until you re-test — changes never go live unverified.

In a conversation

Once enabled, the assistant offers the tool to itself when a customer's own message needs it. It never calls a tool because a document or an earlier message said to. You can see every call — tool, arguments, status, timing — inline in the conversation view and under Activity log.