API and webhooks for integrations

Send from your CRM, receive incoming messages on your server — one plain REST API across WhatsApp, Telegram and MAX.

Why use this instead of the official APIs

The Telegram Bot API is great — if you are running a bot account. The WhatsApp Business API is great — if you have a verified business profile and budget for per-conversation fees. chat-valet's API covers the gap: your personal number, automatable via HTTP, billed by the month.

Authentication

X-Api-Key: cv_xxxxxxxxxxxxxxxxxxxxxxxx

Send a message

`accountId` comes from `GET /api/accounts`. To reply into an existing conversation pass `chatId` instead of the account-number pair — the address is taken from the conversation itself, which is more reliable. The response carries `messageId` (the row in the send log) and `externalId` (the message id in the messenger — delivery and read receipts arrive under it).

POST https://chat-valet.com/api/messages/send
X-Api-Key: cv_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "accountId": "9f8b1c2d-...",
  "to": "15551234567",
  "text": "Hi, your order is ready."
}

→ {
  "ok": true,
  "messageId": 48213,
  "externalId": "3EB0C127D7BE9",
  "sentAt": "2026-08-21T10:24:00Z",
  "remainingToday": 42
}

Send in a cascade

The method this API exists for: you give a number and a text, the service checks where the number is registered and sends through the first suitable channel. The order comes from the `order` field, or the default you set in the cabinet, or WhatsApp → Telegram → MAX. The response tells you which channel was used and why others were skipped.

POST https://chat-valet.com/api/messages/send-cascade

{ "to": "15551234567", "text": "Your order is ready." }

→ {
  "ok": true,
  "channel": "whatsapp",
  "attempts": [
    { "channel": "telegram", "skipped": "not_registered" },
    { "channel": "whatsapp", "sent": true }
  ]
}

Receive incoming messages via webhook

Register your https endpoint in the cabinet under “API”. Two events: `message.in` for incoming messages, `message.status` for the status of an outgoing one — sent, delivered, read or failed. Every request is signed with HMAC SHA-256 in the X-Chatvalet-Signature header. The signature is a hex HMAC SHA-256 of the raw request body — verify it before parsing the JSON.

{
  "event": "message.in",
  "at": "2026-08-21T10:23:00Z",
  "data": {
    "accountId": "9f8b1c2d-...",
    "chatId": "c3d4e5f6-...",
    "chatExternalId": "15551234567@s.whatsapp.net",
    "senderId": "15551234567",
    "text": "When does my parcel arrive?",
    "mediaType": null,
    "at": "2026-08-21T10:22:58Z"
  }
}

`senderId`, `text` and `mediaType` can be `null` — an attachment without a caption, for example. The second event, `message.status`, arrives twice or more per message: first the send result (`sent` or `failed`), then the messenger receipts — `delivered`, `read` or `failed`:

{
  "event": "message.status",
  "at": "2026-08-21T10:24:05Z",
  "data": {
    "to": "15551234567",
    "channel": "whatsapp",
    "accountId": "9f8b1c2d-...",
    "chatId": "c3d4e5f6-...",
    "externalId": "3EB0C127D7BE9",
    "origin": "api",
    "status": "delivered",
    "at": "2026-08-21T10:24:04Z"
  }
}

The status only moves forward: `sent` → `delivered` → `read`, `failed` is final. A receipt carries `chatId`, `origin` (where the message came from: `api`, `campaign`, `human`, `ai`…) and `error` on failure. The event is sent for everything the service sends, broadcasts included; for scheduled messages — once they are actually sent. Messages typed by hand on the phone do not produce webhook events. What each channel reports:

Channel	Delivered	Read	How it is counted
WhatsApp	yes	yes	per message; in groups — by the first receipt from any member
Telegram	no — personal accounts get no delivery receipt	yes	“everything up to message X is read” per chat
MAX	no	yes	“everything up to time T is read” per chat

What you can build

Order notifications

Trigger a message from your e-commerce backend when an order ships — via the channel the customer actually uses, thanks to the cascade.

Appointment reminders

Send reminders 24 hours before a booking with the sendAt field. If the contact replies, receive the event in your CRM via webhook.

Lead follow-up

A form submission fires your server, which calls chat-valet's API to send a follow-up within seconds.

Internal alerts

Post server or business alerts to a Telegram account. Simpler than setting up a dedicated Telegram bot.

Supported features

Send text, images, video, audio, voice notes and documents
Cascade sending with per-request or default channel order
Number checks before sending — don't burn quota on dead numbers
Incoming messages and sent / delivered / read statuses as signed webhook events
Multi-account routing — pick the sending account per request
Message scheduling via the sendAt field
Accounts list and a full send log with delivery and read times via GET endpoints

Rate limits

The daily sending quota of your plan is shared between the API, broadcasts and the cabinet — the API reports the remaining quota in every send response. Up to 10 active API keys and 5 webhook endpoints per account.

GDPR considerations

When you use the API to message EU residents, you are the data controller under GDPR. Ensure you have a lawful basis for processing (typically consent or contract).

Pricing

The API and webhooks are available on every plan, including the free 30-day trial. No per-request fees — see pricing.

Get your API key

Frequently asked questions

What is the difference between this and the WhatsApp Business API?

The WhatsApp Business API requires Meta business verification and charges per conversation. chat-valet's API works through your personal WhatsApp account — no verification, no per-message billing, just a flat monthly plan.

What authentication does the API use?

API keys tied to your account, created in the cabinet under “API”. Pass the key in the X-Api-Key header or as an Authorization: Bearer token — both work. Keys carry scopes: send and read.

How do webhooks work?

You register an HTTPS endpoint in the cabinet. On every incoming message and every status change of an outgoing one (sent, delivered, read, failed) we POST a JSON payload signed with HMAC SHA-256 (the X-Chatvalet-Signature header). On failure we retry after 5 and 30 seconds; anything missed can be re-read from the log.

Is there a sandbox or test mode?

During the 30-day trial you can use your live account for testing at no cost. Webhook endpoints have a one-click “test ping” in the cabinet.

Can I use the API with multiple accounts?

Yes. Connect several WhatsApp, Telegram and MAX accounts under one subscription and pick the sending account per request — or let the cascade method pick the channel for you.

Where is the full documentation for every method?

The complete reference — every method with all fields, error codes and signature verification examples — is built into the cabinet: section “API”, tab “Documentation”.