# Connect your own channel to HAPP

> Incoming webhook plus an outgoing endpoint — and any platform gets an AI assistant in 10 minutes.

- **Integration:** Custom Messenger (Messengers)
- **Page:** https://happ.tools/integrations/custom-messenger
- **Setup guide:** https://docs.happ.tools/ — step-by-step connection instructions, error reference and connection management live in the docs, not on this page.
- **Action:** [Open HAPP Dashboard](https://my.happ.tools/)

## Two endpoints, one assistant

*The contract*

You POST messages in, HAPP POSTs replies back. Everything else is your platform.

- **Minimal schema** — Required fields: sender_id and text. Optional: sender_name and metadata — your arbitrary data, which HAPP passes back in the reply.
- **HMAC-SHA256 signature** — HAPP adds an X-HAPP-Signature header with an HMAC-SHA256 signature of the request body. Verify it on your side to prevent spoofing.
- **Automatic retries** — If the outgoing endpoint errors or doesn't respond within 10 seconds, HAPP retries 3 times with exponential backoff.
- **Real-time endpoint status** — HAPP pings your outgoing endpoint every 5 minutes and shows latency and uptime right in the dashboard.
- **Request and response log** — Every incoming and outgoing request is logged — payload, status code, and response time available for debugging.

## What you need to connect

*Before you start*

Four things — then the wiring is two HTTP calls.

1. **HAPP account** — Active account with a configured assistant. No account yet? Sign up at my.happ.tools.
2. **HTTPS outgoing endpoint** — Your server URL where HAPP will POST AI replies. HTTPS only — HTTP is not supported for security reasons.
3. **Access to your platform code** — You need to add a POST request to the HAPP webhook URL when a message arrives from your user.
4. **HMAC secret (optional)** — HAPP signs every request with HMAC-SHA256. Verify the signature on your side — protection against spoofed requests.

## One assistant, every channel

*Everything else*

This is one of two dozen integrations. Connect the rest of your stack the same way — no code, no migration.

**Messengers** (5 channels): Telegram, Viber, Instagram, Facebook, WhatsApp
**Telephony** (5 carriers): Binotel, Ringostat, Phonet, UniTalk, StreamTelecom
**CRM systems** (5 integrations): SalesDrive, keyCRM, NetHunt, Odoo, Google Sheets

Plus Altegio, Shifio, Zadarma, Qdrant, Custom Messenger and webhooks for anything else you run.

## Frequently asked questions

*FAQ*

Answers to the most common questions about the Custom Messenger integration.

### What fields are required in the incoming request?

Required: sender_id (a unique sender ID in your system) and text (the message text). Optional: sender_name (display name) and metadata (an object of arbitrary data, which HAPP returns in the reply).

### What does HAPP send to the outgoing endpoint?

A POST request with JSON containing to, text, channel_id and metadata. The X-HAPP-Signature header contains the HMAC-SHA256 signature of the request body.

### How do I verify the HMAC-SHA256 signature?

Compute HMAC-SHA256 from the request body (raw bytes) using the HMAC secret from HAPP channel settings. Compare the hex result with the X-HAPP-Signature header value. Use constant-time comparison to avoid timing attacks.

### How many channels can I connect?

The number of Custom Messenger channels is unlimited. Each channel gets its own Incoming Webhook URL, HMAC secret, and can have its own assistant or operator team.

### Are media files (images, files) supported?

Yes. Pass an attachments field in the incoming request — an array of objects with type (image/file/audio) and url. HAPP passes media to the assistant and stores it in the conversation log.

### What happens if my endpoint returns an error?

If the outgoing endpoint returns HTTP 4xx or 5xx or doesn't respond within 10 seconds — HAPP retries 3 more times at 5, 15, and 60 second intervals. All failed attempts are logged.

### How do I test the integration locally?

Use ngrok or Cloudflare Tunnel to get a public HTTPS URL for your local server. After connecting, use the Send test button in HAPP channel settings — HAPP will send a real request to your endpoint.

## Ready to wire your own channel?

Two endpoints and an HMAC secret — your platform gets the same assistant as every native channel.

[Open HAPP Dashboard](https://my.happ.tools/)