instagram-dm

A DM bot sounds like "receive message, send reply". In practice most of the work is the surrounding plumbing, and a mistake there either lets forged requests in or makes your bot talk to itself.

1. Meta webhook↓→
2. Signature check↓→
3. Parse and dedupe events↓→
4. Your handler↓→
5. Send API (window rules)

Verify the webhook

Meta signs each webhook with an X-Hub-Signature-256 header. The check must be done over the raw request body, not the parsed JSON, and in constant time. The library does it so you cannot accidentally compare the wrong thing.

Dedupe redeliveries and ignore your own echoes

Webhooks can arrive more than once, and Instagram also sends you an event for messages your own account sent. Without filtering both, a bot replies twice, or replies to itself forever.

Respect the messaging window

As documented by Meta when the library was written, a business can message someone for 24 hours after that person's most recent message. A human following up can use a HUMAN_AGENT tag for up to 7 days, but never for automated messages. The client refuses to send outside the window before Meta does. Re-check Meta's current documentation before relying on these numbers.

import { evaluateWindow } from '@27colab/instagram-dm';

const w = evaluateWindow(lastInboundAt, { humanAgent: false });
if (!w.open) {
  // refuse to send; w.expiresAt says when it closed
}

Try the window

What this does not do

• It is not an official Meta SDK and is not affiliated with Meta.
• It has no language model, prompts, storage or framework: you plug in a conversation handler.
• Pre-1.0, with a fake Graph API for offline tests.