Ask AI

ⓘ

Who can use this feature?

An admin on Pro or Plus can create the API key. The key needs conversations:write.
The store's AI assistant must be enabled and have available AI usage.

Use POST /ai/ask on the Public API base URL. This endpoint generates an answer and saves both sides of the turn in Chatty. It is separate from sending a reply to an existing livechat conversation.

Request

Send X-Api-Key and Content-Type: application/json.

Field	Required	Meaning
`message`	Yes	Nonblank text, at most 5,000 characters before trimming.
`conversationId`	No	Omit for the first turn. For a follow-up, copy the ID returned by a previous successful `/ai/ask` call.
`customer`	No	First-turn contact details: optional `email`, `phone`, and `name`. An email must be valid. This does not update the contact on later turns.

curl -s -X POST "https://app.chatty.net/v1/ai/ask" \
  -H "X-Api-Key: $CHATTY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"What is your return policy?","customer":{"name":"Example customer","email":"[email protected]"}}'

Example 200 response:

{
  "data": {
    "answer": "Here is the return policy for this store.",
    "conversationId": "conv_123",
    "sources": {},
    "traceId": "trace_123",
    "handoffRequested": false
  }
}

answer depends on your store's knowledge. sources contains the returned source data and may be empty. traceId may be null. handoffRequested reports that the AI requested a human; it is not a receipt that someone accepted or completed the handoff.

Continue the conversation

Save data.conversationId against the CRM thread, then pass it with the next question:

curl -s -X POST "https://app.chatty.net/v1/ai/ask" \
  -H "X-Api-Key: $CHATTY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversationId":"conv_123","message":"Does that also apply to discounted items?"}'

The response uses the same shape. Chatty loads up to 30 recent messages, excluding notes and other internal content, to prepare the follow-up. A resolved public-API conversation is reopened when it receives another turn.

Use an ID returned by this endpoint. A missing conversation, a conversation from another store, or an ordinary livechat conversation returns 404 NOT_FOUND. A webhook's conversationId is not automatically a valid AI session. Keep the livechat ID and the AI session ID separately.

The first turn creates a conversation without a delivery channel. The answer is returned to your server and saved in Chatty; it is not automatically emailed or sent into the original customer's livechat. To send a reviewed answer there, use Chat Conversations API.

Errors and quotas

HTTP	Code	What to do
`400`	`VALIDATION_FAILED`	Correct the message, customer email, or ID shape.
`401`	`UNAUTHENTICATED` / `INVALID_API_KEY`	Check the API key and header.
`402`	`AI_USAGE_LIMIT_REACHED`	Stop automated AI retries and route the request to your team. Resume after usage becomes available.
`403`	`AI_DISABLED`	Enable the AI assistant before trying again.
`403`	`FORBIDDEN`	Grant `conversations:write` to this scoped key.
`404`	`NOT_FOUND`	Check that this is an AI session from the same store. Do not silently start a new session and lose context.
`429`	`RATE_LIMITED`	Wait and retry with backoff; rate-limit windows are 60 seconds. This endpoint permits 20 questions/min per key in addition to the shared Public API limits.
`500`	`EMPTY_AI_ANSWER`	No nonblank answer was produced. Do not show an empty reply as a success.
`500`	`INTERNAL_ERROR`	The AI provider or another service failed. Check saved messages before retrying an uncertain request.

Quota failure example:

{"error":{"code":"AI_USAGE_LIMIT_REACHED","message":"AI usage limit reached"}}

The enabled/usage checks run before generating or saving a turn. Billing usage is finalized through the conversation lifecycle, not incremented once for every question. A successful turn does not guarantee that the next one has quota.

This write has no idempotency key. Retrying after a timeout can create another turn, or another conversation if you omitted conversationId. See the CRM integration example and Errors and rate limits.

Use MCP

ask_ai exposes message and optional conversationId through MCP. API-key calls can also supply customer; OAuth calls ignore that field and do not attach the supplied customer identity. Both need conversations:write; OAuth also checks the member's current conversation-edit permission. Its result is an MCP tool response rather than a raw HTTP response. Check errors before saving the returned session ID. See the MCP tool reference.

Help Center CRM Integration