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

import asyncio
from signalwire.ai_chat import AIChatClient
CONFIG_URL = "https://bayview-taxi.example.com/swml"
async def main():
    async with AIChatClient(space="your-space") as client:
        info = await client.create_conversation(
            "chat-8f21",
            config_url=CONFIG_URL,
            timeout=1800,
            user_metadata={"customer_tier": "premium"},
        )
        print(info.status, info.initial_message)
asyncio.run(main())