Webhook + Send API for DMs, SMS & WhatsApp

Four platforms in one API: Facebook DM, Instagram DM, SMS (via Twilio), and WhatsApp Business (via Meta Cloud API). Same authentication, same idempotency, same HMAC-SHA256 signing secret, and the same response shape across all four. Inbound events are forwarded to your webhook with a platform identifier, and outbound messages route based on conversation_id, platform_user_id, or to_phone in the request body.

ChatGenius forwards 7 event types: message_received (Facebook or Instagram DM), reel_shared (reel sent in DM), post_shared (Instagram post sent in DM), sms.message_received (inbound SMS to your provisioned ChatGenius number), whatsapp.message_received (inbound WhatsApp to your connected business number — text, image, audio, video, document, sticker, location, contacts, or interactive button reply), lead_captured (contact info extracted from any channel), and escalation (conversation escalated to human). Each event includes full conversation context, customer metadata, and platform identifiers.

Every webhook payload is signed with HMAC-SHA256 using your per-client webhook secret. The signature is sent in the X-ChatGenius-Signature header. Your server verifies the signature by computing HMAC-SHA256 of the raw request body with your secret and comparing it to the header value.

ChatGenius retries failed deliveries up to 6 times with exponential backoff (30s, 1m, 5m, 15m, 1h, 4h). If all 6 attempts fail, the event is moved to a dead-letter queue visible in your dashboard. You can replay dead-letter events manually once your endpoint is back online. Note: if Inbound Body Purge is enabled for compliance, SMS and WhatsApp inbound events use exactly one delivery attempt with no retries so the message body can be scrubbed within a tight window.

Yes. Send free-form WhatsApp text inside the 24-hour window or approved templates any time outside it through the same /v1/send endpoint. Pass template_name, template_language (e.g. en_US), and template_components alongside to_phone and platform: "whatsapp". Templates are passed through to Meta's Cloud API verbatim, so any header (text/image/video/PDF), body variable, or button parameter you defined in the template editor is honored.

Yes. Send SMS through the same Send-Reply endpoint by including to_phone in E.164 format (the platform auto-sets to sms). Sender phone number is automatically your client's provisioned Twilio number — server-controlled to enforce A2P 10DLC compliance. Each successful outbound API call counts as 1 toward your monthly SMS quota regardless of how many segments Twilio splits the message into. SMS access requires Professional or Business tier and a provisioned number.

External Reply Mode disables ChatGenius AI entirely for a specific conversation, a single channel (SMS-only or WhatsApp-only via per-channel AI Assistant toggles), or all channels at once (Global External Reply Mode). When enabled, inbound messages are still forwarded to your webhook but ChatGenius does not generate or send any AI response. Your backend sends replies through the Send API instead, giving you full control over the conversation logic.

A per-account compliance toggle for SMS and WhatsApp. When enabled, ChatGenius forwards inbound message bodies to your webhook with one delivery attempt (no retries) and immediately scrubs the body from local storage — meta_messages, the outbound webhook event log, the SMS webhook queue, and any downloaded WhatsApp media files on disk. Conversation rows in the unified inbox become metadata-only (message ID, timestamp, sender E.164, direction, delivery status, ticket_ref). Designed for healthcare-adjacent and privacy-strict scenarios where your server is the system of record. Requires AI off for SMS and WhatsApp (or Global External Reply Mode globally) since purge clears the same context AI uses to reply.

The Send API respects each platform's documented limits: 300 calls/second for Facebook text, 100 calls/second for Instagram, Twilio's account-specific limits for SMS, and Meta Cloud API limits for WhatsApp. ChatGenius includes built-in rate tracking to prevent exceeding these limits. Idempotency keys prevent duplicate sends if you retry a request.

In your ChatGenius dashboard, go to Settings > Webhook + Send API. Enter your endpoint URL, choose which event types to subscribe to (FB DM, IG DM, SMS, WhatsApp), and ChatGenius generates a per-client API key and webhook secret. You can rotate both at any time. The API key authenticates outbound Send API requests, and the webhook secret verifies inbound event signatures. SMS event subscription requires a provisioned Twilio number and Pro+ tier; WhatsApp event subscription requires WhatsApp connected on Pro+. Full developer reference at /docs/chatgenius-webhook-api.