Skip to content
Dashboard

Create an Instagram automation

POST
/instagram/automations
curl --request POST \
--url https://app.whatsetter.com/api/v1/instagram/automations \
--header 'Authorization: Bearer <token>' \
--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 }'

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.

Media typeapplication/json

On create, name, trigger (on, and keywords or any_word: true) and dm_message are required. On change, only the fields sent change.

object
account_id

Create only: required when the workspace has several Instagram accounts.

string
name
string
<= 120 characters
active

True: it writes to real people from now on.

boolean
trigger
object
on

What fires it. Read back, ref_link is an automation made in the dashboard on an ig.me link.

string
Allowed values: comment story_reply story_mention dm
posts
One of:
string
Allowed values: all next
keywords

One of these words fires it (accents and case ignored).

Array<string>
<= 30 items
any_word

Every comment or message fires it

boolean
public_replies

Comments only: public replies under the comment, one picked each time. Empty = none.

Array<string>
<= 10 items
dm_message

The private message people receive (one per comment

string
<= 1000 characters
link

A link delivered as a card with a button once the person taps the button under the private message. null removes it.

object
url
required

A public https URL.

string format: uri
label

The button that opens the link.

string
<= 20 characters
ask_label

The button under the private message that asks for the link.

string
<= 20 characters
title

The card’s title.

string
<= 80 characters
follow_gate

Ask the person to follow the account before the link. null removes it.

object
message
required
string
<= 1000 characters
button_label
string
<= 20 characters
success_message
string
<= 1000 characters
campaign_id

The agent that continues (GET /campaigns, its id or campaign_id). Default: the account’s own.

string | null
ai_handoff

The agent takes the conversation over after the automation.

boolean
default: true
Example
{
"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
}

Created (off unless active was true)

Media typeapplication/json
object
data
object
id
string
account_id
string
name
string
active
boolean
trigger
object
on

What fires it. Read back, ref_link is an automation made in the dashboard on an ig.me link.

string
Allowed values: comment story_reply story_mention dm
posts
One of:
string
Allowed values: all next
keywords

One of these words fires it (accents and case ignored).

Array<string>
<= 30 items
any_word

Every comment or message fires it

boolean
public_replies
Array<string>
dm_message
string
link
object
url
string
label
string | null
ask_label
string | null
title
string | null
follow_gate
object
message
string
button_label
string
success_message
string
campaign_id

The agent that continues (its campaign_id).

string | null
ai_handoff
boolean
stats
object
fired

Times it fired

integer
dms_sent

Private messages it sent.

integer
link_clicks

People who opened its link (once per person).

integer
last_fired_at
string | null format: date-time
created_at
string | null format: date-time
Example
{
"data": {
"trigger": {
"on": "comment",
"posts": "all"
}
}
}

Missing, unknown or revoked API key

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

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)

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

Resource not found in this workspace

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

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

Media typeapplication/json
object
error
object
code
string
message
string
Example
{
"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"
}
}
}

Invalid parameter or body (also an invalid or expired cursor)

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}