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

1 import asyncio
2 
3 from signalwire.ai_chat import AIChatClient, ChatInProgressError
4 
5 CONFIG_URL = "https://bayview-taxi.example.com/swml"
6 
7 
8 async def main():
9     async with AIChatClient(space="your-space") as client:
10         await client.create_conversation("chat-8f21", config_url=CONFIG_URL)
11 
12         try:
13             reply = await client.chat(
14                 "chat-8f21", "How much is a van from 123 Gough Street to the airport?"
15             )
16         except ChatInProgressError:
17             return  # a turn is already running; wait rather than retry
18 
19         print("Ada:", reply.text)
20         if reply.user_event:
21             handle(reply.user_event)
22 
23 
24 asyncio.run(main())