Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🧩Headless Conversation API

Use the Headless Conversation API to send customer messages from your company’s own systems, receive replies, and handle conversation events.

This API is used to integrate "custom pipelines" and is currently in Beta feature. Before正式 use, please first complete pipeline creation, receiver settings, and activation in FIRST LINE. Features and interface may be adjusted depending on the version.

Headless Conversation API Allows enterprises to connect their own website, app, or customer service interface to FIRST LINE. The enterprise is responsible for the front-end interface and user authentication. FIRST LINE processes messages according to pipeline settings and returns replies from AI agents, conversation scripts, or human customer service through events.

If you have not yet created a pipeline, please first read Custom Pipeline Setup Guide.

Quick Start

  1. Create a custom pipeline in FIRST LINE and carefully keep the Client ID、Client Secret and Webhook Secret.

  2. Select a receiver (Fancy AI agent or conversation script), complete the required settings, and activate the pipeline.

  3. From the enterprise backend, use OAuth 2.0 Client Credentials to obtain an Access Token.

  4. Call the Send Message API.

  5. Use Webhook or Event Polling to get the reply, then display it in your own interface.

1. Authentication

The Headless Conversation API uses OAuth 2.0 Client Credentials authorization. The required scope is headless:use. Please use the API domain provided by the FIRST LINE tenant and apply for an Access Token with the Client ID and Client Secret obtained when creating the pipeline.

Please send POST JSON Body Client Credentials. Do not place client_id、client_secret、scope or other identification/credential data in the URL or query string; some environments may not correctly read parameters in the URL when handling POST requests, and sensitive data may also be retained in server, proxy, or browser URL history.

Request example:

POST https://YOUR_TENANT_HOST/oauth/token
Accept: application/json
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "scope": "headless:use"
}

cURL example:

For production integration, please confirm the tenant's Token Endpoint and credential issuance method; the YOUR_TENANT_HOST on this page is only a sample domain.

After authorization is complete, include the following in API requests:

Note: The Client Credentials for the Headless Conversation API are different from a normal FIRST LINE employee API Token. Do not mix them up.

2. Send Customer Messages

POST /api/headless/v1/messages

Send text

Request Body

Field
Required
Description

external_user_id

Yes

The customer identifier value in the enterprise system, up to 191 characters. For the same customer within the same pipeline, continue using the same identifier value.

client_message_id

No (recommended)

A unique identifier for this message, up to 191 characters, used for safe resend.

message.type

Yes

text or postback.

message.text

For text messages

message content, up to 1,000 characters.

message.value

For Postback

The value returned after the customer clicks an option, up to 1,000 characters.

profile.name

No

Customer display name, up to 50 characters.

context

No

Additional context data; see the explanation below.

Postback example:

Successful response

HTTP 202 Accepted:

Field
Description

request_id

The request identifier for this message, used to match subsequent events.

conversation_id

Conversation identifier; used when querying events.

sequence

Event sequence number, helpful for handling event order.

HTTP 202 does not mean the AI has finished answering. After FIRST LINE accepts the message, obtain subsequent messages and processing results via Webhook or event polling.

Avoid duplicate submissions

It is recommended to provide a unique client_message_id. When the network times out and you are unsure whether the message was received, retry withthe same identifier and the same content.

If the original message is still being processed, you may receive 409 Conflict; if the same identifier is used with different message content, you will receive 422 Unprocessable Entity. Do not generate a new message ID just for retrying, otherwise duplicate sends may occur.

3. Query Conversation Events

GET /api/headless/v1/conversations/{conversation_id}/events

You can use the event query API to get new replies and status notifications for a specified conversation:

Parameters
Description

conversation_id

The conversation identifier returned by the Send Message API.

after_sequence

Optional; only events with a sequence number greater than the specified value are returned. Default is 0.

In the response, data is the event list and may be an empty array:

The above is sample data, not a real customer or conversation.

Please process events in sequence order, and store the last successfully processed sequence number for use in the next query. Events may skip some sequence numbers depending on subscription settings,you do not need to wait for consecutive numbers. Polling returns the currently available events immediately and will not keep waiting for new events.

4. Event Types

Webhook and event polling use the same single-event data format.

Event
Description

message.received

Customer message received.

message.created

A message to be sent to the customer is generated.

turn.completed

Processing of this round of customer messages is complete.

conversation.transferred_to_human

Conversation transferred to the human customer service process.

conversation.ended

Conversation has ended.

tool.invoking

AI tool starts executing.

tool.completed

AI tool finished executing.

You can choose which events to receive in the pipeline's Webhook settings. By default, it includes message.created、turn.completed、conversation.transferred_to_human and conversation.ended;event polling also filters by the same subscription list.

message events

message.created of data Example:

sender May be:

  • bot: automatic replies, including AI agents, conversation scripts, or system messages.

  • human: message sent by a human customer service agent.

Message types may include text、image、quickreply、button、carousel;content content varies by type. Please render according to message.type and provide appropriate fallback display for unrecognized types.

Turn completed event

turn.completed of data May include:

in_reply_to is the list of request IDs processed in this turn. Please note:Turn completion does not mean the entire conversation has ended. If you want to determine whether the conversation has formally ended, refer to conversation.ended and other events.

5. Receive Webhook

In FIRST LINE's custom pipeline settings, enter a publicly accessible HTTPS Webhook URL, and select the events you want to subscribe to. FIRST LINE sends event JSON via HTTP POST.

The Webhook includes the following headers:

Header
Description

X-FirstLine-Event

Event type.

X-FirstLine-Event-Id

Event identifier.

X-FirstLine-Timestamp

Unix Timestamp (seconds).

X-FirstLine-Signature

Webhook HMAC SHA-256 signature.

Verify Webhook Signature

To confirm the request comes from the expected source, use the pipeline's Webhook Secret verify signature:

You must use the receivedraw HTTP Request Body for calculation; do not decode the JSON and re-encode it first.

Node.js verification calculation example:

After verification is complete, use event_id for deduplication, then let the enterprise system process the event. The receiver should return 2xx as soon as possible to avoid timeouts caused by long-running tasks. Webhooks may be resent,do not rely on notifications being delivered only once or always in order.

when push delivery fails

If the Webhook has a temporary connection problem, or the receiver responds with 408、429、5xx, the system may retry automatically. Other 4xx responses are usually not retried. It is recommended that the integration side keep event processing records and verify them with the event query API when necessary.

6. Context Data Context (Optional)

When sending a message, you may provide auxiliary data related to this service, for example:

Restrictions are as follows:

  • Up to 20 key-value pairs.

  • Keys are limited to lowercase English letters, numbers, and underscores, 1 to 40 characters in length.

  • Values must be strings, up to 500 characters.

  • If the limit is exceeded, 422will be returned instead of truncating the content.

Context can be referenced by service flows and AI agents, but should not be used to transmit passwords, access tokens, or other unnecessary sensitive information. Enterprises should first verify the data source to prevent customers from forging membership identity or service permissions.

7. Common Errors and Handling

Status Code
Condition
Recommended Handling

200

Event query succeeded.

Process the retrieved events in order.

202

Customer message received.

Wait for the Webhook or query subsequent events.

401

Invalid access token or pipeline status.

Check the Token, Client credentials, and pipeline activation status.

403

Insufficient access permissions.

Confirm that the Token has headless:use scope.

404

No accessible conversation found.

Confirm conversation_id and pipeline.

409

The same message is still being processed.

Retry later with the same ID and content.

422

Field format does not match.

Correct the request data.

429

Requests are too frequent.

Reduce the frequency and use backoff retries.

5xx

Temporary service anomaly.

Log the error and retry a limited number of times with the same message ID.

Event data has a retention period. For long-term retention needs, the enterprise should plan according to its own policy. When tracking a conversation for a long time, it is recommended to properly save received events and processing records.

Pre-launch checks

  • A custom pipeline has been created and activated, and the receiver settings are correct.

  • The Access Token can be successfully authorized, and credentials are stored only in the backend.

  • Text messages can be sent and HTTP 202 can be received.

  • Replies can be received via Webhook or event polling.

  • Event deduplication, message retries, and asynchronous replies have been handled.

  • Human handoff, conversation ending, and common error scenarios have been tested.

After completing the above steps, you can integrate FIRST LINE's conversation capabilities into your enterprise's own service interface.

Last updated