> For the complete documentation index, see [llms.txt](https://en.help.firstline.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://en.help.firstline.cc/feature/channels/headless-api.md).

# Custom Channel

Through a custom channel, connect your company-developed websites, apps, or service interfaces to FIRST LINE to use AI agents, conversation scripts, and live customer service.

{% hint style="info" %}
**Custom channels are currently a Beta feature and are scheduled for official release in Q1 2027.** Features, API specifications, and available scope may continue to change. Please refer to the FIRST LINE system interface and the latest announcements for actual use.
{% endhint %}

## Overview

**Custom Channel** Allow enterprises to send customer messages to FIRST LINE and receive subsequent replies through self-developed websites, apps, or other service interfaces, without using the chat window provided by FIRST LINE.

For example, if a company already has its own member center or app and wants to keep the existing interface, but also wants customers to use FIRST LINE's **Fancy AI Agent**、**conversation script**or**human customer service**for assistance, it can use a custom channel.

It works as follows:

1. The customer enters a message in the enterprise's own interface.
2. The enterprise backend sends the message to FIRST LINE through the Headless Conversation API.
3. FIRST LINE handles it according to the channel's reception settings, either by an AI agent or a conversation script; when needed, it can also be transferred to human customer service.
4. The enterprise backend obtains the reply through Webhook or event query and then displays it in its own interface.

What custom channels provide is**integration capability for conversation services**; they do not automatically generate a website chat interface. Message display, user login, and front-end interactions are still developed and maintained by the enterprise itself.

{% hint style="info" %}
This feature is suitable for enterprises with development resources that want to retain their own interface and operating experience. If you only want to quickly add a FIRST LINE chat window to your website, it is recommended to use the existing [live chat](/feature/channels/live-chat.md) channel.
{% endhint %}

***

## Create a Custom Channel

{% stepper %}
{% step %}
**Enter Custom Channel**

Log in to FIRST LINE, open "Custom Channel" from the left menu, and enter the management list.
{% endstep %}

{% step %}
**Add Channel**

Click "Add" and fill in the name on the "General" tab. You may add a description and choose the channel category as needed. The name is a required field.

It is recommended to use an easily recognizable name, such as "Member Center Chat Service" or "Mobile App Customer Service."
{% endstep %}

{% step %}
**Save and keep the API credentials safe**

Click "Save" to create the account. The system will generate an API Client ID, Client Secret, and Webhook Secret, and display them in a one-time window.

Please copy and securely store these credentials immediately, because once the key window is closed, the original plain text keys cannot be viewed again.
{% endstep %}

{% step %}
**Set the receptionist**

After creation is complete, return to the "General" tab to set who will receive customers. You may choose as needed **AI agent**or**conversation script**and complete the necessary settings.

If you choose a Fancy AI Agent, customer messages will be handled according to that agent's instructions and routing logic; if you choose a conversation script, it will run according to the script settings.
{% endstep %}

{% step %}
**Set up Webhook (optional)**

On the "Webhook" tab, enter the HTTPS URL that the enterprise uses to receive events, select the events to subscribe to, and then save the settings.

If you are not using Webhook for now, the enterprise backend can also obtain conversation progress through the event query API.
{% endstep %}

{% step %}
**Enable and test**

After confirming that the receptionist, API credentials, message receiving, and event handling programs are all complete, enable the channel and use test messages to verify the full send-and-receive flow.
{% endstep %}
{% endstepper %}

***

## Channel Settings Instructions

### General

| Settings         | Description                                                                                           |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| Enable           | Determine whether this channel can be used by external systems. New channels are disabled by default. |
| Name             | The name used to identify this channel is required.                                                   |
| Description      | Record the purpose of use or the connected system.                                                    |
| Channel Category | Classify according to enterprise management needs.                                                    |
| Receptionist     | After the account is created, you can set an AI agent or conversation script.                         |

### API Credentials

API credentials are used to allow the enterprise backend to securely access FIRST LINE's Headless Conversation API.

| Credential     | Purpose                                                |
| -------------- | ------------------------------------------------------ |
| Client ID      | The application that identifies this API channel.      |
| Client Secret  | Used with the Client ID to obtain an API access token. |
| Webhook Secret | Verifies Webhook notifications sent by FIRST LINE.     |

{% hint style="warning" %}
**The Client Secret and Webhook Secret are shown only once when first created or regenerated.** Please store them in the enterprise backend's secret management system. They should not be placed in front-end JavaScript, mobile app installation packages, or public code repositories.
{% endhint %}

If the secret is lost, you can use "Regenerate" on the "API Credentials" tab. Please note:

* After regenerating the API credentials, the old Client and issued access tokens will become invalid, and the enterprise backend must use the new credentials.
* After regenerating the Webhook Secret, the old secret will become invalid immediately. The receiving end must update its verification settings accordingly, otherwise signature verification may fail.

### Webhook

Webhook allows FIRST LINE to actively notify the enterprise backend when new messages appear in a conversation, a round of processing is completed, or the status changes.

**The Webhook URL must use HTTPS and must resolve to a publicly reachable IP address.** Local addresses and private network addresses cannot be used as formal receiving endpoints.

Webhook can optionally subscribe to events such as new messages, turn completed, transferred to human agent, conversation ended, and AI tool execution. Events that are not checked will not be pushed; for detailed event names and data formats, please refer to [Headless Conversation API](/developer/api/advanced/headless-conversation-api.md).

{% hint style="info" %}
`turn.completed` This indicates that the current turn has been completed, but it does not mean the entire conversation has ended. When the AI is still processing the message, the system may first receive the request and then provide a reply event later.
{% endhint %}

***

## Integration documentation for developers

If you need to connect your website or app to FIRST LINE, please have your enterprise developers refer to [Headless Conversation API](/developer/api/advanced/headless-conversation-api.md). The technical documentation provides examples of authentication, message sending, reply reception, Webhook signature verification, and error handling.

***

## FAQ

### Will a custom channel automatically generate a chat window?

No. The enterprise needs to develop its own chat interface and backend service for communicating with FIRST LINE. If you want to use a ready-made website chat interface directly, you may consider "Live Chat."

### Can Fancy AI agents be used?

Yes. After creating the channel, choose the appropriate AI agent in the receptionist settings to let customer messages coming from outside be handled by that agent. The actual reply still operates according to the agent's instructions, available knowledge, and routing settings.

### Why is there no immediate AI answer after the message is sent successfully?

The response from the message sending API is an acknowledgment of receipt, and the AI agent may run as a background job. Please obtain subsequent results through `message.created`、`turn.completed` and other events.

### What if Webhook does not receive messages?

Please check whether the channel is enabled, whether the Webhook URL is a publicly reachable HTTPS URL, whether the relevant events are checked, and whether the receiving end correctly verifies the secret. If necessary, you can use the event query API to check whether events have been generated.

### How long can messages and events be retained?

Event queries provide data within a certain period. If the enterprise has long-term retention or audit requirements, please save the necessary events and conversation records according to its own data management policy; for detailed integration and resend rules, please refer to the developer documentation.

***

## Pre-launch checklist

* The custom channel has been created and the correct receptionist has been set.
* Client ID, Client Secret, and Webhook Secret have been saved in a secure backend environment.
* It has been confirmed that the Access Token can be used normally and that no secrets are exposed on the client side.
* After sending a test message, it can be received through Webhook or polling `message.created`.
* If using an AI agent, multi-turn conversations, transfer to human agent, and conversation script routing have been tested.
* The handling methods for network timeouts, retries, credential renewal, and event retention have been designed.