Conversations

A conversation is a single thread with one contact on one channel (WhatsApp, SMS, or email). Outbound sends and inbound replies are grouped into the same conversation, so you can read the full back and forth in order.

List conversations

Cursor-paginated, newest activity first. Each summary carries the channel, status, and when the last message arrived:

list.ts

const page = await bt.conversations.list({ limit: 50 });

for (const conv of page.data) {
  console.log(conv.id, conv.channel, conv.status, conv.last_message_at);
}
// page.next_cursor / page.has_more drive pagination

Get one conversation

Fetch a single conversation to see the contact it belongs to and its assignment state:

get.ts

const conv = await bt.conversations.get("conv_123");
console.log(conv.id, conv.status); // "open" | "pending" | "resolved"

Read the messages

The conversation summary does not include message bodies — read those from the messages endpoint. Messages come back oldest-first and are cursor-paginated:

messages.ts

const messages = await bt.conversations.messages("conv_123", { limit: 100 });

for (const m of messages.data) {
  // m.direction: "inbound" | "outbound"
  // m.body, m.status, m.created_at
  console.log(m.direction, m.body);
}

React to inbound replies

Do not poll for new replies. When a customer messages you, Blueticked fires the message.received webhook. Use the event to learn that a reply arrived, then read the body from the messages endpoint:

app/api/blueticked/route.ts (Next.js)

const event = await bt.webhooks.constructEvent(
  rawBody,
  req.headers.get("x-blueticked-signature") ?? "",
  process.env.BLUETICKED_WEBHOOK_SECRET!,
);

if (event.event === "message.received") {
  // The inbound message is in the contact's conversation —
  // read the latest messages to get the body.
  const recent = await bt.conversations.messages(conversationId, { limit: 1 });
  const inbound = recent.data.find((m) => m.direction === "inbound");
  // ... route it to your inbox, trigger an auto-reply, etc.
}

Replying and triage

Replies are sent with messages.send, not through the conversation object. You can assign, resolve, or reopen a conversation with bt.conversations.update(id, { status }) — useful when a human agent picks up a thread.