Business tools

Business tools

Let the agent call your own systems.

A business tool is one of your HTTPS endpoints the agent may call during a conversation — "where is my order?", "is size L in stock?", "book 11am tomorrow".

  1. Describe when to use it in plain words — the agent reads this.
  2. List the inputs it must collect (order_id, date…). Use {order_id} in the URL to put a value in the path.
  3. Your endpoint returns JSON; the agent turns it into a friendly answer.

Requests we send

GET https://yourshop.com/api/orders/SK10291

Header Value
X-SKO-Signature t=1725000000,v1=<hex> — HMAC-SHA256 of "{t}.{body}" with your business signing secret
X-SKO-Business Your business UUID
X-SKO-Conversation The conversation UUID

Verify the signature (PHP):

[$t, $v1] = array_map(fn ($p) => explode('=', $p, 2)[1], explode(',', $request->header('X-SKO-Signature')));
$expected = hash_hmac('sha256', $t.'.'.$request->getContent(), env('SKO_SIGNING_SECRET'));
abort_unless(hash_equals($expected, $v1) && abs(time() - (int) $t) < 300, 401);

For GET tools the signed body is the JSON of the query parameters.

Safety

  • Only https:// URLs on public IPs are called. Private and internal addresses are blocked.
  • Turn on Ask the customer to confirm for anything that creates or changes data: the agent must read the details back and get a "yes" before the call runs.
  • Calls time out after the timeout you set (max 30 s).

Sandbox

Use mock://orders/{order_id}, mock://stock?sku=… or mock://slots?date=… to try tool calling with realistic fake data before you build an endpoint.

← PreviousProducts & services