Conversations, messages, tags, and leads

These commands help support teams and AI agents inspect what visitors asked, follow up with messages, organize threads with tags, and maintain lead records. Most commands in this section require a chatbot ID:

sitegpt chatbots list

Conversations

Conversations are visitor chat threads.

sitegpt conversations --help

List conversations

sitegpt conversations list --chatbot <chatbot-id>
sitegpt conversations list --chatbot <chatbot-id> --json
sitegpt conversations list --chatbot <chatbot-id> --status open
sitegpt conversations list --chatbot <chatbot-id> --status resolved
sitegpt conversations list --chatbot <chatbot-id> --mode AI
sitegpt conversations list --chatbot <chatbot-id> --mode AGENT
sitegpt conversations list --chatbot <chatbot-id> --escalated true
sitegpt conversations list --chatbot <chatbot-id> --important true
sitegpt conversations list --chatbot <chatbot-id> --read false
sitegpt conversations list --chatbot <chatbot-id> --query "refund"
sitegpt conversations list --chatbot <chatbot-id> --tag <tag-id>

List filters:

Option	Values/default
`--status <status>`	`all`, `open`, `resolved`. Default: `all`.
`--mode <mode>`	`AI` or `AGENT`.
`--escalated <boolean>`	Filter escalated conversations.
`--important <boolean>`	Filter starred conversations.
`--read <boolean>`	Filter read/unread conversations.
`--lead <lead-id>`	Filter by linked lead.
`--query <text>`	Search conversation/user text.
`--tag <tag-id>`	Filter by tag. Repeatable.
`--include-empty`	Include empty threads.
`--limit <1-100>`	Default: `50`.
`--cursor <cursor>`	Continue pagination.

Use --json when an agent needs the complete thread ID. Human table output may shorten long IDs for readability.

Get one conversation

sitegpt conversations get --chatbot <chatbot-id> <thread-id>
sitegpt conversations get --chatbot <chatbot-id> <thread-id> --json

The response includes conversation metadata, visitor details, assigned tags, lead information, mode, state, and recent messages.

Update a conversation

sitegpt conversations update --chatbot <chatbot-id> <thread-id> --title "Pricing question"
sitegpt conversations update --chatbot <chatbot-id> <thread-id> --mode AGENT
sitegpt conversations update --chatbot <chatbot-id> <thread-id> --important true
sitegpt conversations update --chatbot <chatbot-id> <thread-id> --resolved true
sitegpt conversations update --chatbot <chatbot-id> <thread-id> --escalated true
sitegpt conversations update --chatbot <chatbot-id> <thread-id> --mark-read true
sitegpt conversations update --chatbot <chatbot-id> <thread-id> --email visitor@example.com --name "Jane Doe"
sitegpt conversations update --chatbot <chatbot-id> <thread-id> --phone "+15551234567"
sitegpt conversations update --chatbot <chatbot-id> <thread-id> --tag <tag-id> --tag <another-tag-id>

Update fields:

Option	Description
`--title <title>`	Set the conversation title.
`--mode <mode>`	`AI` or `AGENT`.
`--important <boolean>`	Star or unstar the conversation.
`--resolved <boolean>`	Resolve or reopen the conversation.
`--escalated <boolean>`	Mark escalation state.
`--mark-read <boolean>`	Mark read/unread.
`--tag <tag-id>`	Replace assigned tags with the provided tag IDs. Repeatable.
`--email <email>`	Update visitor email.
`--name <name>`	Update visitor name.
`--phone <phone>`	Update visitor phone.
`--webhook-url <url>`	Update conversation webhook URL.
`--webhook-token <token>`	Update conversation webhook token.

Quick conversation actions

sitegpt conversations star --chatbot <chatbot-id> <thread-id>
sitegpt conversations unstar --chatbot <chatbot-id> <thread-id>
sitegpt conversations resolve --chatbot <chatbot-id> <thread-id>
sitegpt conversations unresolve --chatbot <chatbot-id> <thread-id>
sitegpt conversations read --chatbot <chatbot-id> <thread-id>
sitegpt conversations unread --chatbot <chatbot-id> <thread-id>
sitegpt conversations escalate --chatbot <chatbot-id> <thread-id> --message "A human will follow up shortly."
sitegpt conversations switch-to-ai --chatbot <chatbot-id> <thread-id> --message "The AI assistant is back online."
sitegpt conversations delete --chatbot <chatbot-id> <thread-id> --yes

Bulk conversation actions

sitegpt conversations bulk --chatbot <chatbot-id> --action star <thread-id> <thread-id>
sitegpt conversations bulk --chatbot <chatbot-id> --action unstar <thread-id> <thread-id>
sitegpt conversations bulk --chatbot <chatbot-id> --action resolve <thread-id> <thread-id>
sitegpt conversations bulk --chatbot <chatbot-id> --action unresolve <thread-id> <thread-id>
sitegpt conversations bulk --chatbot <chatbot-id> --action mark-read <thread-id> <thread-id>
sitegpt conversations bulk --chatbot <chatbot-id> --action mark-unread <thread-id> <thread-id>
sitegpt conversations bulk --chatbot <chatbot-id> --action delete <thread-id> <thread-id> --yes

Bulk actions:

star, unstar, resolve, unresolve, mark-read, mark-unread, delete

Messages

Messages are individual entries inside a conversation.

sitegpt messages --help

List messages

sitegpt messages list --chatbot <chatbot-id> <thread-id>
sitegpt messages list --chatbot <chatbot-id> <thread-id> --limit 200
sitegpt messages list --chatbot <chatbot-id> <thread-id> --cursor <cursor>
sitegpt messages list --chatbot <chatbot-id> <thread-id> --json

Options:

Option	Values/default
`--limit <1-500>`	Default: `100`.
`--cursor <cursor>`	Continue pagination.

Send a visitor message

Send into an existing conversation:

sitegpt messages send --chatbot <chatbot-id> <thread-id> "Do you offer annual billing?"

Start a new conversation by omitting the thread ID:

sitegpt messages send --chatbot <chatbot-id> "What can you help me with?"

The CLI sends normal visitor/user messages. Agent and system messages are internal SiteGPT states and are not exposed as public sender options.

React to a message

sitegpt messages react --chatbot <chatbot-id> <thread-id> <message-id> POSITIVE
sitegpt messages react --chatbot <chatbot-id> <thread-id> <message-id> NEGATIVE
sitegpt messages react --chatbot <chatbot-id> <thread-id> <message-id> NEUTRAL

Edit a message

sitegpt messages edit --chatbot <chatbot-id> <thread-id> <message-id> "Updated message text"

Leads

Leads are visitor contact records collected by SiteGPT.

sitegpt leads --help

List leads

sitegpt leads list --chatbot <chatbot-id>
sitegpt leads list --chatbot <chatbot-id> --status open
sitegpt leads list --chatbot <chatbot-id> --status archived
sitegpt leads list --chatbot <chatbot-id> --important true
sitegpt leads list --chatbot <chatbot-id> --query "jane@example.com"

List filters:

Option	Values/default
`--status <status>`	`all`, `open`, `archived`. Default: `all`.
`--important <boolean>`	Filter starred leads.
`--query <text>`	Search name, email, phone, or notes.
`--limit <1-100>`	Default: `50`.
`--cursor <cursor>`	Continue pagination.

Get and update leads

sitegpt leads get --chatbot <chatbot-id> <lead-id>
sitegpt leads update --chatbot <chatbot-id> <lead-id> --name "Jane Doe"
sitegpt leads update --chatbot <chatbot-id> <lead-id> --phone "+15551234567"
sitegpt leads update --chatbot <chatbot-id> <lead-id> --important true
sitegpt leads update --chatbot <chatbot-id> <lead-id> --archived true

Quick lead actions

sitegpt leads star --chatbot <chatbot-id> <lead-id>
sitegpt leads unstar --chatbot <chatbot-id> <lead-id>
sitegpt leads archive --chatbot <chatbot-id> <lead-id>
sitegpt leads unarchive --chatbot <chatbot-id> <lead-id>
sitegpt leads delete --chatbot <chatbot-id> <lead-id> --yes

Bulk lead actions

sitegpt leads bulk --chatbot <chatbot-id> --action archive --lead <lead-id> --lead <lead-id>
sitegpt leads bulk --chatbot <chatbot-id> --action unarchive <lead-id> <lead-id>
sitegpt leads bulk --chatbot <chatbot-id> --action star <lead-id> <lead-id>
sitegpt leads bulk --chatbot <chatbot-id> --action unstar <lead-id> <lead-id>
sitegpt leads bulk --chatbot <chatbot-id> --action delete <lead-id> <lead-id> --yes

Bulk lead actions:

archive, unarchive, star, unstar, delete

--yes is required for bulk delete.

Get started

Chatbot setup

Operations

Agent playbooks

Reference

Conversations, messages, tags, and leads

Conversations

List conversations

Get one conversation

Update a conversation

Quick conversation actions

Bulk conversation actions

Messages

List messages

Send a visitor message

React to a message

Edit a message

Tags

Leads

List leads

Get and update leads

Quick lead actions

Bulk lead actions

Full reference

​Conversations

​List conversations

​Get one conversation

​Update a conversation

​Quick conversation actions

​Bulk conversation actions

​Messages

​List messages

​Send a visitor message

​React to a message

​Edit a message

​Tags

​Leads

​List leads

​Get and update leads

​Quick lead actions

​Bulk lead actions

​Full reference

Conversations

List conversations

Get one conversation

Update a conversation

Quick conversation actions

Bulk conversation actions

Messages

List messages

Send a visitor message

React to a message

Edit a message

Tags

Leads

List leads

Get and update leads

Quick lead actions

Bulk lead actions

Full reference