💬Get free consultation

Quick reference

How to read this page

One row per callable thing. Writes says whether the row changes data in your store. Auth names the credential. Plan is the minimum plan. Nothing here is explained — the linked page carries the detail.

---

Chat Conversations API

Base URL https://app.chatty.net. Full detail: Chat Conversations API.

Name	Area	What it does	Writes	Auth	Plan
GET /chat/conversations	Chat API	Lists conversations, newest activity first	No	X-Api-Key	Pro or Plus
GET /chat/conversations/{id}	Chat API	Returns one conversation in full	No	X-Api-Key	Pro or Plus
GET /chat/conversations/{id}/messages	Chat API	Lists messages in a conversation	No	X-Api-Key	Pro or Plus
POST /chat/conversations/{id}/messages	Chat API	Sends a reply, an internal note, or a message as the customer	Yes	X-Api-Key	Pro or Plus
GET /chat/conversations/{id}/messages/{messageId}	Chat API	Returns one message, deleted ones included	No	X-Api-Key	Pro or Plus
GET /chat/conversations/{id}/related	Chat API	Lists other conversations from the same contact	No	X-Api-Key	Pro or Plus
POST /chat/conversations/{id}/tags	Chat API	Appends tags, deduped	Yes	X-Api-Key	Pro or Plus
DELETE /chat/conversations/{id}/tags/{tag}	Chat API	Removes one tag	Yes	X-Api-Key	Pro or Plus
POST /chat/conversations/{id}/notes	Chat API	Adds a checklist note	Yes	X-Api-Key	Pro or Plus
PUT /chat/conversations/{id}/notes/{noteId}	Chat API	Updates a checklist note	Yes	X-Api-Key	Pro or Plus
DELETE /chat/conversations/{id}/notes/{noteId}	Chat API	Deletes a checklist note	Yes	X-Api-Key	Pro or Plus
GET /chat/conversations/{id}/attributes	Chat API	Lists conversation attributes	No	X-Api-Key	Pro or Plus
POST /chat/conversations/{id}/attributes	Chat API	Creates an attribute, upserts by name	Yes	X-Api-Key	Pro or Plus
PUT /chat/conversations/{id}/attributes/{attributeId}	Chat API	Updates an attribute	Yes	X-Api-Key	Pro or Plus
DELETE /chat/conversations/{id}/attributes/{attributeId}	Chat API	Deletes an attribute	Yes	X-Api-Key	Pro or Plus
POST /chat/conversations/{id}/state	Chat API	Resolves or reopens a conversation	Yes	X-Api-Key	Pro or Plus
POST /chat/conversations/{id}/assign	Chat API	Assigns a conversation to a team member	Yes	X-Api-Key	Pro or Plus
POST /chat/conversations/{id}/read	Chat API	Marks a conversation read on the agent side	Yes	X-Api-Key	Pro or Plus
POST /chat/conversations/{id}/typing	Chat API	Sets the agent typing indicator	Yes	X-Api-Key	Pro or Plus
GET /chat/conversations/{id}/browsed-pages	Chat API	Lists pages the visitor viewed this session	No	X-Api-Key	Pro or Plus
GET /chat/conversations/{id}/summary	Chat API	Returns the AI summary of a resolved conversation	No	X-Api-Key	Pro or Plus
GET /chat/customers/{customerUuid}	Chat API	Returns a contact profile	No	X-Api-Key	Pro or Plus
GET /chat/customers/{customerUuid}/conversations	Chat API	Lists one contact's conversations	No	X-Api-Key	Pro or Plus
GET /chat/members	Chat API	Lists team members	No	X-Api-Key	Pro or Plus
GET /chat/members/{memberId}	Chat API	Returns one team member	No	X-Api-Key	Pro or Plus
GET /chat/tags	Chat API	Returns your store's tag catalog	No	X-Api-Key	Pro or Plus
GET /chat/webhooks	Chat API	Lists webhook subscriptions, signing secrets included	No	X-Api-Key	Pro or Plus
POST /chat/webhooks	Chat API	Creates a subscription, upserts by URL	Yes	X-Api-Key	Pro or Plus
PUT /chat/webhooks/{id}	Chat API	Updates a subscription, including pausing and resuming delivery	Yes	X-Api-Key	Pro or Plus
DELETE /chat/webhooks/{id}	Chat API	Deletes a subscription	Yes	X-Api-Key	Pro or Plus

The public API carries no /api prefix. Paths under /api/chat/... belong to the admin inbox and reject an X-Api-Key.

The Pro or Plus column above is the plan you need to hold an API key at all. Once you have a key, only one action re-checks the plan: turning a paused webhook subscription back on. Pausing one works on any plan, so a store that downgraded while paused cannot resume delivery. See Webhooks.

---

Webhook events

These nine names are the complete set. Full detail: Webhooks.

Name	Area	What it does	Writes	Auth	Plan
message.created	Webhooks	Fires when a customer, an agent, or the AI sends a message	No	whsec_ signature	Pro or Plus
message.updated	Webhooks	Fires when a message is edited	No	whsec_ signature	Pro or Plus
message.removed	Webhooks	Fires when a message is deleted	No	whsec_ signature	Pro or Plus
conversation.created	Webhooks	Fires when a new conversation starts	No	whsec_ signature	Pro or Plus
conversation.state_changed	Webhooks	Fires when a conversation is resolved or reopened	No	whsec_ signature	Pro or Plus
conversation.assigned	Webhooks	Fires when a conversation is assigned or reassigned	No	whsec_ signature	Pro or Plus
conversation.tags_updated	Webhooks	Fires when tags change, carrying the full resulting list	No	whsec_ signature	Pro or Plus
conversation.removed	Webhooks	Fires when a conversation is deleted	No	whsec_ signature	Pro or Plus
customer.created	Webhooks	Fires when a new contact record is created	No	whsec_ signature	Pro or Plus

---

GraphQL Customer API

Endpoint POST https://graphql.chatty.net/graphql. Read-only: no mutation, no subscription. Full detail: GraphQL Customer API.

Name	Area	What it does	Writes	Auth	Plan
customer(id)	GraphQL	Fetches one contact by id, null when nothing matches	No	x-api-id + x-api-secret	Pro or Plus
customers(first, after, last, before)	GraphQL	Lists contacts with Relay cursor pagination, no filter or sort	No	x-api-id + x-api-secret	Pro or Plus

---

MCP tools

Endpoint POST https://app.chatty.net/mcp. Eight tools are always registered, nine depend on a switch read fresh on every request. Call tools/list after connecting rather than trusting a list. Full detail: MCP tool reference.

The Plan column is the plan the switch needs. Creating the key itself needs Pro or Plus, so that is the floor for every row.

Name	Area	What it does	Writes	Auth	Plan	Switch
send_message	MCP	Posts a bot reply into a conversation	Yes	X-App-Id + Bearer key	All	Always on
faq_retrieval	MCP	Searches your knowledge base	No	X-App-Id + Bearer key	All	Always on
add_note	MCP	Adds an internal note to a conversation	Yes	X-App-Id + Bearer key	All	Always on
update_tags	MCP	Replaces the whole tag list on a conversation	Yes	X-App-Id + Bearer key	All	Always on
assign_member	MCP	Assigns or unassigns a team member	Yes	X-App-Id + Bearer key	All	Always on
list_members	MCP	Lists team members and their ids	No	X-App-Id + Bearer key	All	Always on
list_conversations	MCP	Lists test conversations from the AI playground	No	X-App-Id + Bearer key	All	Always on
register_webhook	MCP	Creates a subscription and returns its signing secret	Yes	X-App-Id + Bearer key	All	Always on
product_lookup	MCP	Searches products and variants	No	X-App-Id + Bearer key	All	Training data > Products
product_faq_lookup	MCP	Returns FAQs for one product	No	X-App-Id + Bearer key	All	Training data > Products
manage_cart	MCP	Reads and edits the Shopify cart	Yes, except action: "get"	X-App-Id + Bearer key	All	Training data > Products
collection_lookup	MCP	Searches collections and categories	No	X-App-Id + Bearer key	All	Training data > Collections
discount_lookup	MCP	Finds discounts and promo codes	No	X-App-Id + Bearer key	All	Training data > Discounts
size_guide_lookup	MCP	Returns a size chart for one product	No	X-App-Id + Bearer key	Pro	Assistant skills > Size guide
check_order_status	MCP	Tracks an order by order number or tracking number	No	X-App-Id + Bearer key	Basic	Assistant skills > Order tracking
customer_support	MCP	Runs an after-sale request: return, refund, cancel, edit	No	X-App-Id + Bearer key	All	Assistant skills > After-sale support
human_agent_transfer	MCP	Hands the conversation to a person	No	X-App-Id + Bearer key	All	Assistant skills > Human handover

A store that has never touched its AI agent settings exposes 11 tools: the 8 always-on ones plus order tracking, after-sale support, and human handover.

---

Storefront SDK

Global object window.$chatty, version 1.1.0, no credentials. Full detail: SDK Reference and SDK Events.

Name	Area	What it does	Writes	Auth	Plan
Methods (6)	SDK	push, on, off, is, get, version	No	None	Any
do widget visibility (7)	SDK	chat:open, chat:close, chat:toggle, chat:show, chat:hide, launcher:show, launcher:hide	No	None	Any
do messaging (2)	SDK	message:send, typing:set	Yes	None	Any
do identity and session (3)	SDK	identify, logout, session:reset	Yes	None	Any
do conversation control (3)	SDK	escalate, trigger:run, article:show	Yes	None	Any
do pre-chat form (2)	SDK	prechat:submit, prechat:skip	Yes	None	Any
do custom event tracking (1)	SDK	event:track	Yes	None	Any
set composer and visitor data (8)	SDK	message:text, user:email, user:name, user:phone, user:attributes, user:context, shop:data, conversation:attributes	Yes	None	Any
set commerce context (3)	SDK	product, cart, order	Yes	None	Any
set locale (1)	SDK	locale	Yes	None	Any
set pre-chat prefill (1)	SDK	prechat:field	Yes	None	Any
States (7)	SDK	is(key) reads a boolean: chat, session, pre-chat, and agent availability	No	None	Any
Values (5)	SDK	get(key) reads composer text, conversation id, unread count, pre-chat config, commerce context	No	None	Any
Events (22)	SDK	Lifecycle, messages, conversation, pre-chat and lead capture, presence and typing	No	None	Any

Eighteen do actions and thirteen set actions in total. The SDK returns no value and throws nothing, so a rejected command is silent.

---

Limits

The full list lives on Errors and rate limits.

Where	Limit
Chat Conversations API	120 requests/min per key, 300 requests/min per source IP
Chat Conversations API pages	conversations 20 / 100, messages 50 / 100, related 6 / 50, customer conversations 20 / 100
Chat Conversations API message	5,000 characters of text
Chat Conversations API note	150 characters
Chat Conversations API tag	100 characters, longer tags are dropped from the request
Chat Conversations API attribute	name 255 characters, value 1,000 characters
Chat Conversations API browsed pages	the 50 most recent pages of the session, kept about 24 hours
API keys	5 active keys per store
Webhook subscriptions	10 per store
Webhook delivery	10-second timeout, 7 attempts over about 9 hours
Webhook payload	data is replaced above 80,000 bytes, metadata is rejected above 2,048 bytes
GraphQL Customer API	metered by query cost, budget not published, no rate limit headers
MCP server	no request rate limit
MCP update_tags	50 characters per tag, longer tags are truncated silently, 100 tags kept per conversation
MCP list_conversations	limit defaults to 20 and has no maximum, so ask for a page size you can handle
SDK message sending	15 messages/min, 5,000 characters each
SDK typing indicator	30 calls/min
SDK commerce context	8 KB per object

---

Where to go next

You want	Page
Parameters, payloads, and cURL for every path above	Chat Conversations API
Event payloads, signature verification, and retries	Webhooks
Schema, enums, and pagination	GraphQL Customer API
Connection, client setup, and security	MCP overview
Tool parameters and return shapes	MCP tool reference
Command arguments, states, and values	SDK Reference
Event names and payloads	SDK Events
Which header each API expects	Authentication
Every limit and error format	Errors and rate limits
Choosing between these surfaces	API Reference overview

---

Need help?

Contact the Chatty support team from your dashboard. Include the row you were calling, the timestamp of a failing request, and the returned error code.