Skip to main content
The Custom channel lets you connect Watermelon to an external system so messages can flow in both directions. This is useful when you want to: * connect your own chat interface to Watermelon * send messages from an external backend into an existing Watermelon conversation * receive Agent replies in your own system through a webhook callback * keep the full conversation visible inside Watermelon With this setup, your external system sends incoming messages to Watermelon. Watermelon routes the message to the correct Agent and conversation. When the Agent replies, Watermelon sends that reply to your callback_url.

​
How it works

  1. Your system sends a message to the Custom channel webhook. 2. Watermelon routes that message to the correct Agent using the provided channel information. 3. The Agent processes the message. 4. Watermelon sends the reply to your callback_url.
The conversation remains available in Watermelon like any other conversation.

​
Authentication

Send a POST request to the Custom channel webhook. Webhook URL 
https://webhook-custom-prod-1080791310029.europe-west1.run.app/custom/v1/webhook
Authentication * Type: Bearer * Header: Authorization: Bearer <watermelon_api_key>

​
Sending messages to the Custom Channel

To send a message into Watermelon from your own system, make a POST request to the Custom channel webhook. Your system acts as the message sender and Watermelon processes the message as if it was sent through a Chat Widget. This means the Custom channel impersonates a Chat Widget. Because of this you must provide the widget ID of the Chat Widget you want to use.

​
Important fields

channel_name This defines which internal channel Watermelon should use for routing. For Custom channel integrations this value must be: 
chatwidget
The Custom channel impersonates the Chat Widget channel so the message is processed with the same Agent configuration. channel_id The Chat Widget ID that you want to impersonate. This determines: * which widget configuration is used * which AI Agent processes the message * which workspace settings apply You can find this ID in Watermelon under Chat Widget → Placement. In the embed code it appears as: 
data-watermelon-widget-id
text The message that should be sent into the conversation and processed by the Agent. callback_url The URL where Watermelon will send all responses. This should be an endpoint on your server API that accepts POST requests. Watermelon will call this endpoint whenever the Agent replies. Content-Type: application/json

​
Example request

{
  "channel_name": "chatwidget",
  "channel_id": "LabXNtxYDRp",
  "text": "Hello World",
  "callback_url": "https://webhook.site/d4f8ccd9-d8d1-403f-908b-bca09a89c71d"
}
In this example: * The Custom channel impersonates the Chat Widget with ID LabXNtxYDRp * The message “Hello World” is sent into Watermelon * Agent responses are sent to the provided callback_url

​
Optional conversation targeting

You can also include the following fields if you want to send a message to an existing conversation. * contact_id — the Watermelon contact identifier * socket_id — the conversation identifier If these values are provided, the message will be routed to that specific conversation thread. If they are omitted, Watermelon may create a new conversation.

​
Field reference

​
channel_name

The channel type used for routing. Use: 
chatwidget

​
channel_id

The Chat Widget ID from Watermelon. This determines which widget and Agent configuration the message should use.

​
text

The message that should be processed by the Agent.

​
contact_id

Optional numeric Watermelon contact ID. Use this to associate the message with an existing contact.

​
socket_id

Optional conversation identifier. Use this to continue an existing thread instead of starting a new one.

​
callback_url

The HTTPS endpoint on your side that will receive messages sent back by Watermelon.

​
Callback payload

Watermelon sends replies to your callback_url as a POST request with a JSON payload. This payload can contain an Agent reply or another message routed through the conversation.

​
Response body example

{
  "contact_id": 147246,
  "socket_id": "019cc3083a46-76ddff3da7b46-00d2d1-51-126eab1ca45d5059-a3f00631c9a0fecb196a66a2",
  "message": "Hi! How can I help you today?"
}
When the Agent sends a reply, Watermelon makes a POST request to your callback_url with this payload. In this payload: * contact_id identifies the Watermelon contact * socket_id identifies the conversation thread * message contains the Agent response text Your server can use contact_id and socket_id to store the conversation context and send follow-up messages back into the same thread.

​
Response fields

​
contact_id

The Watermelon contact ID related to the conversation.

​
socket_id

The unique conversation identifier.

​
message

The message text sent by Watermelon, usually the Agent response.

​
Typical flow

A common integration flow looks like this:
  1. A user sends a message in your external application. 2. Your backend forwards that message to the Watermelon Custom channel webhook. 3. Watermelon processes the message with the correct Agent. 4. Watermelon sends the Agent reply to your callback_url. 5. Your system displays that reply to the user.

​
Using the Messaging API with your webhook

The Custom channel is used to send a message into Watermelon and receive the Agent reply on your callback_url. When you continue the conversation through the Messaging API, use the payload and routing values from the active conversation. Do not assume a generic message schema. The verified example shared here is the payload used when the Messaging API sends a conversation event to your webhook.

​
Example payload

{
  "company_id": 1883,
  "conversation_id": 135372,
  "is_typing": false,
  "socket": "019cc3083a46-76ddff3da7b46-00d2d1-51-126eab1ca45d5059-a3f00631c9a0fecb196a66a2",
  "isInbound": false
}

​
Field reference

company_id The Watermelon company ID that owns the conversation. conversation_id The numeric ID of the conversation. socket The socket identifier of the active conversation thread. is_typing Indicates whether the event represents an active typing state. isInbound Indicates the direction of the event. For the example shared above, the Messaging API request is tied to the active conversation through company_id, conversation_id, and socket.

​
Notes

* Use the same contact_id and socket_id when you want to continue an existing conversation. * Make sure your callback_url is publicly reachable and can accept POST requests. * The Chat Widget ID is required for correct routing. * All messages remain visible inside Watermelon. * Keep API credentials on the server side and never expose session cookies or internal tokens in client code.

​
Example cURL request

curl -X POST "https://webhook-custom-prod-1080791310029.europe-west1.run.app/custom/v1/webhook" \
  -H "Authorization: Bearer <watermelon_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_name": "chatwidget",
    "channel_id": "your-watermelon-widget-id",
    "text": "Hello, I need help with my subscription",
    "callback_url": "https://your-domain.com/webhooks/watermelon"
  }'