Browse all guides

Get started Getting started

Add it to your site Install on WordPress Install on Shopify Install on Wix Webflow, Squarespace, Framer and more

Knowledge Add your knowledge Fix unanswered questions

Channels Website chat widget Telegram bot Telegram moderation and group tools Discord bot Discord moderation and tools Proactive replies and welcomes Talking to a person Email (beta)

Web3 projects Web3 project setup Holder verification GitHub, OpenAPI, MCP and llms.txt

Account and usage Plans and billing Usage and analytics AI models and languages Team members Account and security Privacy and your data Emails we send you Partner program for agencies Not available yet

Developers Chat API

Chat API

Send a message and get an answer from your own code.

Every plan For developers

The Chat API sends a message to your agent and returns its answer, using the same knowledge and rules as your widget. Use it to add answers to your own app, help centre or internal tools.

Authentication

Use your key from API Key, sent as a header:

X-Tenant-Api-Key: your-api-key

You can also pass it as a query parameter, ?api-key=your-api-key. This is the same key your website widget uses, so treat it as public and regenerate it if it's misused.

Send a message

curl -X POST https://aidevelopia.com/api/chat \
  -H "X-Tenant-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are your opening hours?", "session_id": "user-123"}'

Field	Type	Notes
`message`	string, required	The question. Up to 2,000 characters.
`session_id`	string, optional	Send the same value on follow-ups to keep the conversation. Up to 255 characters. If you leave it out, one is created and returned.
`page_url`	string, optional	The page the user is on, if it helps the answer.

The response

{
  "response": "We're open Monday to Friday, 9am to 6pm.",
  "session_id": "user-123",
  "rating_token": "…",
  "escalation_offer": false,
  "escalation_offer_reason": null,
  "sources": [],
  "branding": { "primary_color": "#0a0a0a", "avatar_url": null, "chatbot_name": "My Bot", "welcome_message": "Hello!" },
  "usage": { "chat_limit": 500, "current_chats": 42 }
}

sources lists where the answer came from.
escalation_offer is true when the agent suggests handing over to a person.
If a person on your team has taken over the conversation, you get {"response": null, "human_mode": true, "session_id": "…"}.
chat_limit of -1 means unlimited.

Limits and errors

Status	When
`401`	The key is missing, wrong or was deleted.
`422`	The request is invalid, for example `message` is missing or longer than 2,000 characters. The `errors` field says which field and why.
`403`	The workspace has been turned off.
`429`	More than 10 messages a minute in one session, or 30 a minute from one IP address. Also returned when you've used your monthly chats.

Every answer through the API counts as a chat, the same as on your website.

Still stuck? Send us a message or email support@aidevelopia.com.