Marking outbound chat messages as AI-authored with `auto`

API: Chat Conversations v2.1

Endpoint: POST /v2.1/chat/outbound/messages

Authentication: Authorization: Bearer <API token>

Permission: org.permission.message.create

When a bring-your-own chatbot sends a reply on this route, set the optional auto field to true. Every request on this route is attributed to the org user in from. auto: true stores that message as AI- or automation-authored. If an SLA metric has Based on human interaction turned on, that reply does not satisfy the metrics with the option on: First Response, Next Reply, or both.

Omit auto and nothing changes. Existing integrations do not need a migration.

When to send auto

auto is accepted only on POST /v2.1/chat/outbound/messages.

What auto stores

auto is an optional boolean. The API rejects any other JSON type, including the string "true", with 400 bad_request.

Omitting the field is valid and is the backward-compatible behavior. false is for callers that want the attribute present and set to not-automation. For SLA purposes the two are the same: the message can count as a human reply.

The stored value is the message auto attribute. On that attribute, false means the message was created manually. Search and queue-rule criteria can filter these messages with message_auto.

How auto affects SLA timers

Based on human interaction is a boolean on each metric of an SLA policy version. A policy can enable it on one metric and leave it off on the other. Read the active version from GET /v1/slas/{id}?versions=active (versions is active or all). The booleans are on the included SLA version:

• attributes.metrics.firstResponse.basedOnHumanInteraction for First Response Time
• attributes.metrics.nextReply.basedOnHumanInteraction for Next Reply Time

nextReply is present when that metric is configured. basedOnHumanInteraction can be omitted. Omitted and false are the same.

The chat route documents auto: true as exclusion from human-interaction First Response and related denorms. Next Reply uses the same human-authored rule when its own flag is on.

Note: Longest Unresponded Message, Total Conversation Open Time, and Total Customer Wait Time do not have this option.

A reply can satisfy First Response or Next Reply only when it is a successfully sent, customer-visible outbound message. Drafts, internal notes, system events, and failed sends do not satisfy either metric.

The API does not infer that a person typed the message.

On this route every request is attributed to the org user in from. With the option on, a chatbot reply that omits auto (or sends false) still satisfies the timer, because it is stored as not automation-authored. That is the case auto: true is for.

Next Reply is recurring: each new customer inbound starts a cycle, and a qualifying outbound satisfies that cycle. First Response is one-shot. Turning the option on for only one of them changes only that metric.

More on the setting: Understanding Next Reply Time SLA, section Basing Next Reply Time on human interaction.

Request

POST https://api.kustomerapp.com/v2.1/chat/outbound/messages

Authorization: Bearer

Content-Type: application/json

customerId and from are always required. Also send session plus at least one of body or attachments. Sending both body and attachments is valid. Unknown top-level properties are rejected. meta (maximum 100 properties) and messageTemplate allow additional properties.

Other optional fields on this route are unchanged: id, brand, campaign, maybeInitialOutbound, createNewConversation, responseButtons, messageTemplate, meta, externalId, importedAt, createdAt, and sentAt. The optional message id is a string supplied by the client. It is not an ObjectId.

Chatbot reply

{
  "customerId": "55d7998f2d3f9f8800099aee",
  "from": "5679792fbc351e1d007a2994",
  "session": "5679792fbc351e1d007a2993",
  "body": "Here is the answer from our chatbot.",
  "auto": true
}

Human agent reply

Leave auto out. Send false only when you want the attribute stored as false.

{
  "customerId": "55d7998f2d3f9f8800099aee",
  "from": "5679792fbc351e1d007a2994",
  "session": "5679792fbc351e1d007a2993",
  "body": "Thanks. We are looking into your order."
}

Response

A successful create returns 201 and a chat_message resource. When the request includes auto, the created message includes it on data.attributes.auto.

{
  "data": {
    "type": "chat_message",
    "id": "507f1f77bcf86cd799439013",
    "attributes": {
      "body": "Here is the answer from our chatbot.",
      "direction": "out",
      "auto": true,
      "createdAt": "2026-07-15T13:32:00.000Z"
    }
  }
}

Errors

The error body is an errors array. Each item has a code, a message, and a meta object. Branch on code. The message string in the sample is the documented shape; validation text can be more specific.

{
  "errors": [
    {
      "code": "bad_request",
      "message": "Invalid request parameters",
      "meta": {}
    }
  ]
}

Troubleshooting

Check a test message

1. Send a chatbot request with "auto": true.
2. Confirm the 201 body has data.attributes.auto set to true.
3. On a policy that has Based on human interaction enabled, confirm that reply does not satisfy First Response, Next Reply, or both — whichever metrics have the option on.
4. Send a follow-up from a human agent with auto omitted. That message can satisfy the metric.

auto is not a field on other Chat Conversations routes, and it is not part of the native or web chat SDKs. The typing route's ai flag only changes the typing indicator. It does not mark a message.

meta.isAiResponse is a separate metadata flag on this same request. Setting it does not set auto and does not change human-interaction SLA behavior. Send auto when the reply should be treated as automation-authored.

Assistant outbound instead of auto

POST /v2.1/chat/outbound/assistant/messages creates an assistant line and stores it as automation-authored. It still requires customerId and from. It does not accept auto. Sending auto on that route is a 400, because the field is not in the schema and unknown properties are rejected. It accepts exactly one content mode: session plus body, session plus meta.template, or session plus attachments.

Use the assistant route when the reply should be an assistant message. Use auto on the agent route when the reply should be a normal agent outbound message that is also automation-authored. The agent route is the one that can send body and attachments together, along with messageTemplate and responseButtons.

FAQ

What is the difference between omitting auto and sending false?

Both are not automation-authored, so both can satisfy a human-interaction metric. Omitting auto leaves data.attributes.auto unset. false stores false. On the message attribute, false means the message was created manually.

Does auto: true stop every SLA timer?

No. It changes First Response and Next Reply only when that metric's Based on human interaction option is on. With the option off, an auto: true message still counts as a customer-visible sent outbound reply. Longest Unresponded Message, Total Conversation Open Time, and Total Customer Wait Time do not have this option.

Can I set auto from the chat SDK?

No. auto is accepted only on POST /v2.1/chat/outbound/messages. The native and web chat SDKs do not send it. The typing route's ai flag only changes the typing indicator.