# Create an Instagram automation

`POST https://app.whatsetter.com/api/v1/instagram/automations`

Creates an automation on an account: when someone comments one of its
words (on every post, on the posts published from now on, or on some
posts), replies to a story, mentions the account in a story, or sends
a private message with one of its words, it may answer in public
under the comment (`public_replies`, one picked each time), then sends
one private message (`dm_message`; with `link`, a card whose button
opens it after the person taps; with `follow_gate`, after asking them
to follow the account), and the agent continues the conversation
(`ai_handoff`, the account's own agent unless `campaign_id` names
another).

It is created **off** (`active: false`) unless you send `active:
true`: an active automation writes to real people. Going live is
refused with `409 automation_conflict` (and the automation in the way,
in `conflict`) when a live automation of the account already watches
the same posts for the same words: one comment fires one automation
only. Requires scope `instagram:write`.

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `account_id` | string | no | Create only: required when the workspace has several Instagram accounts. |
| `name` | string | no |  |
| `active` | boolean | no | true: it writes to real people from now on. |
| `trigger` | object | no |  |
| `public_replies` | array | no | Comments only: public replies under the comment, one picked each time. Empty = none. |
| `dm_message` | string | no | The private message people receive (one per comment |
| `link` | object,null | no | A link delivered as a card with a button once the person taps the button under the private message. null removes it. |
| `follow_gate` | object,null | no | Ask the person to follow the account before the link. null removes it. |
| `campaign_id` | string,null | no | The agent that continues (`GET /campaigns`, its `id` or `campaign_id`). Default: the account's own. |
| `ai_handoff` | boolean | no | The agent takes the conversation over after the automation. |

```json
{
  "account_id": "68f1c2d3e4f5a6b7c8d9e0f1",
  "name": "Buyer's guide",
  "trigger": {
    "on": "comment",
    "posts": "next",
    "keywords": [
      "GUIDE"
    ]
  },
  "public_replies": [
    "Sent you a DM 👀",
    "Check your messages!"
  ],
  "dm_message": "Here is the guide 👇",
  "link": {
    "url": "https://example.com/guide",
    "label": "Get the guide"
  },
  "ai_handoff": true,
  "active": false
}
```

## Example request

```bash
curl --request POST \
  --url 'https://app.whatsetter.com/api/v1/instagram/automations' \
  --header 'Authorization: Bearer ws_live_…'
  --header 'Content-Type: application/json' \
  --data '{"account_id":"68f1c2d3e4f5a6b7c8d9e0f1","name":"Buyer's guide","trigger":{"on":"comment","posts":"next","keywords":["GUIDE"]},"public_replies":["Sent you a DM 👀","Check your messages!"],"dm_message":"Here is the guide 👇","link":{"url":"https://example.com/guide","label":"Get the guide"},"ai_handoff":true,"active":false}'
```

## Responses

### 201: Created (off unless `active` was true)

```json
{
  "data": {
    "id": "",
    "account_id": "",
    "name": "",
    "active": false,
    "trigger": {
      "on": "comment",
      "posts": "",
      "keywords": [
        ""
      ],
      "any_word": false
    },
    "public_replies": [
      ""
    ],
    "dm_message": "",
    "link": {
      "url": "",
      "label": "",
      "ask_label": "",
      "title": ""
    },
    "follow_gate": {
      "message": "",
      "button_label": "",
      "success_message": ""
    },
    "campaign_id": "",
    "ai_handoff": false,
    "stats": {
      "fired": 0,
      "dms_sent": 0,
      "link_clicks": 0,
      "last_fired_at": ""
    },
    "created_at": ""
  }
}
```

### 401: Missing, unknown or revoked API key

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 403: The key lacks the required scope (`insufficient_scope`), the plan does not have this part of the API (`not_in_plan`), or Instagram is not enabled on the workspace (`instagram_not_enabled`, Instagram routes)

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 404: Resource not found in this workspace

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 409: `automation_conflict`: a live automation of the account already watches the same posts for the same words. `conflict` names it.

```json
{
  "error": {
    "code": "automation_conflict",
    "message": "\"Buyer's guide\" is already live on the same post with the keyword \"guide\". Only one can be active, otherwise people would receive the same thing twice.",
    "conflict": {
      "id": "6900a1b2c3d4e5f6a7b8c9d0",
      "name": "Buyer's guide",
      "reason": "all_posts",
      "keyword": "guide"
    }
  }
}
```

### 422: Invalid parameter or body (also an invalid or expired `cursor`)

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```


Source: https://docs.whatsetter.com/api-reference/operations/createinstagramautomation/
