***

title: ai_message
slug: /reference/python/relay/call/ai-message
description: Send a message to an active AI agent session.
max-toc-depth: 3
---------------------

For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

[ai]: /docs/server-sdks/reference/python/relay/call/ai

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.

<Note>
  This method requires an active AI session started via
  [`ai()`][ai]. Calling it without
  an active session has no effect.
</Note>

## **Parameters**

<ParamField path="message_text" type="Optional[str]" toc={true}>
  The message text to send to the AI agent.
</ParamField>

<ParamField path="role" type="Optional[str]" toc={true}>
  The role of the message sender. Valid values:

  * `"user"` -- simulate user input
  * `"system"` -- send a system-level instruction
  * `"assistant"` -- inject an assistant response
</ParamField>

<ParamField path="reset" type="Optional[dict]" toc={true}>
  Reset configuration. Allows resetting AI state such as the conversation
  history or functions.
</ParamField>

<ParamField path="global_data" type="Optional[dict]" toc={true}>
  Update the global data accessible to the AI and SWAIG functions.
</ParamField>

## **Returns**

`dict` -- Server response confirming the message was sent.

## **Example**

```python {22}
import asyncio
from signalwire.relay import RelayClient

client = RelayClient(
    project="your-project-id",
    token="your-api-token",
    host="your-space.signalwire.com",
    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()
```