Callback requests

Some visitors would rather pick up the phone than talk through the browser. With callbacks on, the web widget shows a short form: the visitor types their phone number, ticks a consent sentence, and your agent calls them right away from your KugelAudio number.

What you need

• An agent with a web widget.
• A number bought through KugelAudio and routed to the same agent. It is the number the visitor sees, and calling it back reaches the same agent. Numbers from your own Twilio or Telnyx account and the shared test line cannot be the caller ID.

Set it up

1. 1
   Turn callbacks on

   Open your agent in the dashboard, go to Phone & web, open the website widget and choose Set up next to Callbacks are off. Turn callbacks on, pick the number visitors see, the countries the agent may call, and how many requests a day the widget takes.

2. 2
   Copy the new code

   The code under the preview now has data-mode="both" and a data-turnstile-sitekey. Replace the code on your pages with it. both shows the call button and the callback form; callback shows only the form.

3. 3
   Greet like a caller

   The agent's first words on a callback reach someone who asked for the call. Say who is calling and why, as in the next section.

<script src="https://cdn.kugelaudio.com/widget/v1/widget.js"
  data-agent="YOUR_WIDGET_ID"
  data-mode="both"
  data-turnstile-sitekey="YOUR_SITE_KEY"
  async></script>

Copy the code from the dashboard rather than from this page: it carries your widget's id and site key.

Tell a callback from an incoming call

The agent reads call.direction: outbound when it is calling the visitor back, inbound for every other call. Open a callback by saying who is calling, that the visitor asked for the call, and that they are speaking with an AI:

import { Text, useAgentInfo } from "curb";

export function CallbackGreeting() {
  const direction = useAgentInfo((info) => info["call.direction"]);
  return direction === "outbound" ? (
    <Text>
      You are calling the visitor back because they asked for a call on the website. Open
      with: "Hallo, hier ist die digitale Assistenz von Example. Sie hatten gerade einen
      Rückruf angefordert." Then help with their question.
    </Text>
  ) : null;
}

Render <CallbackGreeting /> inside <Agent> in src/agent/agent.tsx, after <SystemPrompt>. The widget's context reaches a callback too, so useClient() reads the same keys as on a browser call (see Tell the agent where a call comes from).

What the visitor sees

After sending the form, the widget says that the call is on its way, and then whether it connected. If nobody answers or the line is busy, the agent tries once more after two minutes. When that call is not answered either, the widget says so, and in both mode it offers the browser call instead.

Consent and limits

• Consent. The visitor ticks a sentence saying they agree to be called now by an AI assistant. The widget has a default in German and English; set your own with data-callback-consent. The exact sentence the visitor ticked is stored with the request.
• Who can be called. Only numbers in the countries you picked (Germany, Austria and Switzerland are available). Premium-rate and special-service numbers are refused.
• How often. A visitor who presses the button again while their call is still on its way gets that same call, not a second one. Your widget calls one number at most three times in 24 hours, so a visitor whose call dropped can ask again, and one number gets at most ten callbacks a day from all KugelAudio customers together. Your daily limit (500 by default, up to 5,000) caps all requests through your widget.
• Spam protection. The form runs a Cloudflare Turnstile check before anything is sent.

The visitor sees a short message when a request is refused, for example when their number was already called today.

Costs

A callback counts against your plan's agent minutes like any other call. Calls to the countries above carry no separate carrier charge.

Next steps

• Web widget for the widget's other options.
• Recipes for the event and channel patterns that work with callbacks too.