# info.summary
Start a visitor chat session from an authorised domain, send messages, and stream the assistant's replies.

# info.description
The API behind the Line chat widget. Use it to embed Line chat in your own
front end instead of loading `/widget/v1.js`.

Two credentials are involved. The **public key** identifies the widget and is
safe to ship in client code. `POST /session` exchanges it for a short-lived
**session token** that authorises the rest of the conversation.

Every request is checked against the widget's allowed-domains list using the
`Origin` header, so calls must come from a browser on an authorised domain.
Requests are rate limited per visitor, per IP and per organisation.

# tags[].description
Load the widget and open a conversation.

# components.securitySchemes.widgetSession.description
Session token returned by `POST /api/channels/webchat/session`. Valid for one hour.

# paths./api/channels/webchat/session.get.description
Returns the presentation settings for a widget so you can render the launcher before anyone starts a conversation. No session is created.

# paths./api/channels/webchat/session.get.parameters[].description
Must match one of the widget's allowed domains.

# paths./api/channels/webchat/session.get.responses.200.content.application/json.schema.properties.widget.description
Presentation settings the tenant configured for this widget.

# paths./api/channels/webchat/session.get.responses.403.description
The `Origin` is not on the widget's allowed-domains list.

# paths./api/channels/webchat/session.post.description
Opens a conversation for a visitor and returns a session token plus the transcript so far, including the assistant's greeting.

# paths./api/channels/webchat/session.post.requestBody.description
Identifies the widget and the visitor, plus optional attribution.

# paths./api/channels/webchat/session.post.requestBody.content.application/json.schema.properties.visitorId.description
Your own stable identifier for this visitor. Reuse it to resume their conversation.

# paths./api/channels/webchat/session.post.requestBody.content.application/json.schema.properties.utm.description
Campaign parameters stored against the conversation.

# paths./api/channels/webchat/session.post.responses.200.description
The session token and the transcript so far.

# paths./api/channels/webchat/session.post.responses.200.content.application/json.schema.properties.widget.description
Presentation settings the tenant configured for this widget.

# paths./api/channels/webchat/session.post.responses.200.content.application/json.schema.properties.handoverState.description
Who is answering. `ai` — the assistant. `queued` — waiting on a teammate. `human` — a teammate has taken over. `deferred` — nobody was available and the visitor was asked to leave a message. `closed` — the conversation has ended.

# paths./api/channels/webchat/session.post.responses.200.content.application/json.schema.properties.messages.items.properties.sender.description
`agent` is the AI assistant, `operator` a human on the Line team inbox, `system` a handover notice.

# paths./api/channels/webchat/session.post.responses.403.description
The `Origin` is not on the widget's allowed-domains list.

# paths./api/channels/webchat/message.post.description
Sends a visitor message and streams the response as Server-Sent Events.

Event names:
- `received` — the message was stored.
- `delta` — `{ text }`, a chunk of the assistant's reply. Concatenate in order.
- `message` — `{ body, sender }`, the complete reply.
- `handover` — `{ state }`, a human is taking over or the reply needs approval.
- `error` — `{ message }`, the reply failed. The stream then closes.

A conversation in `queued` or `human` state emits only `handover`; poll
`GET /api/channels/webchat/events` for what the operator says next.

# paths./api/channels/webchat/message.post.responses.200.content.text/event-stream.example
event: received
data: {"ok":true}

event: delta
data: {"text":"Yes — "}

event: message
data: {"body":"Yes — every Line number is a real UK number.","sender":"agent","turn":1}

# paths./api/channels/webchat/message.post.responses.401.description
The session token is missing, expired or does not match.

# paths./api/channels/webchat/message.post.responses.403.description
The `Origin` is not on the widget's allowed-domains list.

# paths./api/channels/webchat/message.post.responses.413.description
The message is longer than 2000 characters.

# paths./api/channels/webchat/events.get.description
Returns the transcript and the current handover state. Pass `since` to fetch only what arrived after a timestamp — this is how you receive replies typed by a human operator.

# paths./api/channels/webchat/events.get.parameters[].description
Return only messages created strictly after this timestamp.

# paths./api/channels/webchat/events.get.responses.200.content.application/json.schema.properties.handoverState.description
Who is answering. `ai` — the assistant. `queued` — waiting on a teammate. `human` — a teammate has taken over. `deferred` — nobody was available and the visitor was asked to leave a message. `closed` — the conversation has ended.

# paths./api/channels/webchat/events.get.responses.200.content.application/json.schema.properties.messages.items.properties.sender.description
`agent` is the AI assistant, `operator` a human on the Line team inbox, `system` a handover notice.

# paths./api/channels/webchat/events.get.responses.401.description
The session token is missing, expired or does not match.

# paths./api/channels/webchat/events.get.responses.403.description
The `Origin` is not on the widget's allowed-domains list.