create_conversation | SignalWire

Create a conversation, or reset an existing one when reinit is set. Calling it for an id that already exists returns that conversation untouched.

Parameters

conversation_id

strRequired

The conversation id. You choose it, and it is scoped to your project.

config_url

strRequired

The URL serving your agent’s SWML. SignalWire fetches it server-to-server, so it must be reachable from the public internet.

user_message

str | None

An opening message from the user, sent as part of creating the conversation.

timeout

int | None

Idle seconds before the conversation ends. Sent as conversation_timeout; the service default is 3600.

user_metadata

dict[str, Any] | None

Arbitrary data about the user, echoed back on this conversation’s webhooks. Sent as user_meta_data.

reinit

boolDefaults to False

Reset an existing conversation instead of returning it as-is.

Returns

ConversationInfo — carries id, status (created, reinitialized, or exists), and initial_message.

initial_message is the agent’s generated greeting. Create the conversation when the visitor opens the chat rather than when the page loads. Use chat() with config_url instead when you don’t need the agent to speak first.

Example

1 import asyncio
2 
3 from signalwire.ai_chat import AIChatClient
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         info = await client.create_conversation(
11             "chat-8f21",
12             config_url=CONFIG_URL,
13             timeout=1800,
14             user_metadata={"customer_tier": "premium"},
15         )
16         print(info.status, info.initial_message)
17 
18 
19 asyncio.run(main())