rpc_ai_message | SignalWire

Send a message, global data, or both to the AI agent running on another call. Useful for cross-call coordination, such as notifying a held caller’s agent about a status change or handing it a value to speak later.

A message lands as a turn in the other agent’s conversation, where it competes with everything else arriving that moment. Global data is merged silently into the other call’s global_data and stays there until a prompt expands it with ${global_data.key}, which makes it the more reliable channel for content a later step needs to say.

Parameters

call_id

strRequired

Call ID of the target call whose AI agent should receive the message.

message_text

str | NoneDefaults to None

The message text to inject into the target AI’s conversation.

role

strDefaults to system

Role for the injected message. Typically "system" for instructions. Sent only when message_text is given.

global_data

dict[str, Any] | NoneDefaults to None

Object merged into the target call’s global_data. See also rpc_ai_global_data().

Raises

ValueError when neither message_text nor global_data is given.

Returns

FunctionResult — self, for chaining.

Examples

Inject a message

from signalwire import AgentBase
from signalwire import FunctionResult
agent = AgentBase(name="my-agent", route="/agent")
agent.set_prompt_text("You are a helpful assistant.")
@agent.tool(name="notify_caller", description="Notify the caller on the other line")
def notify_caller(args, raw_data):
    caller_call_id = args.get("original_call_id")
    return (
        FunctionResult("Tell the caller you have passed the message along.")
        .rpc_ai_message(
            call_id=caller_call_id,
            message_text="The person you're trying to reach is unavailable. Please leave a message."
        )
    )
agent.serve()

Hand the other call a value to speak

# Sender: set the value, then release the held call.
return (
    FunctionResult("Tell the caller you have passed the message along.")
    .rpc_ai_message(call_id, global_data={"decline_message": args["message"]})
    .rpc_ai_unhold(call_id)
)
# Destination step, on the other call:
# step.set_text("Tell the caller: ${global_data.decline_message}")