ai_message | SignalWire

Send a message to an active AI agent session on the call. Use this to inject context, instructions, or simulated user input into a running AI conversation.

This method requires an active AI session started via ai(). Calling it without an active session has no effect.

Parameters

message_text

str | NoneDefaults to None

The message text to send to the AI agent.

role

str | NoneDefaults to None

The role of the message sender. Valid values:

"user" — simulate user input
"system" — send a system-level instruction
"assistant" — inject an assistant response

reset

dict | NoneDefaults to None

Reset configuration. Allows resetting AI state such as the conversation history or functions.

global_data

dict | NoneDefaults to None

Update the global data accessible to the AI and SWAIG functions.

Returns

dict — Server response confirming the message was sent.

Example

import asyncio
from signalwire.relay import RelayClient
client = RelayClient(
    project="your-project-id",
    token="your-api-token",
    contexts=["default"],
)
@client.on_call
async def handle_call(call):
    await call.answer()
    # Start an AI agent
    action = await call.ai(
        prompt={"text": "You are a helpful assistant."},
    )
    # Inject a system message after 10 seconds
    await asyncio.sleep(10)
    await call.ai_message(
        message_text="The caller is a VIP customer. Be extra helpful.",
        role="system",
    )
    await action.wait()
client.run()