Business APIs

A business API is a read-only endpoint of yours that the agent may call by name. Order status is the one almost everyone starts with.

Registering one

In the console, Agent, Business APIs, Add. You provide:

• A function name, for example lookup_order
• A short description of when to use it
• Parameters, with types
• The endpoint URL
• Credentials, sent as a header

The URL and the credentials are stored server side and are never included in anything sent to the model. What the model receives is this and nothing more:

{
  "name": "lookup_order",
  "description": "Status of one order belonging to the current visitor",
  "parameters": {
    "order_no": { "type": "string" }
  }
}

What we send you

POST https://your-site.example/api/support/order
X-Hepo-Signature: sha256=...

{
  "order_no": "SO-48219",
  "visitor": {
    "email": "marta@example.com",
    "verified": true,
    "site": "nordvik"
  }
}

visitor.email is the identity the visitor actually proved, either through the identify call in your own login or through verification inside the conversation. verified is never true unless one of those happened.

Verify ownership on your side

This is the part that matters most, and it is your job, not the model’s.

Return the order only if it belongs to visitor.email. If it does not, return an empty result. Do not return the order with a note saying it belongs to someone else, because the model is helpful by nature and will read that note out loud.

An anonymous visitor guessing order numbers must not be able to retrieve a stranger’s address, phone number or order total. Enforcing that in your handler is the only place it can be enforced properly. A handbook instruction to “verify identity first” is not a security control.

Verify X-Hepo-Signature against your endpoint secret before doing any of this.

Responses

Return flat JSON. Keys become facts the agent may quote, so only include what you would be happy seeing in a chat window.

{
  "status": "out_for_delivery",
  "carrier": "PostNL",
  "last_scan": "2026-07-24T09:14:00Z",
  "eta": "2026-07-24"
}

Failures

Time out, return a 500, or return nothing, and the agent will not invent a status. It uses the fallback wording you configured and hands the conversation to a human.

Calls are rate limited per visitor so a single person cannot use the chat box to hammer your backend.

Keep it read-only

There is no write mode and there will not be one. Refunds, cancellations and address changes are decisions with consequences, and a model that can take them is a model that will eventually take one you did not want.