> ## Documentation Index
> Fetch the complete documentation index at: https://docs.madiad.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Engagement

> Read comments, reply publicly or by DM, and run AutoDM monitors.

Beyond publishing, MADIAD Hub lets you act on the audience a profile has built — list recent media, read and reply to comments, send direct messages, and run AutoDM monitors that respond to new commenters automatically. Every call is scoped to one of your own profiles via `profile_id`.

<Tip>
  To leave your **own** first comment automatically when a post publishes (a link or hashtags), use the post's [`first_comment`](/concepts/posts#first-comment) field instead — that's part of publishing, not engagement.
</Tip>

<Note>
  Engagement automation (sending DMs, replying to comments, AutoDM monitors) is available on the **Business** plan and above. Requests on other plans return `403`. Each plan also has a **daily DM cap** — exceeding it returns `429`.
</Note>

<Note>
  Direct messages and AutoDM are also subject to each platform's own messaging limits (for example Instagram's window for messaging a user who hasn't messaged you recently). When a platform rejects a send, the reason surfaces in the response.
</Note>

## List recent media

Retrieve recent posts, reels, and videos across a profile's connected accounts — useful for finding the `media_id` to read comments on.

```bash theme={null}
curl "https://api.madiad.com/v1/engagement/media?profile_id=$PROFILE_ID&platform=instagram" \
  -H "Authorization: Bearer $MADIAD_API_KEY"
```

## Comments

Read the comments on a post. Pass `platform` and identify the post by `post_id` (the media id from the listing above) or `post_url`:

```bash theme={null}
curl "https://api.madiad.com/v1/engagement/comments?profile_id=$PROFILE_ID&platform=instagram&post_id=$MEDIA_ID" \
  -H "Authorization: Bearer $MADIAD_API_KEY"
```

Reply under a comment publicly, or send the commenter a private DM:

```bash theme={null}
# Public reply
curl -X POST https://api.madiad.com/v1/engagement/comments/public-reply \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile_id": "'$PROFILE_ID'", "comment_id": "'$COMMENT_ID'", "message": "Thanks for watching!" }'

# Private DM reply
curl -X POST https://api.madiad.com/v1/engagement/comments/reply \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile_id": "'$PROFILE_ID'", "comment_id": "'$COMMENT_ID'", "message": "Sent you the link in DM 👀" }'
```

Both require `profile_id`, `comment_id`, and `message`.

## Direct messages

Send a DM to a user by their platform-specific id, and list existing conversations. Both require a `platform`:

```bash theme={null}
curl -X POST https://api.madiad.com/v1/engagement/dms/send \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile_id": "'$PROFILE_ID'", "platform": "instagram", "recipient_id": "17841400000000000", "message": "Hi! Here's the discount code." }'
```

```bash theme={null}
curl "https://api.madiad.com/v1/engagement/dms/conversations?profile_id=$PROFILE_ID&platform=instagram" \
  -H "Authorization: Bearer $MADIAD_API_KEY"
```

## AutoDM monitors

An AutoDM monitor watches a post and automatically DMs anyone who comments — optionally only when their comment contains a trigger keyword.

<Note>
  AutoDM monitors are **Instagram only**, using Meta's official Private Replies API. The monitor runs in the background and de-duplicates commenters automatically, so each person is messaged once.
</Note>

```bash theme={null}
curl -X POST https://api.madiad.com/v1/autodm/monitors \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "'$PROFILE_ID'",
    "post_url": "https://www.instagram.com/p/abc123/",
    "reply_message": "Here is the link you asked for: https://madiad.com/offer",
    "trigger_keywords": ["link", "info"]
  }'
```

The response returns a `monitor_id`. Manage the monitor with it:

| Action        | Request                                        |
| ------------- | ---------------------------------------------- |
| Status        | `GET /v1/autodm/monitors/{monitor_id}`         |
| Activity logs | `GET /v1/autodm/monitors/{monitor_id}/logs`    |
| Pause         | `POST /v1/autodm/monitors/{monitor_id}/pause`  |
| Resume        | `POST /v1/autodm/monitors/{monitor_id}/resume` |
| Stop          | `POST /v1/autodm/monitors/{monitor_id}/stop`   |
| Delete        | `DELETE /v1/autodm/monitors/{monitor_id}`      |

| Field                 | Required | Description                                             |
| --------------------- | -------- | ------------------------------------------------------- |
| `profile_id`          | yes      | The profile whose connected account runs the monitor.   |
| `post_url`            | yes      | The post to watch.                                      |
| `reply_message`       | yes      | The DM sent to each new commenter.                      |
| `trigger_keywords`    | no       | Only DM commenters whose comment includes one of these. |
| `monitoring_interval` | no       | Minutes between checks.                                 |