Guides

How sending works

Cold DMs go out through the Chrome extension; replies come from a person or the AI Setter, inside Meta's 24 hour window.

DM Hero sends two very different kinds of messages, through two different channels. Knowing which is which explains every limit you will meet.

	Cold DMs and follow-ups	Replies
Who starts them	A campaign: the first DM and every follow-up step	A person in the inbox, or the AI Setter
How they leave	The DM Hero Chrome extension, inside the rep's own Instagram session	Meta's Instagram API (Graph)
When	At the extension's own pace, inside the rep's daily DM cap	Only within 24 hours after the lead's last message
Through the API	Configure and control only: create campaigns, enroll, start, pause	Read the thread's state; switch, configure or hand threads to the AI Setter; approve its drafts

Cold DMs: the extension sends

Meta's API cannot message someone who has not written first. So the first DM of a campaign, and every follow-up, is sent by the DM Hero Chrome extension running in the rep's browser, exactly as the rep would send it by hand, paced like a person and capped per rep. The API never sends one: there is no endpoint for it and there will not be one.

What your code does instead:

Create or pick a campaign with its steps (POST /v1/campaigns, PUT /v1/campaigns/{campaign_id}/steps). A campaign created through the API starts paused.
Enroll leads (POST /v1/campaigns/{campaign_id}/enrollments).
Start it (POST /v1/campaigns/{campaign_id}/start).
Watch it happen: dm.sent and lead.contacted webhooks as DMs go out, lead.replied when someone answers.

If nothing is sent, check the rep: GET /v1/reps shows whether its extension is online, paused (and why) or offline, its Instagram token health, and how much of its DM cap is used. A rep.attention_required webhook fires when a rep needs a person.

Replies: a person or the AI Setter

Once a lead writes, the conversation is open for 24 hours after their last message. Inside that window a reply goes out through Meta's API, written by a person in the DM Hero inbox or by the AI Setter. The API sends no text of its own.

The AI Setter and your code

The AI Setter is DM Hero's own reply agent. For each rep it is off, in suggest mode or in auto mode, separately for replies to campaign DMs and for inbound DMs. Your code steers it without writing the reply:

Switch its mode per rep and channel (PUT /v1/reps/{rep_id}/setter-mode, scope reps:write), and keep the handles it must never answer in the rep's excluded list.
In suggest mode the Setter drafts each reply and waits. Your code can approve a draft, which sends the Setter's text as written, or dismiss it.
Hand a thread to the Setter, or take it back for a person.
setter.needs_human marks a thread the Setter parked for a person, with the reason in reason_kind: a good moment to alert someone.
Read each thread's state as metadata (GET /v1/conversations/{conversation_id}): status, stage, reply intent, whether it needs a human, and when the reply window closes. Reads never mark the thread read for the operator.

These operations, fields and events need a plan that includes the AI Setter; on any other plan they answer 403 API_SETTER_NOT_IN_PLAN_403 or read null.

Note: The DM cap of a rep applies to cold DMs sent by the extension. Replies are bounded instead by Meta's own limits, the 24 hour window and the per conversation cap in Rate limits.