> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# chat

> Send a message to an AI agent and return its reply.

[ref-aichatclient]: /docs/server-sdks/reference/python/agents/ai-chat-client

[createconversation]: /docs/server-sdks/reference/python/agents/ai-chat-client/create-conversation

[swml-user-event]: /docs/server-sdks/reference/python/agents/function-result/swml-user-event

Send a message and return the agent's reply. One call is one full turn, including any tool calls the
agent makes along the way, so expect seconds rather than milliseconds.

## **Parameters**

**`conversation_id`** `str` — required

The conversation to send on.

---

**`message`** `str` — required

The message to send.

---

**`role`** `str` — default: user

`user` or `system`. A `system` message steers the agent without appearing as something the user
said.

---

**`config_url`** `str | None` — default: None

Creates the conversation if it does not exist yet. Saves a call, at the cost of never receiving
`initial_message`, so the agent does not speak first.

---

**`user_metadata`** `dict[str, Any] | None` — default: None

Applies only when this call creates the conversation.

---

**`timeout`** `int | None` — default: None

Applies only when this call creates the conversation.

---

**`reinit`** `bool` — default: False

Applies only when this call creates the conversation.

---

## **Returns**

`ChatResponse` — carries `text`, `conversation_id`, and `user_event`.

`user_event` is present only when the turn produced one. Its contents are whatever your tool passed
to [`swml_user_event()`][swml-user-event], so the shape is yours.

## **Raises**

`ChatInProgressError` when a turn is already running on this conversation. That is the contract
rather than a transient failure, so wait for the first turn to return instead of retrying.

## **Example**

```python {13,19}
import asyncio

from signalwire.ai_chat import AIChatClient, ChatInProgressError

CONFIG_URL = "https://bayview-taxi.example.com/swml"


async def main():
    async with AIChatClient(space="your-space") as client:
        await client.create_conversation("chat-8f21", config_url=CONFIG_URL)

        try:
            reply = await client.chat(
                "chat-8f21", "How much is a van from 123 Gough Street to the airport?"
            )
        except ChatInProgressError:
            return  # a turn is already running; wait rather than retry

        print("Ada:", reply.text)
        if reply.user_event:
            handle(reply.user_event)


asyncio.run(main())
```

> Send a message to an AI agent and return its reply.