DocsReference
Staff order tools
What staff can ask the workspace assistant to do, and which actions need a second confirmation.
By the Callaroo team. Updated November 2026
Staff tools are the workspace-side half of the catalog. They let a signed-in team member ask for order history, one order, an item count, a status change, a follow-up or a block without leaving the conversation. They are not available to callers.
Who can use them
The person asking must be a signed-in member of the workspace. The tool derives the business from that membership, so one restaurant cannot read or change another restaurant's orders. A caller on the phone, a visitor to the public site and a member of a different workspace all fail the same authorization check.
The six tools
- get_recent_orders
- Read a bounded list of orders in a time window
- get_order_details
- Read one order by ID or active short code
- count_item_sales
- Count an item's quantity and orders over a window
- update_order_status
- Apply one allowed status transition
- queue_customer_callback
- Queue staff follow-up for an order
- block_number
- Add a number to the workspace blocklist
Reading orders
get_recent_orders returns summaries, newest first. It is bounded so a question about “the last few orders” cannot turn into a full-table read.
- Time window
- 1 to 1,440 minutes; 60 by default
- Status filter
- Optional: needs_review, confirmed, preparing, ready, completed or cancelled
- Result limit
- 1 to 15 orders; 5 by default
- Each summary
- Order ID, short code, status, customer name, total, item summary and timestamps
get_order_details takes exactly one of an order ID or a short code. It returns the full line items, version, conversation reference, the caller's last four digits and any review flag. A completed or cancelled short code is historic, so a lookup by short code only finds an active order; use the order ID for a closed one.
The tool returns only the last four digits of the caller's number. The full contact record stays in the workspace, where access is already controlled.
Counting item sales
count_item_sales answers questions such as “how many chicken wraps have we sold in the last two hours?”. The database computes the count from the line items stored on confirmed and later orders; the assistant does not add up a list in its head.
- The item query is 1 to 80 characters and matches an exact name first, then name or alias fragments.
- The window is 1 to 1,440 minutes, 60 by default.
- Only orders in confirmed, preparing, ready or completed count. Drafts, review orders and cancellations do not.
- An ambiguous query returns up to three candidates and asks for a narrower name.
- The result reports the matched item, quantity, number of orders and the exact window.
Summaries you will see
Four different things are called a summary in the workspace. They answer different questions, and one is not a substitute for another.
- Order summary
- A short line built on the server from the stored items, such as “2 Chicken wraps, 1 Fries”. It is truncated at 240 characters and is not written by the assistant.
- Conversation summary
- The short version of the call, written when the call ends. It sits next to the transcript and the outcome.
- Sales count
- A computed quantity and order count for one menu item over a time window, not a narrative.
- Callback preview
- The customer, short code, last four digits and reason shown before a follow-up is queued.
Read the transcript when a detail matters. The order summary is for scanning a list; the conversation summary is for someone who was not on the call; the sales count is for a quantity question.
Changing an order's status
update_order_status moves one order along the kitchen path. It requires the order, the version the staff member saw, and the next status. It does not accept a free-form status and it cannot skip a step.
- needs_review
- Can move to confirmed or cancelled
- confirmed
- Can move to preparing or cancelled
- preparing
- Can move to ready or cancelled
- ready
- Can move to completed
- completed
- Terminal. No further change
- cancelled
- Terminal. No further change
A note of up to 200 characters can be attached to the change. The result reports the previous status, the new status and the new version, so the next action uses the right version.
Queueing a callback
queue_customer_callback creates a staff follow-up for an order. It requires the order ID, a reason of 1 to 200 characters and a trusted confirmation. It does not place an outbound call; it puts the work in the callback queue.
- The order must have a stored callback number. Without one, the tool returns callback_phone_unavailable.
- The preview shows the customer, the short code, the last four digits and the reason before anything is written.
- A pending callback for the same order is reused rather than duplicated.
- The result says whether the callback was reused, so staff do not promise a second call that will not happen.
Blocking a number
block_number adds a caller to the workspace blocklist. It can target the last caller from trusted records or an explicit international number, and it always requires a reason of 1 to 120 characters.
- The first call returns a preview with the resolved number and reason; it writes nothing.
- Executing requires a trusted staff agreement bound to that exact number and reason.
- A masked caller label is rejected rather than reconstructed into a number.
- Your own business number, the configured transfer destination and numbers on the never-block list are protected.
- The blocklist is rate-limited to 10 blocks per hour per workspace.
- Blocking an already-blocked number reports that it was already blocked instead of creating a duplicate.
Why a second confirmation exists
Cancelling an order, approving a needs_review order, queueing a callback and blocking a number all need a preview first. The staff member confirms that exact preview, and the server records a short-lived agreement tied to the action. A simple confirmation flag from the assistant alone is not accepted.
- Default lifetime
- 5 minutes
- Allowed range
- 30 seconds to 15 minutes
- Bound to
- The exact order or number, plus the version, status, note or reason that applies
- If it expires
- Preview again; the old agreement is not reused
- If the order changes
- A status change fails its version check before any write
Version checks and replay
Status changes carry the order version the staff member saw. A stale version fails with a version conflict, so two people cannot silently overwrite each other. Callback requests are bound to the exact order and reason by the confirmation. Each tool call also has an invocation ID: repeating the same call and arguments replays the stored result instead of writing twice, while reusing the ID for a different action is rejected.
Common errors
- order_not_found
- No order matches that ID or active short code
- ambiguous_order
- More than one active order matches the short code
- invalid_transition
- That status change is not allowed from the current state
- version_conflict
- The order changed; read it again before retrying
- staff_agreement_required
- Preview and confirm the exact action first
- staff_agreement_invalid
- The confirmation expired or does not match the action
- callback_phone_unavailable
- The order has no stored callback number
- item_not_found
- No menu item matches the sales query
- ambiguous_item
- More than one menu item matches; narrow the name
- protected_number
- That number is the business's own configured number
- protected_transfer_destination
- That number is the saved transfer destination
- never_block
- The number is on the never-block list
- rate_limited
- Too many new blocks in the last hour; try later
- masked_caller
- Only a masked caller label is available; supply the number explicitly
What staff tools cannot do
- Create a new order or edit its line items. Staff tools move existing orders; they do not rewrite the caller's choices.
- Refund a payment, change a price or take a card payment.
- Call the customer. A callback is queued work for a person.
- Block the business's own number, its transfer destination or a never-block number.
- Bypass the workspace boundary by supplying another organization's ID.
- Approve a destructive action without the trusted confirmation step.
Treat a review flag as a request for a person, not as an error. Read the line items and the conversation before approving, and leave a note when you change something the caller already agreed to.