chat | SignalWire

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

strRequired

The conversation to send on.

message

strRequired

The message to send.

role

strDefaults to user

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

config_url

str | 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

Applies only when this call creates the conversation.

timeout

int | None

Applies only when this call creates the conversation.

reinit

boolDefaults to 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(), 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

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())