get_support_conversation

Read one support conversation with its message history and the member context a reply needs.

Purpose

Open a single conversation. Returns the thread's state, its message history, and a flattened snapshot of who the member is — subscription status, current plan, member-since date, how many messages they have sent — so a reply can be written without a second round of lookups.

Names, emails and message bodies are returned verbatim. This is the most PII-dense tool in the set. Do not forward its output anywhere outside the conversation with the creator.

Required ability

support-conversation:view

Reading internal notes additionally requires support-conversation:update — see the caveats.

Input schema

{
  "type": "object",
  "required": ["conversation_id"],
  "properties": {
    "conversation_id": {
      "type": "string",
      "description": "UUID of the support conversation to read."
    },
    "message_limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "How many of the most recent messages to return (1..200, default 50). Returned oldest-first."
    },
    "include_internal": {
      "type": "boolean",
      "description": "Include creator-only internal notes. Requires the support-conversation:update ability."
    }
  }
}

Output shape

{
  "data": {
    "conversation": {
      "id": "sup_01HX...",
      "project_id": "prj_01HX...",
      "channel": "telegram",
      "status": "open",
      "assigned_to_user_id": null,
      "unread_count": 2,
      "blocked": false,
      "first_response_at": null,
      "resolved_at": null
    },
    "member": {
      "project_user_id": "usr_01HX...",
      "name": "Jane Doe",
      "email": "[email protected]",
      "status": "active",
      "member_since": "2026-03-02T09:00:00Z",
      "plan_name": "Premium Monthly",
      "subscription_status": "active",
      "subscription_ends_at": "2026-09-02T09:00:00Z",
      "subscription_count": 1,
      "inbound_message_count": 4,
      "first_contact_at": "2026-08-20T10:05:00Z"
    },
    "messages": [
      {
        "id": "smg_01HX...",
        "direction": "inbound",
        "author_kind": "contact",
        "type": "text",
        "delivery_status": "sent",
        "internal": false,
        "body": "My invite link expired before I could join",
        "attachment_kinds": [],
        "created_at": "2026-08-20T10:05:00Z"
      }
    ]
  },
  "meta": {
    "message_count": 1,
    "message_limit": 50,
    "internal_included": false
  }
}

Example prompts

"Open support conversation sup_01HX... and summarise what the member needs."

"Read the last 10 messages in that thread — is this a billing problem or an access problem?"

Failure modes

No support conversation found with that id. — unknown id, or the conversation belongs to a project outside the token's scope.
Reading internal notes requires the support-conversation:update ability. — include_internal was true on a read-only token.
TOKEN_MISSING_ABILITY — token lacks support-conversation:view.

Caveats

Internal notes are gated behind a write ability on purpose. Reading a private remark about a member takes the same permission as writing one, so a read-only token cannot see them.
Attachments are described by kind only (attachment_kinds: ["photo"]). Telegram file_id values are effectively download credentials and are never returned. Fetch files through the dashboard or the REST API.
messages is the newest message_limit messages, returned oldest-first so it reads as a transcript. A long thread is truncated at the start, not the end.
member.status is the project-scoped member status — it can be lead for someone who has never paid. Anyone who can reach the bot can open a conversation.
first_response_at: null means nobody has replied yet. It is stamped once, on the first human reply ever, and is not reset by a reopen.

get_support_conversation

On this page