Skip to main content

AI Companion — Setup

This page explains how to turn the AI Companion on, how AI credit works, and where you see what it costs. For what the Companion is and how it behaves, read the AI Companion concept first.

There is nothing to configure: no provider, no API key, no model choice. dzbot runs the Companion for you and charges its usage against your organization's AI credit.

Turning it on​

The Companion only shows up for users who have the AI Companion access right (it lives in the Tickets group of admin rights, as tickets.ai_companion). Grant it to the groups whose members should be able to use the Companion:

  • Server Admin -> Groups -> select a group -> enable AI Companion.

Anyone in a group with this right sees the AI Companion button in the admin header (the sparkles icon, top right). Users without the right never see it.

For how access rights and groups work in general, see Access control.

Optional: custom instructions​

You can give the Companion extra guidance on tone, wording or policy that applies to every conversation of your organization — the AI Companion instructions field in the organization settings under Integrations. The instructions refine how the Companion behaves but never override its core rules: it still acts only with the rights of the person using it, and every change it makes shows up as a card in the chat. Leave the field empty to use the defaults.

How AI credit works​

AI credit belongs to your organization and is shared by all of its servers.

  • Included every month: every organization with at least one server on an active subscription or in its trial period gets 1 € of AI usage per billing month. The billing month follows the organization's oldest active server subscription, or the trial while it runs. Unused included credit does not carry over.
  • Purchased credit: if you need more, you can top up prepaid credit. Purchased credit never expires and stays with the organization even while it has no server. It cannot be transferred, is not refunded and is not paid out.
  • Order of use: the included monthly amount is used first, then purchased credit.

AI apps you connect over MCP (such as Claude or ChatGPT) do not use AI credit — they bring their own model. See Connect AI apps (MCP).

What a request costs​

Each request is charged in euros after it has finished, based on its size. A typical request costs a fraction of a cent. You only ever see euro amounts.

Every message carries the whole session so far, so messages get more expensive as a session grows. Once a session is very long, each further message costs about twice as much again. For a new topic, start a new session.

If a request costs more than what is left, the balance ends at 0 — it never goes negative — and dzbot covers the difference. After that the Companion declines new requests until credit is added:

  • In the admin panel, users who may top up get a link to do so; everyone else is asked to contact an organization admin.
  • In Discord (/ai and mentions), the message includes a link to the AI Companion page.

Seeing usage and topping up​

Navigation path:

  • Server Admin -> Organization -> AI Companion

The page needs the access right Access AI Companion page — on the organization (org.ai_companion.access) or on the server (admin.ai_companion.access). Every group that already had the AI Companion right received the server right automatically.

The page shows:

  • Available now — everything the Companion can still spend
  • Included this month — what is left of the 1 € and the date it renews
  • Purchased credit — your prepaid balance
  • Top up AI credit — the top-up form (see below)
  • spending per day for 7, 30 or 90 days
  • spending per team member
  • the most expensive conversations
  • amounts dzbot covered because the balance ran out mid-conversation
  • Credit added — the history of top-ups and credit granted by dzbot

The Companion panel itself also shows the current AI credit in its header, and each session shows how much it has cost so far.

Topping up​

Topping up needs the billing right Access Billing — on the organization (org.billing.access) or on the server (admin.billing.access), the same right used to manage the dzbot subscription. Without it, the top-up form is not shown.

  1. Pick 5 €, 10 € or 25 €, or enter another amount between 5 € and 500 €.
  2. Tick the box agreeing that dzbot provides the credit immediately and that you thereby lose your right of withdrawal.
  3. Pay through the Stripe checkout. Stripe adds VAT where it applies.

The credit appears on the page as soon as the payment is confirmed. Each top-up is also booked in your organization's Accounting as a dzbot AI credit expense. Individual AI requests never appear there — only top-ups.

Verifying it works​

Once you have the access right:

  1. Reload the admin panel.
  2. Look for the AI Companion button (sparkles icon) in the top-right header.
  3. Open it, start a New session, and ask something simple like "search for player <name>".

If you get a sensible answer back, you're set. Head to AI Companion usage to learn what it can do.

Troubleshooting​

If a request fails, the chat shows a short message describing why:

MessageWhat it meansWhat to do
The AI credit is used upYour organization has no included or purchased credit leftTop up under Organization -> AI Companion, or ask an organization admin to
The AI service is currently unavailableA temporary outage of the AI serviceWait a moment and try again
Maximum steps reachedThe task ran long without finishingReply "continue" to pick up where it stopped, or break the task into smaller asks
System errorSomething went wrong on dzbot's sideTry again later