> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# createConversation

> Create a conversation with an AI agent, or reset an existing one.

[ref-aichatclient]: /docs/server-sdks/reference/typescript/agents/ai-chat-client

[chat]: /docs/server-sdks/reference/typescript/agents/ai-chat-client/chat

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`** `string` — required

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

---

**`options`** `CreateConversationOptions` — required

Creation options. `configUrl` is required.

---

**`options.configUrl`** `string` — required

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`** `boolean` — default: 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.

> **Warning**
>
> `initialMessage` is the agent's generated greeting. Create the conversation
> when the visitor opens the chat rather than when the page loads. Use
> [`chat()`][chat] with `configUrl` instead when you don't need the agent to
> speak first.

## **Example**

```typescript {6-9}
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);
```

> Create a conversation with an AI agent, or reset an existing one.