Conversations

A conversation is where users send messages. It can be a support thread, a group channel, a direct message, or the chat next to a video call. Every message, member, and read receipt belongs to one conversation.

Where this fits: your backend creates a conversation and adds members, then makes a chat token for each user. The app connects and chats. This page covers the first step. You need a backend with an API key; see the Chat quickstart.

When to create a conversation

Create one conversation for each place people chat in your product. Some common patterns:

Your product	One conversation per…	Example `name`
Customer support	Support ticket	`support-room-42`
Team chat	Channel	`team-design`
Direct messages	Pair of users	`dm-alice-bob`
Video call with chat	Call (link it with `roomId`)	`call-8d86361a`
Live stream	Created for you when the stream starts	(see Live Streaming)

Pick the name in your backend, from an id you already have, like a ticket id. That way you can find the conversation again without storing Livqeno's id.

Create

On your backend:

import { Livqeno } from '@livqeno/server';
const livqeno = new Livqeno({
  apiKey: process.env.LIVQENO_API_KEY,
  baseUrl: process.env.LIVQENO_API_URL, // https://api.livqeno.com
});
 
const conversation = await livqeno.chat.createConversation({
  name: 'support-room-42',
  members: [{ userId: 'alice', role: 'ADMIN' }, { userId: 'bob' }],
});
// { publicId: 'conv_9WcQ4kRz1nB2xYtL', name: 'support-room-42', type: 'CHANNEL', status: 'ACTIVE', ... }

import os
from livqeno import Livqeno, CreateConversationParams, ConversationMember
 
livqeno = Livqeno(
    api_key=os.environ["LIVQENO_API_KEY"],
    base_url=os.environ["LIVQENO_API_URL"],  # https://api.livqeno.com
)
conversation = livqeno.chat.create_conversation(
    CreateConversationParams(
        name="support-room-42",
        members=[ConversationMember(user_id="alice", role="ADMIN"), ConversationMember(user_id="bob")],
    )
)

You get back the conversation. publicId (like conv_9WcQ…) is Livqeno's id for it.

Options:

Option	What it does	When to use it
`name`	Your name for it. Must be unique in the project's environment. A duplicate fails with `409`.	Always. Use an id from your own system.
`members`	The first members, each with an optional role (`MEMBER` by default).	Almost always. See the warning below.
`getOrCreate`	If the `name` already exists, return that conversation instead of failing. `members` is ignored in that case.	When the same code may run more than once, like "open chat" for a ticket.
`roomId`	Links the conversation to an RTC room. The type becomes `ROOM` unless you set `type`.	When the chat belongs to a video call.
`type`	`CHANNEL` (default), `ROOM`, or `DIRECT`.	To label what kind of chat it is.
`retentionDays`	The conversation's message retention setting.	When you have a data-retention policy.
`metadata`	Your own JSON.	To store your own ids or labels.

Find a conversation

Use this to look up a conversation from your backend, for example to show a list of chats or check that one exists.

On your backend:

const conversations = await livqeno.chat.listConversations();
const one = await livqeno.chat.getConversation('support-room-42'); // or a conv_... id, or an attached room's id

conversations = livqeno.chat.list_conversations()
one = livqeno.chat.get_conversation("support-room-42")

getConversation / get_conversation accepts any of these (Conversation references):

the public id (conv_...)
the name
the id of a linked RTC room

The same is true everywhere else a conversation is needed, including chat.connect({ room }) in your app.

Update a conversation

Use this to rename, archive, or change the retention of a conversation. There's no SDK method yet, so call the REST endpoint from your backend with your API key:

Terminal

curl -X PATCH "$LIVQENO_API_URL/v1/chat/conversations/support-room-42" \
  -H "Authorization: Bearer $LIVQENO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"retentionDays": 30}'

All fields are in REST API → Chat.

Common errors

Error	Cause	Fix
`409` on create	A conversation with that `name` already exists in this environment.	Pass `getOrCreate: true`, or use `getConversation()`.
`404` on `getConversation` / `get_conversation`	Wrong environment, or no matching conversation or room.	Make sure the API key is for the right environment. A development key can't see production conversations.
Users get `ROOM_NOT_FOUND` when they connect	They aren't members. Livqeno answers "not found" instead of "forbidden", so outsiders can't learn which conversations exist.	Add them with `addMember`.
`ROOM_NOT_FOUND` when passing `roomId`	That RTC room isn't in this project.	Create the room first, in the same environment.

Production tips

Pick name in your backend, like a ticket id or room id. Don't use text users type.
Pass roomId when you create the conversation. You can't link a room later.
Use getOrCreate: true when two users might open the same chat at the same moment. Both get the same conversation instead of one getting a 409.

Next steps

Now that the conversation exists:

Members: add or remove people, and give moderators their role.
Chat authentication: make a token so each member's app can connect.
Messages: what users can do once they're in.