sitegpt-ai Messages API
The Messages API from sitegpt-ai — 3 operation(s) for messages.
The Messages API from sitegpt-ai — 3 operation(s) for messages.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/sitegpt-ai:sitegpt-ai-messages-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: SiteGPT Agent Messages API
version: 2.0.0
description: Agent-facing API for managing SiteGPT chatbots, dashboard summaries, appearance media, knowledge, settings, conversations, leads, members, account profiles, usage, billing reads, and API tokens.
servers:
- url: https://sitegpt.ai
security:
- bearerAuth: []
tags:
- name: Messages
paths:
/api/v2/chatbots/{chatbotId}/messages:
post:
operationId: sendMessageToNewConversation
summary: Send new message
description: 'Send a visitor message and start a new conversation.
Required scope: `conversations:write`.
On success, `data` contains: `conversation`, `message`, `awayMessage`.'
tags:
- Messages
security:
- bearerAuth:
- conversations:write
x-sitegpt-auth: bearer
x-sitegpt-scopes:
- conversations:write
x-mint:
title: Send new message
description: Send a visitor message and start a new conversation.
parameters:
- name: chatbotId
in: path
required: true
description: Chatbot ID.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- message
additionalProperties: false
properties:
message:
type: string
minLength: 1
pageUrl:
type:
- string
- 'null'
format: uri
example:
message: Can you explain your pricing?
responses:
'201':
description: Successful SiteGPT API v2 response.
content:
application/json:
schema:
type: object
required:
- ok
- data
- meta
properties:
ok:
type: boolean
const: true
data:
type: object
additionalProperties: true
properties:
conversation:
$ref: '#/components/schemas/Conversation'
message:
$ref: '#/components/schemas/Message'
awayMessage:
anyOf:
- $ref: '#/components/schemas/Message'
- type: 'null'
description: 'The away message this message got: set when the conversation is held by the team, outside the working hours of the chatbot, with an away message. Show its answer text to the visitor. Each conversation gets it one time, so later messages return null.'
meta:
$ref: '#/components/schemas/AgentResponseMeta'
additionalProperties: false
example:
ok: true
data:
message:
id: message-id
name: Example message
createdAt: '2026-05-13T00:00:00.000Z'
meta:
requestId: request-id
'400':
$ref: '#/components/responses/AgentError'
'401':
$ref: '#/components/responses/AgentError'
'403':
$ref: '#/components/responses/AgentError'
'404':
$ref: '#/components/responses/AgentError'
'405':
$ref: '#/components/responses/AgentError'
'409':
$ref: '#/components/responses/AgentError'
/api/v2/chatbots/{chatbotId}/conversations/{threadId}/messages:
get:
operationId: listConversationMessages
summary: List messages
description: 'List conversation messages.
Required scope: `conversations:read`.
On success, `data` contains: `messages`, `pagination`.'
tags:
- Messages
security:
- bearerAuth:
- conversations:read
x-sitegpt-auth: bearer
x-sitegpt-scopes:
- conversations:read
x-mint:
title: List messages
description: List conversation messages.
parameters:
- name: chatbotId
in: path
required: true
description: Chatbot ID.
schema:
type: string
- name: threadId
in: path
required: true
description: Conversation thread ID.
schema:
type: string
- name: limit
in: query
required: false
description: Maximum number of records to return.
schema:
type: integer
minimum: 1
- name: cursor
in: query
required: false
description: Pagination cursor.
schema:
type: string
responses:
'200':
description: Successful SiteGPT API v2 response.
content:
application/json:
schema:
type: object
required:
- ok
- data
- meta
properties:
ok:
type: boolean
const: true
data:
type: object
additionalProperties: true
properties:
messages:
type: array
items:
$ref: '#/components/schemas/Message'
pagination:
$ref: '#/components/schemas/Pagination'
meta:
$ref: '#/components/schemas/AgentResponseMeta'
additionalProperties: false
example:
ok: true
data:
messages:
- id: message-id
name: Example message
createdAt: '2026-05-13T00:00:00.000Z'
pagination:
limit: 20
hasNextPage: false
nextCursor: null
meta:
requestId: request-id
'400':
$ref: '#/components/responses/AgentError'
'401':
$ref: '#/components/responses/AgentError'
'403':
$ref: '#/components/responses/AgentError'
'404':
$ref: '#/components/responses/AgentError'
'405':
$ref: '#/components/responses/AgentError'
'503':
$ref: '#/components/responses/AgentError'
post:
operationId: sendConversationMessage
summary: Send message
description: 'Send a visitor message to an existing conversation.
Required scope: `conversations:write`.
On success, `data` contains: `message`, `awayMessage`.'
tags:
- Messages
security:
- bearerAuth:
- conversations:write
x-sitegpt-auth: bearer
x-sitegpt-scopes:
- conversations:write
x-mint:
title: Send message
description: Send a visitor message to an existing conversation.
parameters:
- name: chatbotId
in: path
required: true
description: Chatbot ID.
schema:
type: string
- name: threadId
in: path
required: true
description: Conversation thread ID.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- message
additionalProperties: false
properties:
message:
type: string
minLength: 1
pageUrl:
type:
- string
- 'null'
format: uri
example:
message: I have one more question.
responses:
'201':
description: Successful SiteGPT API v2 response.
content:
application/json:
schema:
type: object
required:
- ok
- data
- meta
properties:
ok:
type: boolean
const: true
data:
type: object
additionalProperties: true
properties:
message:
$ref: '#/components/schemas/Message'
awayMessage:
anyOf:
- $ref: '#/components/schemas/Message'
- type: 'null'
description: 'The away message this message got: set when the conversation is held by the team, outside the working hours of the chatbot, with an away message. Show its answer text to the visitor. Each conversation gets it one time, so later messages return null.'
meta:
$ref: '#/components/schemas/AgentResponseMeta'
additionalProperties: false
example:
ok: true
data:
message:
id: message-id
name: Example message
createdAt: '2026-05-13T00:00:00.000Z'
meta:
requestId: request-id
'400':
$ref: '#/components/responses/AgentError'
'401':
$ref: '#/components/responses/AgentError'
'403':
$ref: '#/components/responses/AgentError'
'404':
$ref: '#/components/responses/AgentError'
'405':
$ref: '#/components/responses/AgentError'
'409':
$ref: '#/components/responses/AgentError'
'429':
$ref: '#/components/responses/AgentError'
'503':
$ref: '#/components/responses/AgentError'
/api/v2/chatbots/{chatbotId}/conversations/{threadId}/messages/{messageId}:
patch:
operationId: updateConversationMessage
summary: Update message
description: 'React to or edit a conversation message.
Required scope: `conversations:write`.
On success, `data` contains: `message`.'
tags:
- Messages
security:
- bearerAuth:
- conversations:write
x-sitegpt-auth: bearer
x-sitegpt-scopes:
- conversations:write
x-mint:
title: Update message
description: React to or edit a conversation message.
parameters:
- name: chatbotId
in: path
required: true
description: Chatbot ID.
schema:
type: string
- name: threadId
in: path
required: true
description: Conversation thread ID.
schema:
type: string
- name: messageId
in: path
required: true
description: Message ID.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
reaction:
type: string
enum:
- NEGATIVE
- NEUTRAL
- POSITIVE
text:
type: string
example:
reaction: POSITIVE
responses:
'200':
description: Successful SiteGPT API v2 response.
content:
application/json:
schema:
type: object
required:
- ok
- data
- meta
properties:
ok:
type: boolean
const: true
data:
type: object
additionalProperties: true
properties:
message:
$ref: '#/components/schemas/Message'
meta:
$ref: '#/components/schemas/AgentResponseMeta'
additionalProperties: false
example:
ok: true
data:
message:
id: message-id
name: Example message
createdAt: '2026-05-13T00:00:00.000Z'
meta:
requestId: request-id
'400':
$ref: '#/components/responses/AgentError'
'401':
$ref: '#/components/responses/AgentError'
'403':
$ref: '#/components/responses/AgentError'
'404':
$ref: '#/components/responses/AgentError'
'405':
$ref: '#/components/responses/AgentError'
'503':
$ref: '#/components/responses/AgentError'
components:
schemas:
GenericObject:
type: object
additionalProperties: true
Message:
type: object
description: One stored conversation turn. NORMAL_MESSAGE carries the visitor question plus the AI answer; USER_MESSAGE and AGENT_MESSAGE carry one side of a human conversation; SYSTEM_MESSAGE records events such as escalation.
additionalProperties: true
properties:
messageId:
type: string
messageType:
type: string
description: NORMAL_MESSAGE, USER_MESSAGE, AGENT_MESSAGE, or SYSTEM_MESSAGE.
systemMessageType:
type:
- string
- 'null'
description: Set on SYSTEM_MESSAGE rows; null otherwise.
question:
anyOf:
- type: object
additionalProperties: true
properties:
text:
type: string
timestamp:
type: string
- type: 'null'
answer:
anyOf:
- type: object
additionalProperties: true
properties:
text:
type: string
timestamp:
type: string
- type: 'null'
reaction:
type: string
enum:
- POSITIVE
- NEGATIVE
- NEUTRAL
gptModel:
type:
- string
- 'null'
description: Public model label for AI answers; null on human turns.
sources:
type: array
items:
type: string
description: The page URL of each knowledge passage the AI was given for this answer, in retrieval order (best match first). A page with several passages appears several times. Answers sent through this API keep an empty string for each passage from uploaded files or text; answers from the chat widget leave those out.
agentId:
type:
- string
- 'null'
agentName:
type:
- string
- 'null'
iconUrl:
type:
- string
- 'null'
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
AgentError:
type: object
required:
- ok
- error
- meta
properties:
ok:
type: boolean
const: false
error:
type: object
required:
- code
- message
properties:
code:
type: string
message:
type: string
details: {}
additionalProperties: false
meta:
type: object
required:
- requestId
properties:
requestId:
type: string
additionalProperties: true
additionalProperties: false
AgentResponseMeta:
type: object
required:
- requestId
properties:
requestId:
type: string
warnings:
type: array
items:
type: string
nextCursor:
type:
- string
- 'null'
additionalProperties: true
ChatUser:
type: object
description: A website visitor identified through the chat widget.
additionalProperties: true
properties:
id:
type: string
name:
type: string
email:
type: string
phone:
type: string
verified:
type: boolean
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
Lead:
type: object
description: A captured lead. The top-level email convenience field is present on lead endpoints; conversation payloads embed the same record without it.
additionalProperties: true
properties:
id:
type: string
chatbotId:
type: string
chatUser:
$ref: '#/components/schemas/ChatUser'
name:
type: string
phone:
type: string
email:
type: string
description: Convenience copy of chatUser.email.
tags:
type: array
items:
type: string
customData:
$ref: '#/components/schemas/GenericObject'
description: Custom lead-form fields collected by the widget.
important:
type: boolean
archived:
type: boolean
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
Conversation:
type: object
description: A conversation thread between a visitor and the chatbot.
additionalProperties: true
properties:
threadId:
type: string
chatbotId:
type: string
mode:
type: string
enum:
- AI
- AGENT
description: AI answers automatically; AGENT means human takeover.
startedAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
endedAt:
type:
- string
- 'null'
format: date-time
escalated:
type: boolean
important:
type: boolean
resolved:
type: boolean
title:
type:
- string
- 'null'
tagIds:
type: array
items:
type: string
sessionId:
type:
- string
- 'null'
ipAddress:
type:
- string
- 'null'
pageUrl:
type:
- string
- 'null'
source:
type: string
enum:
- website
- api
- whatsapp
- messenger
- slack
- google_chat
- crisp
- freshdesk
- zoho_salesiq
- zendesk
- intercom
- email
description: 'Where the conversation started: website (the chat widget or the hosted chat page), api, or a connected channel.'
webhookUrl:
type:
- string
- 'null'
webhookTokenConfigured:
type: boolean
chatUserId:
type:
- string
- 'null'
chatUser:
anyOf:
- $ref: '#/components/schemas/ChatUser'
- type: 'null'
lead:
anyOf:
- $ref: '#/components/schemas/Lead'
- type: 'null'
totalMessages:
type: integer
totalPositiveMessages:
type: integer
totalNegativeMessages:
type: integer
totalGpt4MessagesCount:
type: integer
totalMessagesRead:
type: integer
totalMessagesReadByUser:
type: integer
unreadMessages:
type: integer
lastMessage:
anyOf:
- $ref: '#/components/schemas/Message'
- type: 'null'
messages:
type: array
items:
$ref: '#/components/schemas/Message'
description: Full message list; present on single-conversation reads and bulk action results, absent from list endpoints.
Pagination:
type: object
description: Cursor pagination state for paginated list endpoints.
additionalProperties: false
required:
- limit
- hasNextPage
- nextCursor
properties:
limit:
type: integer
description: Page size used.
hasNextPage:
type: boolean
nextCursor:
type:
- string
- 'null'
description: Pass as the cursor query parameter to fetch the next page. Null on the last page.
responses:
AgentError:
description: SiteGPT agent API error response.
content:
application/json:
schema:
$ref: '#/components/schemas/AgentError'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: SiteGPT API token