Webchat Widget API

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

v1.0.0OpenAPI 3.1.0Download the OpenAPI 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.

Base URL

https://useline.io
get/api/channels/webchat/session
Read a widget's public configuration

Returns the presentation settings for a widget so you can render the launcher before anyone starts a conversation. No session is created.

Parameters

keyquery · stringrequired

The widget's public key.

Originheader · string · urirequired

Must match one of the widget's allowed domains.

Response

200The widget's public configuration.application/json
widgetobjectrequired

Presentation settings the tenant configured for this widget.

colourstring

Accent colour as a CSS hex value.

positionstring

One of: left, right

launcherTextstring
avatarUrlstring | null · uri
assistantNamestring

Errors

400
The key parameter is missing.
403
The Origin is not on the widget's allowed-domains list.
404
No enabled widget matches that key.

Example request

curl -X GET 'https://useline.io/api/channels/webchat/session' \
  -H 'Origin: https://example.com'
post/api/channels/webchat/session
Start a conversation

Opens a conversation for a visitor and returns a session token plus the transcript so far, including the assistant's greeting.

Request body

Identifies the widget and the visitor, plus optional attribution.

keystringrequired

The widget's public key.

visitorIdstringrequired

Your own stable identifier for this visitor. Reuse it to resume their conversation.

pageUrlstring · uri
referrerstring · uri
utmobject

Campaign parameters stored against the conversation.

{
  "key": "pk_live_2f8c…",
  "visitorId": "b6e1f0c2-4f0a-4f7c-9a1d-2c2f7c5f9b10",
  "pageUrl": "https://example.com/pricing"
}

Response

200The session token and the transcript so far.application/json
tokenstringrequired

Bearer token for the other calls.

sessionIdstring · uuidrequired
expiresInintegerrequired

Token lifetime in seconds.

widgetobject

Presentation settings the tenant configured for this widget.

colourstring

Accent colour as a CSS hex value.

positionstring

One of: left, right

launcherTextstring
avatarUrlstring | null · uri
assistantNamestring
handoverStatestringrequired

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.

One of: ai, queued, human, deferred, closed

messagesarray of objectrequired

Errors

400
key or visitorId is missing.
403
The Origin is not on the widget's allowed-domains list.
404
No enabled widget matches that key.
429
Rate limited. Back off and retry.

Example request

curl -X POST 'https://useline.io/api/channels/webchat/session' \
  -H 'Origin: https://example.com' \
  -H 'Content-Type: application/json' \
  -d '{"key":"pk_live_2f8c…","visitorId":"b6e1f0c2-4f0a-4f7c-9a1d-2c2f7c5f9b10","pageUrl":"https://example.com/pricing"}'
post/api/channels/webchat/messagesession token
Send a message and stream the reply

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.

Request body

messagestringrequired

The visitor's message.

{
  "message": "Do you offer UK mobile numbers?"
}

Response

200An SSE stream of the reply.text/event-stream
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}

Errors

400
The message is empty.
401
The session token is missing, expired or does not match.
403
The Origin is not on the widget's allowed-domains list.
413
The message is longer than 2000 characters.
429
Rate limited. Back off and retry.

Example request

curl -X POST 'https://useline.io/api/channels/webchat/message' \
  -H 'Authorization: Bearer $LINE_SESSION_TOKEN' \
  -H 'Origin: https://example.com' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Do you offer UK mobile numbers?"}'
get/api/channels/webchat/eventssession token
Poll for new messages

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.

Parameters

sincequery · string · date-time

Return only messages created strictly after this timestamp.

Response

200The transcript and handover state.application/json
handoverStatestringrequired

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.

One of: ai, queued, human, deferred, closed

messagesarray of objectrequired

Errors

401
The session token is missing, expired or does not match.
403
The Origin is not on the widget's allowed-domains list.
404
The session or widget no longer exists.

Example request

curl -X GET 'https://useline.io/api/channels/webchat/events' \
  -H 'Authorization: Bearer $LINE_SESSION_TOKEN' \
  -H 'Origin: https://example.com'