Skip to main content
Pearl Generic channel cover
Pearl Generic channel cover

Generic Channel

The Generic channel connects your own messaging system to a Pearl Text agent. Use it with a web chat, mobile app, CRM inbox, or any custom platform instead of one of NLPearl’s built-in integrations. The integration uses two webhooks:
The exchange is asynchronous. When you send a user message, NLPearl immediately returns 202 Accepted. Pearl’s reply is delivered shortly afterward as a separate POST request to your outbound URL.

Set Up the Channel

1

Open Text Channels

On the platform, open Settings → Text Channels, click Connect Channel, and choose Generic.
The Connect Channel menu of Text Channels, with Generic
The Connect Channel menu of Text Channels, with Generic
2

Configure your endpoint

The Connect Generic Channel window opens. Under Channel details, enter what NLPearl will use to send events to your system:Then click Connect channel.
If your outbound URL is behind a firewall, allow the NLPearl IP addresses listed in IP Whitelisting.
The Connect Generic Channel window with the channel name, the outbound URL, and the optional auth header
The Connect Generic Channel window with the channel name, the outbound URL, and the optional auth header
3

Save your channel credentials

In the list of Text Channels, click the ⋯ menu of your channel, then Manage. The Generic channel window shows the credentials required by your integration:Edit lets you change the channel name, the outbound URL, or the auth header later.
The Generic channel window with the Channel ID and the masked Signing secret
The Generic channel window with the Channel ID and the masked Signing secret
Treat the signing secret like a password. Never expose it in client-side code or commit it to source control.
4

Assign the channel to a Pearl

Open the Pearl that should handle these conversations, click Settings on its page, and pick the Generic channel in Text Channel.
The Text Channel list in the Settings of a text Pearl's page
The Text Channel list in the Settings of a text Pearl's page
A Generic channel can serve one Pearl at a time. If it is already connected to another Pearl, disconnect it there first.
Your inbound base URL is:

Send Requests to NLPearl

Send every request as JSON and include the channel secret:

Send a User Message

Send a user message to:
chatId is the conversation key. Every message with the same chatId belongs to the same conversation, and every outbound event for that conversation includes it.
Possible responses:
A message whose chatId is on your blacklist is answered with 200 but not processed: Pearl doesn’t reply.

Return Control to Pearl

After a human handoff, return the conversation to Pearl:

End a Conversation

Close a conversation:

Take Over a Conversation

Let a human agent take control at any time, without waiting for Pearl to hand off:
Pearl goes silent while your agent handles the conversation. Because you initiated the takeover, NLPearl does not send a handoff event. When your agent is finished, call /HandoffToPearl to resume Pearl or /EndConversation to close the conversation.

Record a Manual Reply

Add a reply your human agent sent from your own system to the NLPearl transcript, so Pearl resumes with full context:
NLPearl records the message but does not deliver it, since your platform already sent it to the user. This is valid only while the conversation is handed off — after a handoff event or your own /TakeOver — and otherwise returns 400.
/ManualMessage has no retry deduplication. If a request times out and you resend it, the message is recorded twice.
These control actions return 200 when successful, 400 when chatId is missing, or 404 when no active conversation exists for the supplied chatId.

Receive Events from NLPearl

NLPearl sends each event to your outbound URL as a POST request with this envelope:

Event Types

New event types may be added over time. Ignore types your integration does not recognize.

Acknowledge Message Delivery

Your HTTP response controls delivery retries for message events: Other event types, including typing and handoff, are best-effort notifications and are not retried.

Verify Webhook Signatures

NLPearl includes these headers in every request to your outbound URL:
The signature is the hexadecimal result of:
Verify the signature and reject old timestamps to protect your endpoint against forged requests and replay attacks:
Compute the HMAC over the raw request body bytes before parsing the JSON. Re-serializing a parsed body can change its bytes and invalidate the signature.
If you configured a custom authentication header, NLPearl includes it alongside the signature headers.

Handle Human Handoffs

A handoff can start in two ways: Pearl steps aside on its own and sends a handoff event, or your agent takes control directly with /TakeOver. Either way, Pearl stays silent until the conversation is returned to it.
1

Start the handoff

Pearl sends a handoff event with the reason it stepped aside, or your agent calls /TakeOver to step in directly. No handoff event is sent for your own takeover.
2

Keep the transcript in sync

Let your human agent communicate with the user in your own system. Continue sending the user’s messages to /Message, and record your agent’s replies with /ManualMessage. Pearl remains silent while handed off, but the transcript and inactivity timers stay up to date, so Pearl resumes with full context.
3

Finish the handoff

Call /HandoffToPearl when Pearl should resume, or /EndConversation when the conversation is complete. Your endpoint then receives ai_resumed or conversation_ended, respectively.

Rotate the Secret

Open the Generic channel window (⋯ → Manage in Text Channels) and click Rotate beside the Signing secret. Confirm with Rotate secret to generate a new one.
The Rotate the signing secret? confirmation, with Rotate secret
The Rotate the signing secret? confirmation, with Rotate secret
The previous secret becomes invalid immediately. Update the secret used for both the X-Pearl-Secret request header and webhook signature verification at the same time. Otherwise, your inbound requests and outbound webhook verification will fail until both sides use the new value.

Limits

The channel must be assigned to a running Pearl. If the Pearl is stopped or no Pearl is connected, inbound calls return 400 with "This channel is not connected to a Pearl.".

Inbound

Configure how your Pearl handles incoming conversations, inactivity, transcripts, and webhooks.