Skip to content
Black Friday starts in 4 days

DocsCustom AI tools

Custom AI tools

Let the AI look things up in your own system: an order, a subscription, whether your game server is up. You build one HTTPS endpoint. This page is what it receives and what it sends back.

How it fits together

  1. 1

    You describe the tool

    On the dashboard, under Your AI, Custom tools: a name, when to use it, what the AI sends, what it may read back, and your address. There is no Discord command for this, and it needs Manage Server.

  2. 2

    The AI decides

    While it answers someone, the AI sees that one of your tools fits and asks for it with an input.

  3. 3

    The bot calls you

    The bot checks the input, sends one signed request to your endpoint, and hands your answer to the AI.

Every plan includes custom tools, Free included. How many each plan holds is on the pricing page.

The request

A POST to your address, over HTTPS on port 443. One request per use, with no retry: if it fails, the AI is told the tool is unavailable and says so.

HeaderValue
Content-Typeapplication/json
Acceptapplication/json
Accept-Encodingidentity. Answer uncompressed; a compressed answer is refused.
User-AgentAITicketBot-Tools/1 (+https://aiticketbot.com)
X-AITB-Signaturesha256=<hex>. See Verifying a request.
AuthorizationOnly if you set one on the tool. Sent exactly as you typed it.
The body
{
  "tool": "lookup_order",
  "input": { "order_id": "A-10492" },
  "context": {
    "guild_id": "1234567890123456789",
    "surface": "tickets",
    "user_id": "9876543210987654321",
    "channel_id": "1122334455667788990",
    "ticket_id": "17242"
  },
  "request_id": "3f0c0f4e-8f0f-4a53-9b0d-1d2a6a2d6b0e",
  "sent_at": "2026-10-02T14:58:47Z"
}
  • input only ever holds the inputs you declared, with the types you declared. A text input is never longer than the length you set.
  • Every id is a JSON string. Discord ids are too large for a JavaScript number.
  • surface is tickets, ask, faq, widget or test. ticket_id is there only inside a ticket.
  • channel_id is the Discord channel or thread the AI answers in, and null on the website chat, the dashboard and the Test button. ticket_id is our own ticket number; another ticket bot does not know it.
  • sent_at is UTC and ends in Z.

Who is asking

input is written by an AI from what a member typed. A member can ask it to look up an order number that is not theirs, and the AI will pass that number on.

context.user_id is the only identity to trust. The bot sets it from Discord, never the AI. Check ownership against it: does order A-10492 belong to this Discord user?

It is null for an anonymous visitor of the website chat, where there is nobody to name. A tool that returns personal data should answer {"ok": false, "error": "sign_in_required"} when it is null. That is also why a new tool starts switched off for the website chat.

On a request sent by the dashboard's Test button, surface is test and user_id is the admin who pressed it.

Acting on the ticket

A tool that does something to the ticket, for example closes it in the ticket bot that opened it, takes the channel from context.channel_id. The bot sets it from Discord. Do not add a channel input for the AI to fill in: the AI does not know the channel's id, and a member could ask it to pass another ticket's id.

Verifying a request

Every tool has its own signing secret. The dashboard shows it once, when the tool is added, and again only when you make a new one. The header is an HMAC-SHA256 of the exact bytes of the request body, hex encoded.

Python
import hashlib, hmac

def verify(secret: str, raw_body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)
Node.js
import crypto from "node:crypto";

function verify(secret, rawBody, header) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(header ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
PHP
<?php
// Read the raw body BEFORE json_decode: the signature is over these exact bytes.
$raw    = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_AITB_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('AITB_TOOL_SECRET'));
if (!hash_equals($expected, $header)) {
    http_response_code(401);
    exit;
}
$request = json_decode($raw, true);

Compare in constant time, and verify the raw bytes before you parse them. To refuse a replayed request, reject a sent_at older than a few minutes and a request_id you have already seen. Requests come from the bot's servers with no fixed IP list, so rely on the signature, not the source address.

The answer

Status 2xx, a JSON object, at most 32 KB, within 8 seconds.

It worked
{ "ok": true, "status": "shipped", "items": ["Gold pack"], "paid_at": "2026-09-28" }
It did not, and the AI should say so
{ "ok": false, "error": "order_not_found" }

ok and error are always read. error is cut down to a short code (lowercase letters, digits and _, 40 characters), so send a code, not a sentence.

Only the result fields you listed reach the AI

The tool's result fields are listed on the dashboard, each with a type. The bot passes those on and drops everything else. This is on purpose: whatever reaches the AI, it may say to the member, and a sentence inside a result is repeated as a fact.

Type on the dashboardWhat is passed on
One of a listThe value, if it is exactly one of your values (capitals count). Otherwise dropped.
TextOne line, at most 500 characters. Line breaks become spaces. Longer text is cut to 497 characters and ends in ...
Whole number, NumberThe number, up to 253. A value of another type is dropped.
Yes or notrue or false.
DateA date or a moment in UTC, in ISO 8601. See Dates.
List of textsUp to 20 texts, each one line of at most 500 characters (a longer one is cut and ends in ...). Anything in the list that is not text is skipped.
List of itemsUp to 20 items. Each item is a JSON object, and only the item fields you listed are passed on, each checked by its own type like a result field. See Lists of items.

A value of the wrong type is dropped, not converted. A field you send as null reaches the AI as null, meaning no value: "renewsAt": null for a plan that does not renew. Do not return text typed by other people (notes, comments, usernames) in a result field, and use “One of a list” wherever the value comes from a known set. Send ids (Discord ids, order numbers) as strings: a number above 253 is dropped. The dashboard's Test button shows what reached the AI and why anything did not.

Field names match your keys exactly

A result field's name is a key of your JSON, and it must match exactly, capitals included: letters, digits and _, starting with a letter, at most 32 characters. camelCase like serverName works. Two names that differ only in capitals, like plan and Plan, cannot be in the same tool. When your endpoint sends a name in other capitals, the Test button says so.

Lists of items

A List of items is for a list of objects: a member's subscriptions, a customer's orders, a status page's components or incidents. On the dashboard you list the fields of one item, and every item is checked against them.

A List of items named subscriptions
{
  "ok": true,
  "active_count": 2,
  "subscriptions": [
    {
      "serverName": "AI Ticket Bot",
      "plan": "Premium",
      "status": "active",
      "expires": 1793692800
    },
    {
      "serverName": "My Server",
      "plan": "Pro",
      "status": "cancelled",
      "expires": "2026-12-01"
    }
  ]
}
  • Up to 20 items, with 1 to 8 fields in an item. An item field can be any type except the two lists. A tool can have up to 3 lists of items.
  • An entry that is not an object, or that has none of your fields, is skipped. An item field sent as null is passed on as null.
  • A key inside an item that you did not list is dropped, as at the top level.
  • An empty list ([]) is passed on as an empty list: “nothing is down” is an answer.
  • A single object where a list belongs is dropped. Wrap it in [ ].
  • An item cannot hold a list: an incident's list of updates is not read. Put what the AI needs in its own item field, such as the newest update as latestUpdate.

Put the most useful items first. Every text is at most 500 characters and every list at most 20 items. On top of that, the items of all the lists in one answer share about 8,000 characters of what the AI gets. Each list keeps its first items, in your order: the soonest to expire, the open incidents before the resolved ones. Plain fields are never cut by this.

A shortened list says so

When a list had more items than the AI is given, the bot adds _cut with the full count, and the AI is told to say it is showing only part of the list. A _cut key in your own answer is dropped.

What the AI gets
{
  "ok": true,
  "subscriptions": [ ... 20 items ... ],
  "_cut": { "subscriptions": 27 }
}

Dates

A Date field, at the top level or inside an item, accepts:

"2026-11-30"The AI gets:"2026-11-30"
"2026-11-30T12:00:00+02:00"The AI gets:"2026-11-30T10:00:00Z"
"2026-11-30T12:00:00Z" or "2026-11-30 12:00:00"The AI gets:"2026-11-30T12:00:00Z". With no offset, the time is read as UTC.
Unix seconds, 1793692800The AI gets:"2026-11-03T08:00:00Z"
Unix milliseconds, 1793692800000The AI gets:"2026-11-03T08:00:00Z"

A number of 100,000,000,000 or more is read as milliseconds. Anything else ("next tuesday", "2026-02-30", a negative number) is dropped, and so are fractions of a second.

What counts as a failure

What happenedWhat the AI is told
No answer within 8 seconds{"ok": false, "error": "timeout"}
A status outside 2xx, including any 3xx (redirects are not followed){"ok": false, "error": "unavailable"}
A body over 32 KB, not JSON, or not an object{"ok": false, "error": "unavailable"}
An address that is private, local, or does not resolve{"ok": false, "error": "unavailable"}

The AI then tells the member it could not check and, inside a ticket, offers to bring in staff.

Ten failures in a row switch the tool off. The admin who added it gets one direct message, and it stays off until it is switched back on from the dashboard. An {"ok": false} answer from your endpoint is a normal answer and does not count.

Limits

  • At most 3 tool requests in one AI reply. The AI is told the rest could not run.
  • 30 requests a minute per server, across all of its tools.
  • Tools are used while the AI answers people, never while it is being trained.
  • In a reply where it used a tool, the AI does not close the ticket or blacklist the member. It can still bring in staff, and it can close on a later reply.