> ## Documentation Index
> Fetch the complete documentation index at: https://watermelon.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom channel

> "Connect Watermelon to your own application, API, or messaging flow by sending messages into Watermelon and receiving responses through a callback URL.

***

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**

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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

```json theme={null}
{
  "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:

```text theme={null}
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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```bash theme={null}
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"
  }'
```