Skip to content
Totem APIDocs
ENEnglishESEspañol
Create API key
Beta

Reference Conversations

Create API key

Conversations

List and fetch a team's conversations on every channel, with their status, assignee, whether a person has taken them over and when the last messages came and went. Never message content.

Overview

A conversation is one thread with a lead, on one channel and business account: WhatsApp, email, the web chat (chatbot), Facebook, Instagram, SMS or TikTok. A lead can have several conversations on the same channel and business account, one for each contact address (phone number, email address or handle) it has used, so key your copy on the conversation's id. You get the conversation's metadata, never its messages:

  • channel_type: the channel, or null for a channel this version of the API does not know.
  • status: active or archived in the team's inbox.
  • assignee: the team member the conversation is assigned to, or null.
  • reply_mode: human while a person has taken the conversation over, including a WhatsApp chat answered from the WhatsApp Business app, and ai otherwise. ai means no takeover is active; it does not mean an assistant is set up or answering on that channel. A takeover with a time limit goes back to ai when it ends, and the conversation gets a new version then.
  • last_inbound_at and last_outbound_at: when the latest message came in from the customer, and when the latest message that did not fail went out to them. Erased messages, imported WhatsApp history and web-chat visitor messages do not count as inbound, so a chatbot conversation reads null there. Imported WhatsApp history does count as outbound.

The contact's name, phone number or handle travel on the linked lead, not on the conversation. For the picture across all of a lead's channels, read the lead's response facet with GET /v1/leads/{id}.

Use GET /v1/conversations and GET /v1/conversations/{id} to look conversations up; GET /v1/conversations?lead= lists one lead's conversations. To keep a copy, follow the changes feed: Keep a copy in sync explains it.

List conversations

GET /v1/conversations

Returns a page of the team's conversations, one per channel, business account and contact address: channel, inbox status, assignee and the times of the latest inbound and outbound messages. Pass lead for one lead's conversations. Message content is never exported.

Scopes
messages:read
Rate limit
Sync

Query parameters

  • limit integer Range 1–100 Default 25

    Items per page, 1–100. Defaults to 25.

  • cursor string 1–512 chars

    The next_cursor of the previous page. Omit it for the first page.

  • lead string ID prefix lead_…

    Only the conversations linked to this lead: every item's lead is this id. A lead of another team, or one that does not exist, matches nothing.

Headers

  • Totem-Team string Conditional ID prefix team_…

    The team to read, as a team_… id. Omit it when the key reads one team; it is required when the key reads several (400 team_required). When you send it, it must name a team the key reads: a malformed id gets 400 invalid_request, and a team outside the key gets 404 team_not_accessible, as does a request without it once the key reads no team at all.

Returns

Returns a list of Conversation objects.

  • object string

    Always list.

  • data Array<Conversation>

    The items of this page.

  • has_more boolean

    true when another page follows: fetch it with next_cursor, even if this page holds fewer items than limit.

  • next_cursor string Nullable

    Opaque cursor for the next page, or null on the last page. Never parse it.

Errors

+ 12 common errors

GET /v1/conversations
curl 'https://api.totemstudio.ai/v1/conversations?limit=25' \
  -H "Authorization: Bearer $TOTEM_API_KEY" \
  -H "Totem-Team: $TOTEM_TEAM_ID"
Response · 200JSON
{
  "object": "list",
  "data": [
    {
      "id": "conv_m3GhGjRHmFbww1g10oqOp7j3gWqPJ",
      "object": "conversation",
      "livemode": false,
      "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
      "lead": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
      "channel_type": "whatsapp",
      "status": "active",
      "assignee": "mem_h548E7UiYhutHhucVrQCzkM0eaea0",
      "reply_mode": "ai",
      "created_at": "2026-09-28T10:16:00.000Z",
      "last_inbound_at": "2026-10-01T08:58:00.000Z",
      "last_outbound_at": "2026-10-01T08:59:30.000Z",
      "version": 12,
      "updated_at": "2026-10-01T08:59:31.040Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Get a conversation

GET /v1/conversations/{id}

Returns one conversation by its id, without message content. A conversation this key cannot read, or one that was removed, answers 404 resource_missing.

Scopes
messages:read
Rate limit
Read

Path parameters

  • id string Required ID prefix conv_…

    The conversation's public id.

Returns

Returns a Conversation object.

Errors

+ 12 common errors

GET /v1/conversations/{id}
curl 'https://api.totemstudio.ai/v1/conversations/conv_m3GhGjRHmFbww1g10oqOp7j3gWqPJ' \
  -H "Authorization: Bearer $TOTEM_API_KEY"
Response · 200JSON
{
  "id": "conv_m3GhGjRHmFbww1g10oqOp7j3gWqPJ",
  "object": "conversation",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "lead": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "channel_type": "whatsapp",
  "status": "active",
  "assignee": "mem_h548E7UiYhutHhucVrQCzkM0eaea0",
  "reply_mode": "ai",
  "created_at": "2026-09-28T10:16:00.000Z",
  "last_inbound_at": "2026-10-01T08:58:00.000Z",
  "last_outbound_at": "2026-10-01T08:59:30.000Z",
  "version": 12,
  "updated_at": "2026-10-01T08:59:31.040Z"
}

The Conversation object

A conversation on one channel: its status, assignee and the times of the latest messages, never their content.

Attributes

  • id string ID prefix conv_…

    Public id of the record.

  • object string

    Always conversation.

  • livemode boolean

    true for real data; false in example data.

  • team string ID prefix team_…

    The team this record belongs to.

  • lead string Nullable ID prefix lead_…

    The lead this conversation is linked to, or null when it is unlinked or the lead no longer exists. Identity (name, phone, handle) travels on the lead only.

  • channel_type string Nullable

    The channel: whatsapp, email, chatbot (the web chat), facebook, instagram, sms or tiktok; null for a value this version does not know. A lead can have several conversations on the same channel and business account, one for each contact address (phone number, email address or handle) it has used, so key your copy on id.

    Possible values
    • sms
    • whatsapp
    • facebook
    • instagram
    • tiktok
    • chatbot
    • email
  • status string Nullable

    active or archived in the team's inbox; null for a value this version does not know.

    Possible values
    • active
    • archived
  • assignee string Nullable ID prefix mem_…

    The team member assigned to the conversation (see /members), or null.

  • reply_mode string

    human while a person has taken the conversation over, including a WhatsApp chat answered from the WhatsApp Business app; ai otherwise. ai means no takeover is active, not that an assistant is set up or answering on this channel. A timed takeover returns to ai when it expires, and the record's version changes then.

    Possible values
    • ai
    • human
  • created_at string Nullable Format date-time

    When the conversation was created (UTC).

  • last_inbound_at string Nullable Format date-time

    The latest customer message (UTC). Not counted: erased messages, imported WhatsApp history and web-chat visitor turns, so a chatbot conversation reads null. Instagram shares cannot be told apart and count.

  • last_outbound_at string Nullable Format date-time

    The latest message sent to the customer that did not fail (UTC), whoever sent it. Imported WhatsApp history counts.

  • version integer Range ≥ 1

    Increases every time one of the record's exported fields changes. Apply a change only when its version is greater than the one you hold.

  • updated_at string Format date-time

    When Totem recorded this version (UTC). It is not the time the business event happened.

Conversation · exampleJSON
{
  "id": "conv_m3GhGjRHmFbww1g10oqOp7j3gWqPJ",
  "object": "conversation",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "lead": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "channel_type": "whatsapp",
  "status": "active",
  "assignee": "mem_h548E7UiYhutHhucVrQCzkM0eaea0",
  "reply_mode": "ai",
  "created_at": "2026-09-28T10:16:00.000Z",
  "last_inbound_at": "2026-10-01T08:58:00.000Z",
  "last_outbound_at": "2026-10-01T08:59:30.000Z",
  "version": 12,
  "updated_at": "2026-10-01T08:59:31.040Z"
}

API version 1.0a