Text the caller during the call

Messagingin-call SMS

Have an AI agent tool text the caller during a live voice call without exposing the phone number to the model.

Also called send a link by text during a call, in-call SMS

sms

The claim

A tool result can carry a SWML document, and that document can run send_sms. The handler in this recipe builds one with FunctionResult.send_sms. It addresses the text to caller_id_num, which the platform posts in the body of every tool call, and sends it from a number in your environment. The tool takes only an appointment argument, so the model cannot choose where the text goes.

Why it holds

Docs: the send_sms reference. The SWAIG tool webhook lists caller_id_num in the request body.

How it works

def text_confirmation(self, args, raw_data):
    to = (raw_data or {}).get("caller_id_num")
    if not to or not to.startswith("+"):
        return FunctionResult("NO_NUMBER: ... Read the details back instead.")
    return FunctionResult("The details are on their way to your phone.").send_sms(
        to_number=to, from_number=SMS_FROM, body=body, tags=["appointment"])

The function result the platform receives:

{"response": "The details are on their way to your phone.",
 "action": [{"SWML": {"version": "1.0.0", "sections": {"main": [
   {"send_sms": {"to_number": "+15557654321", "from_number": "+15551230000",
                 "body": "Ridgeline Cycles: your workshop appointment is ...",
                 "tags": ["appointment"]}}]}}}]}

send_sms is the SDK method and the wire verb, inside an action whose key is SWML. When caller_id_num is absent or does not start with +, or the appointment is empty, the handler returns a response and no action, and the platform sends nothing.

The swml/ surface does the same in a plain document: answer, then send_sms addressed to %{call.from}, then play. call.from is the caller’s number in the SWML variables reference, so that document attempts a send_sms on every call. The agent version texts only when the handler receives a non-empty appointment.

Limitations

The handler learns nothing about delivery. Per the reference, the verb sets send_sms_result to success or failed on the call; this recipe does not read it.

The handler sends nothing when caller_id_num is absent or does not start with +, and tells the model to read the details aloud instead.

What to change first

Add a phone property to the tool’s parameters and run the verifier. The first assertion fails, which is the point: once the model can supply a number, the caller no longer binds the send.

Where this sits

Before this

Give a voice AI agent a tool

Send an SMS Show the AI model only the fields it needs

python/app.py

"""Text the caller during the call.

A tool result can carry a SWML document, and that document can run
`send_sms`. A handler that has something the caller should keep, such as an
appointment time, texts it to them from inside the tool result.

The model never sees a phone number. The tool takes no number parameter. The
handler reads the caller's number from `caller_id_num`, which the platform
posts with every tool call. The sending number comes from your environment.
The model's only part is deciding when to call the tool.

Written against signalwire-sdk 3.0.1.
"""
import os

from dotenv import load_dotenv
from signalwire import AgentBase, FunctionResult

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

# The number the text is sent from. It must be a messaging-enabled number on
# your SignalWire project. There is no placeholder: a text from a number you
# do not own fails, so the app refuses to start without one.
SMS_FROM = os.getenv("SMS_FROM")
if not SMS_FROM or not SMS_FROM.startswith("+"):
    raise SystemExit("SMS_FROM is not set. Put a messaging-enabled number in "
                     "E.164 form in .env (see .env.example).")

SHOP = "Ridgeline Cycles"


class BookingAgent(AgentBase):
    def __init__(self):
        super().__init__(name="booking", route="/booking")
        self.prompt_add_section(
            "Role",
            f"You book workshop appointments for {SHOP}. Agree a day and time "
            "with the caller, then use text_confirmation so they have it in "
            "writing. Do not read phone numbers aloud or ask for one.",
        )

    @AgentBase.tool(
        name="text_confirmation",
        description=(
            "Text the appointment details to the caller's phone once a day and "
            "time are agreed."
        ),
        parameters={
            "type": "object",
            "properties": {
                "appointment": {
                    "type": "string",
                    "description": "The agreed day and time, for example "
                                   "'Thursday 10 September at 2pm'.",
                }
            },
            "required": ["appointment"],
        },
    )
    def text_confirmation(self, args, raw_data):
        # The platform posts the caller's number with every tool call. The
        # model never has it and cannot pass a different one.
        to = (raw_data or {}).get("caller_id_num")
        if not to or not to.startswith("+"):
            return FunctionResult(
                "NO_NUMBER: this caller's number is not available, so no text "
                "was sent. Read the details back to them instead."
            )
        when = (args.get("appointment") or "").strip()
        if not when:
            return FunctionResult("INCOMPLETE: agree a day and time first.")
        body = f"{SHOP}: your workshop appointment is {when}. Reply to this " \
               f"text to change it."
        return FunctionResult(
            "The details are on their way to your phone."
        ).send_sms(to_number=to, from_number=SMS_FROM, body=body,
                   tags=["appointment"])


agent = BookingAgent()

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

# Text the caller during the call, in plain SWML: answer, send the text to the
# number that dialled in, and carry on talking. `%{call.from}` is the caller's
# number. Replace from_number with a messaging-enabled number on your project
# before you deploy this document; +15551230000 is a placeholder.
version: "1.0.0"
sections:
  main:
    - answer: {}
    - send_sms:
        to_number: "%{call.from}"
        from_number: "+15551230000"
        body: "Ridgeline Cycles: workshop hours are 8 to 6, Monday to Saturday."
        tags: ["hours"]
    - play: { url: "say:We have texted you our hours. How can we help today?" }
    - hangup: {}

Run it

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

SMS_FROM must be a messaging-enabled number on your project; the app refuses to start without one. To deploy the swml/ surface instead, replace its from_number placeholder first. The webhook needs a public HTTPS URL. For a local run, expose port 3000 with a tunnel such as ngrok and use that hostname. Point a number’s SWML webhook at https://<user>:<password>@<your-host>/booking/, agree a time, and watch your phone.

Verify it

No network, no account.

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

The verifier renders and validates the SWML, runs the handler with the payload shape the platform posts, and asserts the following.

the tool’s only parameter is appointment
with caller_id_num present, the whole result equals the expected payload
that payload is one SWML action holding one send_sms to that number from SMS_FROM, with the exact body and tag
the inline SWML document validates against the bundled schema
an appointment containing another phone number leaves to_number as the caller’s and lands in the body
with no caller number, or one that does not start with +, the response starts NO_NUMBER and carries no action
with no agreed time the response starts INCOMPLETE and carries no action
the plain-SWML surface validates and its send_sms goes to %{call.from}

Report an issue