Defining one
The description is the whole thing
The model has nothing else to go on. It decides whether to call your action, and with what, entirely from what you write here. Weak:Parameters need descriptions too
Every parameter must say what it is, or the model will invent a value.order_id
with no description gets filled with something plausible-looking and wrong.
Placeholders
Use{{parameter_name}} in the URL or the body:
- Every placeholder must have a parameter behind it. A
{{order_id}}with no matching parameter would reach your API as the literal text{{order_id}}— failing in a way that looks like your bug rather than ours. - The body must still be valid JSON once the blanks are filled.
Reserved names
These clash with the agent’s built-in tools and are refused:search_knowledge,
capture_lead, escalate_to_human, send_media, send_link.
Anything else you connect is namespaced, so no third-party tool can impersonate
one of the agent’s own.
Security
HTTPS only, checked twice
HTTPS only, checked twice
Once when you save it — so you hear about an
http:// address while looking
at the form — and again at call time.The URL is resolved before we fetch it
The URL is resolved before we fetch it
Validated and DNS-resolved, so an address cannot be used to reach a
private network from inside ours.
Your secret is encrypted and shown once
Your secret is encrypted and shown once
Stored encrypted, not readable from the dashboard, and never displayed again
after you save it.
Thirty calls per conversation, per hour
Thirty calls per conversation, per hour
Custom actions are the only tool that spends your money, so the cap is a
per-conversation one. A conversation is the unit a visitor controls, so it is
the unit that gets bounded — a workspace-wide cap would be one a single
visitor could exhaust for everybody.Thirty is far above any honest conversation. Checking an order, a booking and
a balance twice over is under ten.
Writing the endpoint
Four rules, in order of how much trouble they save.1
Check the shared secret first
Before parsing anything.
2
Require two facts, never one
An order number alone is guessable — they are usually sequential. Require the
number and something only the real customer knows, like the email on the
order.
3
Fail identically for "not found" and "wrong match"
4
Return the smallest useful object
Everything you return may end up spoken to the customer. Return the status
and the tracking link, not the whole order record with the customer’s address
and payment details in it.