Normalize spoken dates and phone numbers in a voice AI tool handler

AI Agentsspoken input normalization for voice AI

Take a date and a phone number in the caller's words, turn them into an ISO date and an E.164 number in the tool handler, and read both back for the caller to check.

Also called speech-to-text date parsing, phone number from spoken digits, voice form validation, callback scheduling by phone

tool-calling

The claim

Speech recognition does not produce dates and phone numbers. It produces words: “the fifth of March”, “9/30”, “oh one two three”. Asking the model to convert them is asking it to guess, and a guess about a callback number is a missed callback. This tool takes both values in the caller’s words and the handler does the conversion in code.

Why it holds

Three things follow from that. The parameter descriptions carry examples of the words, not a format, so the model passes what it heard. The handler writes the machine values, 2026-09-15 and +14155550123, to global_data, where the next tool or the post-prompt reads them. And the handler reads both back in words, with the weekday, so a wrong date is caught by the caller before it is booked. When it cannot read a value it says so with a typed state and asks for the one piece it needs.

How it works

@AgentBase.tool(name="schedule_callback", parameters={
    "type": "object",
    "properties": {
        "date": {"type": "string", "description": "The day in the caller's words: "
                 "'tomorrow', 'next Tuesday', 'the fifth of March', 'March 5th', '9/30'."},
        "phone": {"type": "string", "description": "The number as spoken or read: "
                  "'four one five, five five five, oh one two three' or '(415) 555-0123'."},
    }, "required": ["date", "phone"]})
def schedule_callback(self, args, raw_data):
    when = normalize_date(args.get("date"), today())
    if when is None:
        return FunctionResult(f"UNPARSED_DATE: could not read {args.get('date')!r} ...")
    number = normalize_phone(args.get("phone"))
    ...
    result = FunctionResult(f"Callback set for {spoken_date(when)} at "
                            f"{spoken_phone(number)}. Read both back ...")
    result.update_global_data({"callback": {"date": when.isoformat(), "phone": number}})
    return result

The date grammar is small and stated. “Today”, “tomorrow” and “the day after tomorrow” are relative. A bare weekday is the next one after today, so “Saturday” on a Saturday is a week away; “next” adds a week. A month and an ordinal day, as words (“the twenty second of September”), digits (“22nd”) or 9/30, mean the next time that date comes round. A year makes it absolute. Cardinal day words (“March five”) are not in the grammar. Anything else, and a day that does not exist in its month, is UNPARSED_DATE.

Phone numbers are the digits found among the words, with “oh” and “o” as zero. Ten digits get +1; eleven starting with a one get +; anything else is UNPARSED_PHONE. The read-back groups the digits three, three, four, as a person would say them.

What “next Tuesday” and “(415) 555-0123” return on Saturday 5 September 2026:

{"response": "Callback set for Tuesday, September 15th at four one five, five five five, zero one two three. Read both back and ask the caller to confirm.",
 "action": [{"set_global_data": {"callback": {"date": "2026-09-15", "phone": "+14155550123"}}}]}

Limitations

The grammar is North American English and one country code. “Next Tuesday” means a week after the coming Tuesday here; some callers mean the coming one. State the rule your callers expect, and keep the read-back, which is what catches the difference either way.

Times of day are not parsed. Add them as a third parameter with the same shape: words in, a typed state out when the words do not resolve.

A year makes a date absolute even when it is in the past. A yearless date is searched eight years ahead, far enough for “February 29” across a skipped century leap year. Ten digits are taken as a North American number with no check on the area code. Each is one line to tighten once you know your callers.

The TypeScript SDK’s /swaig route in 2.0.5 hands argument to the handler as posted, while the platform nests the arguments in argument.parsed[0]. The surface overrides onFunctionCall to unwrap that shape.

What to change first

Change or 7 to or 0 in the Python weekday arithmetic (|| 7 in the TypeScript) and run the verifier. The “Saturday” row fails, because a Saturday now means today rather than a week away. Every other weekday row still passes, which shows exactly which rule the change touched.

Where this sits

Before this

Give a voice AI agent a tool

Commit a transaction from a call Collect required details in any order with a voice AI agent

python/app.py

"""Normalize spoken dates and phone numbers in a tool handler.

Speech recognition hands the model "next Tuesday" and "four one five, five
five five, oh one two three". The tool takes those words as they are; the
handler turns them into an ISO date and an E.164 number, writes the machine
values to `global_data`, and reads both back in words the caller can check.
When it cannot, it says so with a typed state and asks for the piece it needs.
The prompt never asks the model to convert anything.

Written against signalwire-sdk 3.0.1.
"""
import os
import re
from datetime import date, timedelta

from dotenv import load_dotenv
from signalwire import AgentBase, FunctionResult

# the SDK does not read .env for you
load_dotenv()

MONTH_NAMES = ["january", "february", "march", "april", "may", "june", "july",
               "august", "september", "october", "november", "december"]
MONTHS = {m: i for i, m in enumerate(MONTH_NAMES, 1)}
MONTHS.update({m[:3]: i for i, m in enumerate(MONTH_NAMES, 1)})
MONTHS["sept"] = 9
WEEKDAYS = ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"]
UNITS = {"first": 1, "second": 2, "third": 3, "fourth": 4, "fifth": 5, "sixth": 6,
         "seventh": 7, "eighth": 8, "ninth": 9, "tenth": 10, "eleventh": 11,
         "twelfth": 12, "thirteenth": 13, "fourteenth": 14, "fifteenth": 15,
         "sixteenth": 16, "seventeenth": 17, "eighteenth": 18, "nineteenth": 19,
         "twentieth": 20, "thirtieth": 30}
TENS = {"twenty": 20, "thirty": 30}
DIGITS = {"zero": "0", "oh": "0", "o": "0", "one": "1", "two": "2", "three": "3",
          "four": "4", "five": "5", "six": "6", "seven": "7", "eight": "8", "nine": "9"}
DIGIT_WORDS = ["zero", "one", "two", "three", "four", "five", "six", "seven", "eight",
               "nine"]
FILLER = {"on", "the", "of", "this", "at"}


def today():
    """The clock. TODAY pins it so the verifier's dates are stable."""
    pinned = os.getenv("TODAY")
    return date.fromisoformat(pinned) if pinned else date.today()


def _words(text):
    return re.sub(r"[^a-z0-9/]+", " ", (text or "").lower().replace("-", " ")).split()


def _next_weekday(start, name):
    """The next such weekday strictly after start."""
    delta = (WEEKDAYS.index(name) - start.weekday()) % 7 or 7
    return start + timedelta(days=delta)


def _resolve(month, day, year, start):
    """A calendar date, or None when the day does not exist in that month.

    Without a year, the next time the date comes round. February 29th exists
    in one year of four, and a century rule can stretch that to eight, so the
    search runs that far rather than stopping at next year."""
    if year:
        try:
            return date(year, month, day)
        except ValueError:
            return None
    for candidate_year in range(start.year, start.year + 9):
        try:
            candidate = date(candidate_year, month, day)
        except ValueError:
            continue
        if candidate >= start:
            return candidate
    return None


def normalize_date(text, start):
    """'tomorrow', 'next Tuesday', 'the fifth of March', 'March 5th', '9/30'.

    A weekday means the next one after today; 'next' adds a week. A month and
    day with no year mean the next time that date comes round.
    """
    words = _words(text)
    joined = " ".join(words)
    if joined == "today":
        return start
    if joined == "tomorrow":
        return start + timedelta(days=1)
    if joined in ("day after tomorrow", "the day after tomorrow"):
        return start + timedelta(days=2)
    core = [w for w in words if w not in FILLER]
    if len(core) == 1 and core[0] in WEEKDAYS:
        return _next_weekday(start, core[0])
    if len(core) == 2 and core[0] == "next" and core[1] in WEEKDAYS:
        return _next_weekday(start, core[1]) + timedelta(days=7)
    if len(core) == 1:
        m = re.fullmatch(r"(\d{1,2})/(\d{1,2})(?:/(\d{4}))?", core[0])
        if m:
            return _resolve(int(m[1]), int(m[2]), int(m[3]) if m[3] else None, start)
    month = day = year = None
    i = 0
    while i < len(core):
        w = core[i]
        if w in MONTHS and month is None:
            month = MONTHS[w]
        elif w in TENS and i + 1 < len(core) and UNITS.get(core[i + 1], 10) < 10:
            day = TENS[w] + UNITS[core[i + 1]]
            i += 1
        elif w in UNITS:
            day = UNITS[w]
        elif re.fullmatch(r"\d{1,2}(st|nd|rd|th)?", w):
            day = int(re.sub(r"\D", "", w))
        elif re.fullmatch(r"\d{4}", w):
            year = int(w)
        else:
            return None
        i += 1
    if month is None or day is None:
        return None
    return _resolve(month, day, year, start)


def normalize_phone(text):
    """Spoken or written digits to E.164, North America assumed. None otherwise."""
    digits = "".join(DIGITS.get(w, w) for w in _words(text) if w in DIGITS or w.isdigit())
    if len(digits) == 10:
        return "+1" + digits
    if len(digits) == 11 and digits.startswith("1"):
        return "+" + digits
    return None


def ordinal(n):
    if 11 <= n % 100 <= 13:
        return f"{n}th"
    suffix = {1: "st", 2: "nd", 3: "rd"}.get(n % 10, "th")
    return f"{n}{suffix}"


def spoken_date(d):
    """'Tuesday, September 8th': the weekday lets the caller catch a wrong date."""
    weekday = WEEKDAYS[d.weekday()].capitalize()
    month = MONTH_NAMES[d.month - 1].capitalize()
    return f"{weekday}, {month} {ordinal(d.day)}"


def spoken_phone(e164):
    """'four one five, five five five, zero one two three', grouped for reading back."""
    n = e164[2:]
    groups = (n[:3], n[3:6], n[6:])
    return ", ".join(" ".join(DIGIT_WORDS[int(c)] for c in g) for g in groups)


class CallbackDesk(AgentBase):
    def __init__(self):
        super().__init__(name="callback-desk", route="/callback")
        self.prompt_add_section(
            "Role",
            "You schedule callbacks for a repair shop. Pass the day and the number "
            "exactly as the caller says them; the tool converts them. Read back what "
            "the tool returns and ask the caller to confirm.",
        )

    @AgentBase.tool(
        name="schedule_callback",
        description=("Schedule a callback on a day at a phone number. Pass both as the "
                     "caller said them. Do not convert or reformat either one."),
        parameters={
            "type": "object",
            "properties": {
                "date": {"type": "string",
                         "description": ("The day in the caller's words: 'tomorrow', "
                                         "'next Tuesday', 'the fifth of March', "
                                         "'March 5th', '9/30'.")},
                "phone": {"type": "string",
                          "description": ("The number as spoken or read: 'four one five, "
                                          "five five five, oh one two three' or "
                                          "'(415) 555-0123'.")},
            },
            "required": ["date", "phone"],
        },
    )
    def schedule_callback(self, args, raw_data):
        date_text, phone_text = args.get("date"), args.get("phone")
        when = normalize_date(date_text, today())
        if when is None:
            return FunctionResult(
                f"UNPARSED_DATE: could not read {date_text!r} as a date. Ask the caller "
                "for the day and the month, then call again.")
        number = normalize_phone(phone_text)
        if number is None:
            return FunctionResult(
                f"UNPARSED_PHONE: {phone_text!r} was not a ten digit number. "
                "Ask the caller to say it digit by digit, then call again.")
        # the machine values go to global_data; the caller hears words
        result = FunctionResult(f"Callback set for {spoken_date(when)} at "
                                f"{spoken_phone(number)}. Read both back and ask the "
                                "caller to confirm.")
        result.update_global_data({"callback": {"date": when.isoformat(),
                                                "phone": number}})
        return result


agent = CallbackDesk()

if __name__ == "__main__":
    agent.serve(host="0.0.0.0", port=int(os.getenv("PORT", "3000")))

/**
 * Normalize spoken dates and phone numbers in a tool handler.
 *
 * Speech recognition hands the model "next Tuesday" and "four one five, five
 * five five, oh one two three". The tool takes those words as they are; the
 * handler turns them into an ISO date and an E.164 number, writes the machine
 * values to `global_data`, and reads both back in words the caller can check.
 * When it cannot, it says so with a typed state and asks for the piece it
 * needs. The prompt never asks the model to convert anything.
 *
 * Written against @signalwire/sdk 2.0.5.
 *
 *     npm start            # serves /callback/ and /callback/swaig
 */
import "dotenv/config";
import { AgentBase, FunctionResult } from "@signalwire/sdk";

type Json = Record<string, unknown>;
type Hook = Promise<Json> | undefined;

const MONTH_NAMES = ["january", "february", "march", "april", "may", "june", "july",
                     "august", "september", "october", "november", "december"];
const MONTHS: Record<string, number> = { sept: 9 };
MONTH_NAMES.forEach((m, i) => { MONTHS[m] = i + 1; MONTHS[m.slice(0, 3)] = i + 1; });
const WEEKDAYS = ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday",
                  "sunday"];
const UNITS: Record<string, number> = {
  first: 1, second: 2, third: 3, fourth: 4, fifth: 5, sixth: 6, seventh: 7, eighth: 8,
  ninth: 9, tenth: 10, eleventh: 11, twelfth: 12, thirteenth: 13, fourteenth: 14,
  fifteenth: 15, sixteenth: 16, seventeenth: 17, eighteenth: 18, nineteenth: 19,
  twentieth: 20, thirtieth: 30,
};
const TENS: Record<string, number> = { twenty: 20, thirty: 30 };
const DIGITS: Record<string, string> = {
  zero: "0", oh: "0", o: "0", one: "1", two: "2", three: "3", four: "4", five: "5",
  six: "6", seven: "7", eight: "8", nine: "9",
};
const DIGIT_WORDS = ["zero", "one", "two", "three", "four", "five", "six", "seven",
                     "eight", "nine"];
const FILLER = new Set(["on", "the", "of", "this", "at"]);
const DAY = 86_400_000;

/** The clock, as a UTC date at midnight. TODAY pins it for the verifier. */
export function today(): Date {
  const pinned = process.env["TODAY"];
  if (pinned) return new Date(`${pinned}T00:00:00Z`);
  const now = new Date();
  return new Date(Date.UTC(now.getFullYear(), now.getMonth(), now.getDate()));
}

const words = (text: string | undefined) =>
  (text ?? "").toLowerCase().replace(/-/g, " ").replace(/[^a-z0-9/]+/g, " ").trim()
    .split(" ").filter(Boolean);

/** Monday is 0, as in Python. */
const weekday = (d: Date) => (d.getUTCDay() + 6) % 7;
const addDays = (d: Date, n: number) => new Date(d.getTime() + n * DAY);

function nextWeekday(start: Date, name: string) {
  const delta = ((WEEKDAYS.indexOf(name) - weekday(start)) % 7 + 7) % 7 || 7;
  return addDays(start, delta);
}

/** A calendar date, or undefined when the day does not exist in that month. */
function resolve(month: number, day: number, year: number | undefined, start: Date) {
  const make = (y: number) => {
    const d = new Date(Date.UTC(y, month - 1, day));
    return d.getUTCMonth() === month - 1 && d.getUTCDate() === day ? d : undefined;
  };
  if (year) return make(year);
  // the next time the date comes round; February 29th can be eight years off
  for (let y = start.getUTCFullYear(); y <= start.getUTCFullYear() + 8; y++) {
    const candidate = make(y);
    if (candidate && candidate >= start) return candidate;
  }
  return undefined;
}

/**
 * 'tomorrow', 'next Tuesday', 'the fifth of March', 'March 5th', '9/30'. A
 * weekday means the next one after today; 'next' adds a week. A month and day
 * with no year mean the next time that date comes round.
 */
export function normalizeDate(text: string | undefined, start: Date): Date | undefined {
  const all = words(text);
  const joined = all.join(" ");
  if (joined === "today") return start;
  if (joined === "tomorrow") return addDays(start, 1);
  if (joined === "day after tomorrow" || joined === "the day after tomorrow") {
    return addDays(start, 2);
  }
  const core = all.filter((w) => !FILLER.has(w));
  if (core.length === 1 && WEEKDAYS.includes(core[0]!)) {
    return nextWeekday(start, core[0]!);
  }
  if (core.length === 2 && core[0] === "next" && WEEKDAYS.includes(core[1]!)) {
    return addDays(nextWeekday(start, core[1]!), 7);
  }
  if (core.length === 1) {
    const m = /^(\d{1,2})\/(\d{1,2})(?:\/(\d{4}))?$/.exec(core[0]!);
    if (m) {
      return resolve(Number(m[1]), Number(m[2]), m[3] ? Number(m[3]) : undefined, start);
    }
  }
  let month: number | undefined, day: number | undefined, year: number | undefined;
  for (let i = 0; i < core.length; i++) {
    const w = core[i]!;
    const next = core[i + 1];
    if (w in MONTHS && month === undefined) month = MONTHS[w];
    else if (w in TENS && next !== undefined && (UNITS[next] ?? 10) < 10) {
      day = TENS[w]! + UNITS[next]!;
      i++;
    } else if (w in UNITS) day = UNITS[w];
    else if (/^\d{1,2}(st|nd|rd|th)?$/.test(w)) day = Number(w.replace(/\D/g, ""));
    else if (/^\d{4}$/.test(w)) year = Number(w);
    else return undefined;
  }
  if (month === undefined || day === undefined) return undefined;
  return resolve(month, day, year, start);
}

/** Spoken or written digits to E.164, North America assumed. */
export function normalizePhone(text: string | undefined): string | undefined {
  const digits = words(text).filter((w) => w in DIGITS || /^\d+$/.test(w))
    .map((w) => DIGITS[w] ?? w).join("");
  if (digits.length === 10) return "+1" + digits;
  if (digits.length === 11 && digits.startsWith("1")) return "+" + digits;
  return undefined;
}

function ordinal(n: number) {
  const tail = n % 100;
  if (tail >= 11 && tail <= 13) return `${n}th`;
  const small: Record<number, string> = { 1: "st", 2: "nd", 3: "rd" };
  const suffix = small[n % 10] ?? "th";
  return `${n}${suffix}`;
}

const cap = (s: string) => s.charAt(0).toUpperCase() + s.slice(1);

/** 'Tuesday, September 8th': the weekday lets the caller catch a wrong date. */
export function spokenDate(d: Date) {
  const day = cap(WEEKDAYS[weekday(d)]!);
  const month = cap(MONTH_NAMES[d.getUTCMonth()]!);
  return `${day}, ${month} ${ordinal(d.getUTCDate())}`;
}

/** 'four one five, five five five, zero one two three', grouped for reading back. */
export function spokenPhone(e164: string) {
  const n = e164.slice(2);
  return [n.slice(0, 3), n.slice(3, 6), n.slice(6)]
    .map((g) => [...g].map((c) => DIGIT_WORDS[Number(c)]).join(" ")).join(", ");
}

const iso = (d: Date) => d.toISOString().slice(0, 10);

export class CallbackDesk extends AgentBase {
  constructor() {
    super({ name: "callback-desk", route: "/callback" });
    this.promptAddSection("Role", {
      body: "You schedule callbacks for a repair shop. Pass the day and the number "
          + "exactly as the caller says them; the tool converts them. Read back what "
          + "the tool returns and ask the caller to confirm.",
    });
    this.defineTool({
      name: "schedule_callback",
      description: "Schedule a callback on a day at a phone number. Pass both as the "
                 + "caller said them. Do not convert or reformat either one.",
      parameters: {
        type: "object",
        properties: {
          date: { type: "string",
                  description: "The day in the caller's words: 'tomorrow', "
                             + "'next Tuesday', 'the fifth of March', 'March 5th', "
                             + "'9/30'." },
          phone: { type: "string",
                   description: "The number as spoken or read: 'four one five, five five "
                              + "five, oh one two three' or '(415) 555-0123'." },
        },
        required: ["date", "phone"],
      },
      handler: (args) => {
        const dateText = args["date"] as string | undefined;
        const phoneText = args["phone"] as string | undefined;
        const when = normalizeDate(dateText, today());
        if (!when) {
          return new FunctionResult(
            `UNPARSED_DATE: could not read '${dateText}' as a date. `
            + "Ask the caller for the day and the month, then call again.");
        }
        const number = normalizePhone(phoneText);
        if (!number) {
          return new FunctionResult(
            `UNPARSED_PHONE: '${phoneText}' was not a ten `
            + "digit number. Ask the caller to say it digit by digit, then call again.");
        }
        // the machine values go to global_data; the caller hears words
        return new FunctionResult(`Callback set for ${spokenDate(when)} at `
            + `${spokenPhone(number)}. Read both back and ask the caller to confirm.`)
          .updateGlobalData({ callback: { date: iso(when), phone: number } });
      },
    });
  }

  /**
   * The platform posts a tool's arguments as `argument: {parsed: [args], raw}`.
   * The 2.0.5 `/swaig` route hands `argument` to the handler as posted, so
   * this hook unwraps the documented shape before dispatch.
   */
  override onFunctionCall(name: string, args: Json, raw: Json): Hook {
    const parsed = args["parsed"];
    if (!Array.isArray(parsed)) return undefined;
    const tool = this.getTools().find((t) => t.name === name);
    return tool ? tool.execute((parsed[0] ?? {}) as Json, raw) : undefined;
  }
}

if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
  for (const name of ["SWML_BASIC_AUTH_USER", "SWML_BASIC_AUTH_PASSWORD"]) {
    if (!process.env[name]) throw new Error(`${name} is required; see .env.example`);
  }
  new CallbackDesk().serve({ port: Number(process.env["PORT"] ?? 3000) });
}

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # set SWML_BASIC_AUTH_PASSWORD
python app.py                    # serves /callback/ and /callback/swaig

The TypeScript surface is the same agent with defineTool, on Node 20.18.1 or newer:

cd typescript
npm ci
cp ../.env.example .env
npm start

Point a number’s SWML webhook at https://<user>:<password>@<your-host>/callback/ and call it. Say a day and read out a number; the agent reads both back.

Verify it

No network, no account.

python verify.py          # from the recipe folder, not python/

With today pinned to Saturday 5 September 2026 through TODAY, the verifier renders the document and runs fourteen pairs through the handler. It asserts the following.

one tool on each surface, date and phone both required, and both descriptions carry the spoken examples
“tomorrow”, “today”, “Tuesday” and “next Tuesday” become the 6th, the 5th, the 8th and the 15th of September, each read back with its weekday
“Saturday”, said on a Saturday, is the 12th, not today
“the fifth of March” and “March 5th” both become 2027-03-05; “September 30”, “9/30” and “the twenty second of September” stay in 2026
“February 29th”, said in 2026, is 2028-02-29, the next leap day rather than nothing
the same number in seven spellings, spoken and written, one with the leading one, all become +14155550123 and are read back as grouped words
every success writes callback.date and callback.phone to global_data as one action
“someday soon” and “February 30” are UNPARSED_DATE; a seven digit number is UNPARSED_PHONE, each with no action
the TypeScript surface, through its own /swaig route with the documented argument shape, gives the same fourteen results

Report an issue