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

conversationId

stringRequired

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

options

CreateConversationOptionsRequired

Creation options. configUrl is required.

options.configUrl

stringRequired

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

options.userMessage

string

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

options.timeout

number

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

options.userMetadata

Record<string, unknown>

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

options.reinit

booleanDefaults to false

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

Returns

Promise<ConversationInfo> — carries id, status, and initialMessage. status is the lifecycle state the service reports; the SDK fills in created when the response omits it.

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

Example

import { AIChatClient } from '@signalwire/sdk';
const CONFIG_URL = 'https://bayview-taxi.example.com/swml';
const client = new AIChatClient({ space: 'your-space' });
const info = await client.createConversation('chat-8f21', {
  configUrl: CONFIG_URL,
  userMetadata: { customer_id: 'cust-4410' },
});
console.log(info.status, info.initialMessage);