Skip to main content
Use these commands to review what visitors asked, test your chatbot, move conversations between the AI and your team, and keep your leads in order. A conversation is all the messages between one visitor and the chatbot or your team. The CLI calls the conversation ID <thread-id> in its help. On this page it is YOUR_CONVERSATION_ID. This page shows the common path for each task. For every option, see the command reference: Conversations, Messages, Tags, and Leads.

​
Before you start

  • The Growth plan or above, on your own account or on the account that owns the chatbot. See Which plan applies.
  • The CLI installed and logged in. See Install and log in. The default access from sitegpt login is enough for the tasks on this page.
  • Your chatbot ID. Run sitegpt chatbots list to find it.

​
Find conversations

Common filters:
  • --status is all, open, or resolved. The default is all.
  • --mode is AI or AGENT (human mode).
  • --escalated, --important, and --read take true or false.
  • --query searches the conversation text. --tag filters by tag ID.
  • --include-empty also lists conversations with no messages.
The table shortens the visitor email and the last message. Add --json when a script or an AI agent reads the result. Check that it works: The CLI lists the matching conversations. If none match, it prints No conversations found.

​
Read a conversation

1

Get the summary

The output shows the title, the mode, the resolved, important, and escalated state, the tags, the message counts, the visitor email, and the last message.
2

Read the messages

--limit can be from 1 to 500. The default is 100. If there are more messages, the CLI prints Next cursor. Pass it with --cursor to get the next part.
Check that it works: The message list shows the ID, type, reaction, question, and answer of each message. With --json, each message also has sources. This is the content that SiteGPT gave the AI for the answer, not the links that the answer cites. See Message sources.

​
Test the chatbot with a message

Start a new conversation:
To send a message in a conversation that already exists, put the conversation ID before the text:
The CLI sends every message as the visitor. You cannot send a team member reply from the CLI. In AI mode, the CLI waits for the chatbot reply. In human mode, SiteGPT saves the message and the AI does not reply. Outside working hours, with Your team answers later, --json shows your away message in awayMessage. If the conversation reached its message limit, the command fails with MESSAGE_LIMIT_REACHED. Start a new conversation. Check that it works: The CLI prints Started conversation with the IDs, then the chatbot answer.

​
Resolve, star, or mark a conversation as read

The other quick actions work the same way: unresolve, star, unstar, read, and unread. To star a conversation is to mark it as important. Check that it works: The CLI prints resolve applied to conversation YOUR_CONVERSATION_ID. conversations get shows Resolved: yes.

​
Hand a conversation to your team

This escalates the conversation. It moves to human mode and SiteGPT adds a system message to it. --message sets the text of that message. If you leave it out, SiteGPT uses a default text. The command fails if the conversation is resolved. It also fails if a team member has taken it over and it is not already escalated. See Conversations and handoff. Check that it works: The CLI prints Escalated conversation YOUR_CONVERSATION_ID. conversations get shows Escalated: yes.

​
Release a conversation to the AI

If your team holds the conversation, it goes back to AI mode and SiteGPT adds a system message. If the AI already answers it, nothing changes and no message is added. With --json, switched is then false. --message works as for escalate. The command fails on a resolved conversation. Check that it works: The CLI prints switch-to-ai applied to conversation YOUR_CONVERSATION_ID. conversations get shows Mode: AI.

​
Update the visitor details

--name and --phone need --email in the same command. conversations update can also change the title, the mode, the tags, and the states. See Conversations. Check that it works: The CLI prints Updated conversation YOUR_CONVERSATION_ID. conversations get shows the new visitor email.

​
Act on many conversations at once

1

Do a dry run

A dry run prints the action and the IDs, and changes nothing. It does not contact SiteGPT, so it does not check that the IDs exist.
2

Run the action

Run the same command without --dry-run.
The actions are star, unstar, resolve, unresolve, mark-read, mark-unread, and delete. You can pass up to 100 conversation IDs. delete needs --yes. Check that it works: The CLI prints the action and the number of conversations, for example resolve applied to 2 conversations.

​
Delete a conversation

Check that it works: The CLI prints Deleted conversation YOUR_CONVERSATION_ID.

​
Tag conversations

Tags belong to a chatbot, so every tag command needs --chatbot.
1

Create a tag

The CLI prints the new tag ID. To see the tags you have, run sitegpt tags list --chatbot YOUR_CHATBOT_ID.
2

Add the tag to a conversation

--tag replaces all tags on the conversation. To keep the other tags, pass them too. Repeat --tag for each tag.
Check that it works: sitegpt conversations list --chatbot YOUR_CHATBOT_ID --tag YOUR_TAG_ID lists the conversation.

​
Rate or edit a message

Rate a message as POSITIVE, NEGATIVE, or NEUTRAL:
Change the text of a message:
Check that it works: The CLI prints Updated reaction for message YOUR_MESSAGE_ID. or Edited message YOUR_MESSAGE_ID.

​
Find leads

A lead is the contact details that a visitor gives in the chat. See Manage leads.
--status is all, open, or archived. The default is all. --query searches the name, email, and phone. --important true lists starred leads. To see one lead, run sitegpt leads get --chatbot YOUR_CHATBOT_ID YOUR_LEAD_ID. Check that it works: The CLI lists the matching leads. If none match, it prints No leads found.

​
Update, star, or archive a lead

The other quick actions are unarchive, star, and unstar. Check that it works: sitegpt leads get --chatbot YOUR_CHATBOT_ID YOUR_LEAD_ID shows the new name and Archived: yes.

​
Act on many leads at once

The actions are archive, unarchive, star, unstar, and delete. A dry run prints the action and the lead IDs and changes nothing. It does not contact SiteGPT. Run the command again without --dry-run to apply it. delete needs --yes. Check that it works: The CLI prints the action and the number of leads, for example archive applied to 2 leads.

​
Delete a lead

Check that it works: The CLI prints Deleted lead YOUR_LEAD_ID.