Chatbot API
A chatbot API for your own apps, backends and data
The intoCHAT REST API lets your server talk to the agent you trained in the dashboard. Send a message and get the same reply the chat widget would give, read conversations and leads, keep contacts in sync, add knowledge and subscribe webhooks, with JSON over HTTPS and an OpenAPI 3.1 spec that describes every endpoint.
Your chatbot shouldn't stop at the website widget
The widget covers visitors on your website. But the same questions arrive in your mobile app, your customer portal, an internal tool or a support form, and the conversations and leads the agent collects belong in your CRM, your data warehouse or your ticketing system, not only in a dashboard. Rebuilding the bot for every place means a second knowledge base and a second set of rules that slowly drift apart. A chatbot API lets every channel you build use the one agent you already trained, and lets your own systems read what it learned.
What the chatbot API gives you
One agent, trained once, answering wherever your code runs.
Same agent, same answers
A reply through the API is written by the same code as a reply in the widget, from the same knowledge, instructions and model. Your API actions, custom buttons, chat forms and booking work in API chats too.
Conversations that continue
Pass your own sessionId, such as your user ID, and the same person always continues the same conversation. The agent sees the last 40 messages as history, and every API chat appears on the Conversations tab next to the widget chats.
Your data in your systems
Page through conversations with full transcripts, leads with their custom fields, and contacts, newest first, with a since parameter for incremental syncs. The order is fixed, so nothing is read twice or skipped while new chats come in.
A scoped key for each job
Give each integration its own key with only the scopes it needs, for example conversations:read for a reporting job and chat for your app. Keys belong to the account, not to a person, and stop working the moment you revoke them.
An OpenAPI spec to start from
Every endpoint, field, error and webhook body is described in one OpenAPI 3.1 file. Import it into Postman or Insomnia, or generate a client library with a tool such as OpenAPI Generator.
How to start with the chatbot API
Train your agent
Create the agent in the dashboard, add your website, files or Q&A, and set its instructions and model. The API uses the agent exactly as it is configured there; agents are created and changed in the dashboard, not through the API.
Create an API key
In the sidebar, under Settings, click API keys. Name the key, keep Every scope, including ones added later or choose Only the scopes I choose, and click Create key. Copy the key, which starts with ic_live_, into an environment variable on your server: it is shown only once.
Send your first message
POST the message to /api/v1/agents/{agentId}/chat with the key as a Bearer token in the Authorization header. The JSON response has the reply, the conversationId and sessionId to continue with, the sources it drew on and any follow-up questions, buttons, products, forms or booking times. Set stream to true to receive the text as it is written.
Sync and subscribe
Read conversations, leads and contacts on a schedule with since, add text snippets or Q&A pairs as your content changes, and subscribe a webhook to events such as lead.created or handoff.requested, so they reach your server the moment they happen.
Chatbot API details
Send a message
The chat endpoint takes a message of up to 10,000 characters, an optional conversationId or sessionId to continue a conversation, stream for streamed text and timeZone for booking times. Without either ID, every message starts a new conversation.
Structured reply fields
Besides the reply in Markdown, the response lists the pages it drew on, suggested follow-ups, custom buttons, product cards with price and availability, an offered chat form or lead form, open booking times, rich-reply blocks such as tables and cards, and the live chat state.
Aware of live chat
When someone on your team has taken over the conversation in the Live chat inbox, your message is saved, the reply is empty and liveChat says paused. Read your teammate's replies, with their first name, from the conversation endpoint. Those messages use none of your plan's messages.
Conversations and Inbox
List an agent’s conversations from the widget and the API with topics, sentiment, live chat state and CSAT score, filter them by Inbox status, and fetch one with every message. With conversations:write you set its Inbox status, priority, tags and assignee.
Leads and contacts
List leads with name, email, phone and your custom form fields. Create or update contacts by your own external ID or by email, each with up to 50 custom attributes, so the agent's contacts match the users in your app.
Knowledge you can update
List an agent’s sources with their training status, add a text snippet or a Q&A pair, which starts training right away, and delete a source together with what the agent learned from it. A Q&A pair with the same question is updated instead of duplicated.
Webhooks and events
Subscribe up to 25 webhooks per agent to events such as lead.created, form.submitted, booking.created, handoff.requested and conversation.status_changed, each signed with its own secret. Or poll the latest events of one kind, shaped exactly like a webhook delivery.
Clear limits and errors
Each key can make 60 requests a minute, and every response carries X-RateLimit headers. Errors share one JSON shape with a stable code, such as insufficient_scope, rate_limited or message_limit_reached, so your code can handle each case.
Frequently asked questions
What is a chatbot API?
A chatbot API lets your own software send messages to a chatbot and get its replies, instead of only through a chat window on a website. intoCHAT's REST API does that for the agent you trained in the dashboard, and also lets your server read its conversations, leads and contacts, update its knowledge and subscribe to its events.
Which plan do I need for the API?
The API is included on Starter, Pro and Enterprise. On Free you can’t create keys. If an account moves back to Free, its existing keys answer every request with a plan_required error, and work again as soon as the account is on Starter or higher.
Do API replies count as messages?
Yes. Each reply the agent writes through the API counts on your plan exactly like a reply in the widget: one message with the default model, more with a larger model, and toward the agent’s monthly message cap if you set one. Reading conversations, leads and contacts, and adding or deleting sources, uses no messages.
Can I call the API from a browser or my embed code?
No. The API is for servers: it sends no CORS headers, and a key in a web page could be copied by anyone. To show a chat on your site, use the script tag or the JavaScript SDK, and call the API from your backend. Only the OpenAPI spec can be loaded from any site.
How do I continue a conversation?
Send the conversationId of an earlier reply, or your own sessionId, such as your user ID: the same sessionId always continues the same conversation. Only conversations started through the API can be continued through it, and the agent sees the last 40 messages as history.
What are the rate limits?
Each key can make 60 requests a minute across all endpoints, and an account can have up to 20 active keys. An agent answers at most 1,000 messages an hour, widget and API together, and a reply has to finish within 55 seconds, or the request ends with a timeout error.
What can't the API do yet?
There are no endpoints yet to create or change agents, submit chat forms, book meetings or take over live chats. Sources added through the API are text snippets and Q&A pairs; website pages, files and Notion pages are added in the dashboard. API messages can't carry files, and client actions, which run in a visitor's browser, aren't offered in API chats.
How is this different from AI actions?
They go in opposite directions. With AI actions, the agent calls your API during a chat to look something up, such as an order or an account. With the chatbot API, your server calls intoCHAT to send messages and read data. Many setups use both.
Build on the agent you already trained
Create your agent free and train it on your website, then upgrade to Starter, create an API key and send your first message with a single curl command.
Create your agent freeFree plan, no credit card needed.