API Reference
Overview
💬Get free consultation

API Reference

ⓘ

Who can use this feature?

  • The storefront SDK works on any plan and needs no key.
  • An API key is required for the GraphQL Customer API, the Chat Conversations API, webhook management, and API-key MCP. Creating an API key requires an admin on Pro or Plus. The Public API uses an explicit scoped key; merchant MCP can also use OAuth.

Start here

"I want Chatty to talk to the rest of my stack — where do I begin?" There are seven ways in, and they are not interchangeable. Picking the wrong one usually means the code works, but it can never do the thing you actually wanted.

Read the two tables below, then check Common wrong picks. Five minutes here saves a rebuild.

How much of this you can do yourself. Creating the API key takes a minute and needs no code: follow Generate your API key below. What happens after that splits in two. If the tool you're connecting has a setup screen that asks for a Chatty API key, paste the key there and you're done. If it doesn't, someone has to write the code that calls Chatty, so plan on a developer.

If you're looking for ready-made integrations without code, see Klaviyo, Zendesk, or Joy instead.


What each one does

WayWhat it doesWhat it can't doRead more
Built-in integrationsConnect Chatty to apps such as Klaviyo, Zendesk, Joy, Gorgias, Powerful Contact Form, and SEA Survey, or to a non-Shopify website. You fill in a form in the app.Anything the guide for that app doesn't list. There's no way to extend one.Integrations
Storefront SDKControl the chat widget on your storefront: open or close it, prefill or send a message, pass customer and cart context, react to what the visitor does in chat.Read past conversations, run on your server, or change settings saved in the app. It only exists in the shopper's browser.Storefront SDK
Chat Conversations APIRead and write conversations from your own systems: list and fetch conversations and messages, send replies, resolve, assign, tag, add notes and attributes, read customers, members, and tags.Push anything to you — you ask, it answers. It also can't change widget settings. Each endpoint needs the matching permission on your key.Chat Conversations API
Public APIManage settings, knowledge, customers, conversations, team, channels, integrations, and translations; export data; read analytics; send email and files; ask AI with saved multi-turn context.Work with a legacy unscoped key. It uses a different base path from the Chat Conversations API.Public API
WebhooksTell your server the moment something happens: 11 events across messages, conversations, and customer profiles, with delivery logs and redelivery.Give you history, and it can't reply. To answer, your server calls the Chat Conversations API.Webhooks
GraphQL Customer APIRead the contacts Chatty collected — names, emails, channels, order counts, total spend, chat activity — with exactly the fields you ask for.Write anything. It's read-only, and it doesn't return message content.GraphQL Customer API
MCP serverLet an AI assistant you run — your own bot, or a tool such as Claude — discover your store's tools, look up a product, an order, or an FAQ, and post its reply into the conversation.Act as a general-purpose API. The assistant only gets the tools allowed by its scopes, authentication mode, and enabled features.MCP server

Two pages apply to every API above: Authentication explains how credentials work, and Errors and rate limits covers what to do when a request fails.


Pick by what you want to do

You want to…Use
Connect a tool that already has a Chatty guideBuilt-in integrations — no code, no key
Copy conversations into a helpdesk, database, or spreadsheetChat Conversations API
React the moment a new message arrivesWebhooks to hear it, Chat Conversations API to reply
Reply to customers from a tool your team already usesChat Conversations API
Open the chatbox from your own button, or prefill a messageStorefront SDK
Pass the logged-in customer, the cart, or the current product into chatStorefront SDK
Export contacts to a CRM, an email platform, or a CSVGraphQL Customer API, or customer export for an emailed CSV
Let your own AI assistant read and answer conversationsMCP server
Build a report on chat volume and outcomesAnalytics for ready-made reports, Chat Conversations API for conversations, GraphQL Customer API for customers
Add Chatty to a website that isn't your Shopify storeWebsite integration

Common wrong picks

Each pair below looks like the same job. It isn't.

Chat Conversations API vs Webhooks

The API answers when you ask. Webhooks speak when something happens. If your feature is "within seconds of a customer message, do X", polling the API on a timer is the wrong shape: you either poll too often and hit the limit, or too rarely and arrive late. Subscribe to message.created instead, and call the API only to fetch detail and to reply.

Storefront SDK vs Chat Conversations API

The SDK runs in the shopper's browser and touches only that shopper's live widget. The API runs on your server and sees every conversation in your store. Anything involving history, other customers, or work that must happen while nobody is on the site belongs to the API. Anything about what the widget does on the page belongs to the SDK.

MCP server vs Chat Conversations API

Both can post a reply. The difference is who decides. With MCP, an AI assistant is handed a set of tools and picks which to call. With the API, your code decides and calls a fixed path. If there's no model in the loop, MCP adds a layer you don't need.

GraphQL Customer API vs Chat Conversations API

"Customer" appears in both. GraphQL returns people and their totals, and nothing else — it's read-only and has no message content. The Chat Conversations API returns the conversations and the messages themselves. Wanting "everything about this shopper" usually means both.

Built-in integration vs building your own

Check Integrations before you scope any development. If a guide already exists for the tool you're connecting, that path is a form in the app, not a project.

The public API vs the paths in your browser

The admin inbox in your browser calls near-identical paths under /api/chat/..., authenticated with your admin session. Those are not the public API and an API key won't work on them. The /chat paths carry no /api prefix: https://app.chatty.net/chat/conversations.


Plans, credentials, and limits

WayPlanNeeds a developerCredentialsLimits worth knowing
Built-in integrationsSee the guide for each appNoNoneSet in the app
Storefront SDKAny planYes, to add JavaScript to your themeNoneRuns only where the widget is loaded
Chat Conversations APIPro or PlusYesX-Api-Key: sk_...120 requests/min per key, 300 requests/min per IP
Public APIPro or PlusYesX-Api-Key with explicit scopes120 requests/min per key, 300 per IP; AI ask adds 20/min per key
WebhooksPro or PlusYesX-Api-Key: sk_... to manage subscriptions10 subscriptions per store; 10-second delivery timeout; up to 7 attempts over about 9 hours
GraphQL Customer APIPro or PlusYesX-Api-Key: sk_...Read-only; 300 requests/min per IP; a query costs up to 500 points from a 2,000-point store budget that refills at 100 points per second
MCP serverPro or Plus for an API key; OAuth has no plan checkYesX-App-Id and Authorization: Bearer sk_..., or an OAuth access tokenTools are filtered by permissions, authentication mode, and enabled features

You can keep up to 5 active API keys per store, and the same sk_ key works across the Chat Conversations API, webhooks, MCP, and GraphQL. The Chat Conversations API, webhooks, and GraphQL read it from X-Api-Key. MCP reads it from Authorization: Bearer, with your App ID in X-App-Id. See Authentication for the details.


Generate your API key

Sign in as an admin to manage API keys in Settings → General → Manage keys.

Create an API key

Under Permissions, tick what the key needs, for example Read conversations or Read customers. A key with nothing ticked is refused on every Chat Conversations API and webhook call. Then enter a name in Key name. Name it after the tool that will use it, for example Zendesk sync. The name can be up to 50 characters. Then click Generate key.

The Manage keys panel with the Key name field and the Generate key button

The new key appears in your list with the full sk_ value visible.

The new key shown in full, with a banner reminding you to copy it now

!

Copy the key before you leave the page. Chatty stores only a hash of it, so the full key can never be shown again. If you lose it, delete the key and create a new one.

You can keep up to 5 active keys per store. Create one per integration so you can delete a single key without breaking the others.

ⓘ

A new key takes up to 30 seconds to start working. A deleted key stops on its next request. A 401 on your first request right after creating a key is expected. Wait and try again before you go looking for a bug in your code.

ⓘ

Creating and managing keys requires an admin on the Pro or Plus plan. On other plans the panel is replaced by a note with an upgrade link.

Find your App ID

Your App ID sits at the top of the same panel. Some tools call it a Client ID. It identifies your store, and some integrations need it alongside your key.

The App ID field at the top of the Manage keys panel


Two things that surprise people

A conversation list can look shorter than your inbox. The conversation list reflects the store's primary conversation store. Older conversations that predate it don't appear in the list, but you can still fetch them one by one by id. Build any reconciliation on ids you already hold, not on the assumption that the list is complete.

A message you just sent may not appear immediately. Chatty writes messages to a live layer first and syncs them after, so a read taken instantly after a write can come back without it. Don't treat "not in the list yet" as "failed".


See Settings and features to configure Chatty, Ask AI for multi-turn answers, and the CRM integration example for a complete workflow.

What you can build

Export contacts to a spreadsheet
Use the GraphQL customers query with pagination to pull all contacts, then write them to a CSV.

Sync high-value customers to an email platform
The customers query has no filter, so page through all contacts and keep those with a high totalSpent. Push them to your email tool via its own API.

Alert your team on every new customer message
Subscribe to the message.created webhook, act only when senderType is customer, and notify your team.

Embed chat actions in your storefront
Use the SDK to open the chatbox from a custom button or prefill a message.


Need help?

If you're still unsure which way fits, contact the Chatty support team from your dashboard. Tell them what you want to happen, where it should happen (the storefront, your server, or another tool), and whether a developer is available. That's enough to point you at the right page.