Inject a message into a live AI call

AI Agentslive AI agent prompt updates

Send a REST command to update a live AI call with a system message, shared data, or a replacement prompt.

observability

The claim

POST /api/calling/calls with command: calling.ai_message addresses a call that is running an AI agent, by id. The body carries the call id at the top level and a params object. The vendored REST spec, tools/openapi/rest.json, describes the system role as injecting “instructions or context that modify the AI’s behavior mid-conversation without the caller hearing it”. The same params take global_data, “arbitrary JSON data to merge into the AI session’s global data store”, or reset, with full_reset and a new system_prompt.

Why it holds

The verifier proves the request. The spec is the authority for what the platform does with it.

How it works

client = RestClient()

def nudge(call_id, instruction):
    return client.calling.ai_message(call_id, role="system", message_text=instruction)

def share(call_id, data):
    return client.calling.ai_message(call_id, global_data=data)

def restart(call_id, system_prompt):
    return client.calling.ai_message(
        call_id, reset={"full_reset": True, "system_prompt": system_prompt})

What the platform receives for nudge:

{"command": "calling.ai_message",
 "id": "6d3f4a0e-2b1c-4e7a-9f0d-1c2b3a4d5e6f",
 "params": {"role": "system",
            "message_text": "The caller is a returning customer. Skip the identity questions."}}

The SDK’s calling namespace, rest/namespaces/calling.py, sends every call command to that one path. It puts the call id in id. The spec marks command, id and params required for this command. Its role enum is system, user or assistant. The spec describes user as “a message as if the caller said it” and assistant as “a message as if the AI said it”.

Your backend learns the call id from the agent. The tool webhook body carries it as call_id; see the SWAIG tool webhook.

Limitations

The verifier proves the request, not the model’s reaction. What the next turn does with a system message is the model’s behaviour on a live call.

The spec describes a user role message as one the AI treats “as if the caller said it”. Keep it out of flows where the caller’s words matter as a record.

What to change first

Change role="system" to role="operator" in nudge and run the verifier. The role assertion fails, which is the point: the three roles are the whole vocabulary.

Where this sits

python/app.py

"""Inject a message into a live AI call.

One REST command, `calling.ai_message`, addresses a call that is already
running an AI agent, by id. The vendored REST spec describes `role: system` as
injecting "instructions or context that modify the AI's behavior
mid-conversation without the caller hearing it". The same command carries
`global_data` to merge into the session, or `reset` with a new system prompt.

Your backend needs the call id. The tool webhook body carries it as `call_id`
(docs: ai-swaig-tool-webhook).

Written against signalwire-sdk 3.0.1 (RestClient.calling).
"""
from dotenv import load_dotenv
from signalwire.rest import RestClient

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

# RestClient() reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN /
# SIGNALWIRE_SPACE from the environment (signalwire/rest/client.py).
client = RestClient()


def nudge(call_id, instruction):
    """A system-role message, per the spec one the caller does not hear."""
    return client.calling.ai_message(call_id, role="system",
                                     message_text=instruction)


def share(call_id, data):
    """Merge keys into the session's global_data mid-call."""
    return client.calling.ai_message(call_id, global_data=data)


def restart(call_id, system_prompt):
    """A reset: full_reset with a new system_prompt, as the spec defines it."""
    return client.calling.ai_message(
        call_id, reset={"full_reset": True, "system_prompt": system_prompt})


if __name__ == "__main__":
    import sys

    if len(sys.argv) < 3:
        raise SystemExit("usage: python app.py <call_id> <instruction>")
    print(nudge(sys.argv[1], " ".join(sys.argv[2:])))

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # project id, API token, space
python app.py <call_id> "The caller is a returning customer."

Take the call id from a tool webhook of a call that is running an AI agent. There is no server to expose; the script speaks to the REST API and exits.

Verify it

No network, no account.

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

The verifier swaps the SDK’s HTTP layer for a recorder, calls the three helpers, and asserts the following.

each helper adds exactly one POST to the documented calling path
the spec marks command, id and params required for this command, and the observed role is in its enum
each body equals {"command": "calling.ai_message", "id": <call id>, "params": ...} with the exact params
every param is a documented property of the spec’s variant, and so is every key nested under reset

Report an issue