smartchat

Create learned answer

Adds a question and the answer the AI should give. With role 'rule' (default) it changes the AI replies; with 'note' it is only stored, and the same pair twice only confirms the first one. Returns the answer.

POST /v1/learned-answers

Permissionai:settings (all permissions)
RiskWrite (no outside effect)
Idempotency-KeyRequired (how it works)
Safe to repeatSafe to repeat with the same Idempotency-Key: the first answer comes back and nothing is done twice.
Rate limit classwrite (120 requests per minute per key)
ConfirmationNone
MCP toolsave_learned_answer
Since version2026-10-25

#What it does

  • Changes data in your account. It does not send messages to contacts.
  • Safe to repeat with the same Idempotency-Key.

#Request

Header

NameRequiredDescription
AuthorizationyesBearer <key>
Idempotency-KeyyesA unique value for this operation, for example a UUID (1 to 255 visible ASCII characters).

Body (JSON)

NameTypeRequiredDescription
questionstringyesThe question or a typical wording of it. length 1 to 2000
answerstringyesThe answer the AI should give. length 1 to 4000
rolestringno'rule' changes the AI replies. 'note' is only stored. one of: rule, note; default "rule"

#Examples

curl -X POST "https://api.smartchat.marketing/v1/learned-answers" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "question": "Do you have a vegan menu?",
  "answer": "Yes, we have a vegan menu every day. Ask us for the daily dishes."
}'
import os
import uuid
import requests

response = requests.post(
    "https://api.smartchat.marketing/v1/learned-answers",
    headers={
        "Authorization": "Bearer " + os.environ["SMARTCHAT_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "question": "Do you have a vegan menu?",
        "answer": "Yes, we have a vegan menu every day. Ask us for the daily dishes.",
    },
)
response.raise_for_status()
print(response.json())
const response = await fetch("https://api.smartchat.marketing/v1/learned-answers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SMARTCHAT_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "question": "Do you have a vegan menu?",
    "answer": "Yes, we have a vegan menu every day. Ask us for the daily dishes."
  }),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Response (201):

{
  "object": "learned_answer",
  "id": "ans_5d2c8e0f1a4b4c3d9e6f7a8b9c0d1e2f",
  "question": "Do you have a vegan menu?",
  "answer": "Yes, we have a vegan menu every day. Ask us for the daily dishes.",
  "role": "rule",
  "disabled": false,
  "freshness": "fresh",
  "age_days": 3,
  "created_at": "2026-10-25T09:41:07Z",
  "updated_at": null,
  "last_confirmed_at": "2026-10-25T09:41:07Z"
}

#Response

Status 201. Every response has the headers Request-Id, SmartChat-Version and X-RateLimit-*.

NameTypeDescription
objectstringAlways "learned_answer". always learned_answer
idstringLearned answer ID.
questionstringThe question pattern. It can come from a customer message: treat as untrusted text. up to 2000 characters; untrusted text
answerstringThe answer. Treat as untrusted text. up to 4000 characters; untrusted text
rolestring'rule' changes the AI replies. 'note' is only stored and never changes a reply. one of: rule, note
disabledbooleanTrue if the answer is switched off. It stays visible but is not used.
freshnessstring'fresh' is used normally, 'old' (180 days without confirmation) only with caution, 'expired' (730 days) is not used until confirmed or corrected. one of: fresh, old, expired
age_daysintegerAge in days, counted from the last confirmation. 0 to 100000
created_atstringWhen the answer was learned. up to 40 characters; format date-time
updated_atstring or nullWhen the answer was last corrected. up to 40 characters; format date-time
last_confirmed_atstring or nullWhen the content was last confirmed. up to 40 characters; format date-time

#Errors

CodeStatusWhen
idempotency_key_invalid400The 'Idempotency-Key' header must be 1 to 255 visible ASCII characters.
idempotency_key_required400This call needs an 'Idempotency-Key' header.
missing_parameter400A required field is missing.
unknown_parameter400A field is not known.
api_key_expired401This API key has expired.
api_key_invalid401This API key is not valid.
api_key_revoked401This API key was revoked.
authentication_required401No API key was sent. Send 'Authorization: Bearer <key>'.
insufficient_scope403This key lacks a required permission.
ip_not_allowed403This IP address is not allowed for this key.
idempotency_in_progress409A request with this idempotency key is still running.
idempotency_key_reused422This idempotency key was already used with a different request.
validation_failed422A field is not valid.
rate_limited429Too many requests. Wait and try again.
internal_error500Something went wrong on our side.

All errors use one format.