Automations API Overview

ベータ版。 Automations API はベータ版であり、現在フィードバックを積極的に収集しています。改善を重ねる中で、エンドポイント、ペイロード、および制限が変更される可能性があります。改善の優先順位付けのため、フィードバックとバグレポートをサポートまでお送りください。

Automations エンドポイントを使用すると、Instagram で発生したエンゲージメントと Facebook ページへの DM に自動的に反応するルールを定義できます。各オートメーションは、1 つ以上の triggers(ルールを発火させるイベント)と 1 つ以上の actions(発火時に発生する処理)を組み合わせます。1 つのルールで複数のトリガーを監視し、複数のアクションをディスパッチできます — 同じエンゲージメントから分析パイプラインへ Webhook を発火 AND DM を送信することも可能です。このエンジンは、ユーザーがあなたに向けて行ったエンゲージメント(コメント、ストーリー返信、DM、リアクション)にのみ反応します — フォローをトリガーとする DM 送信、見知らぬ相手への初回 DM、一斉アウトバウンドは決して行いません — また、Ayrshare のアカウントごとのレート制限、受信者ごとの重複排除、および冪等な Webhook 取り込みを継承します。

sent は Meta がメッセージを受理したことを意味し、受信者が受信したことを意味するものではありません。 Instagram では、配信は最終的に受信者の Message requests 設定によって決まります。受信者が全員からのメッセージリクエストを許可していない場合、Meta は成功レスポンスを返しつつメッセージを黙って破棄し、これはあらゆる API レイヤーで不可視です。配信されたコメントトリガー DM でさえ、受信者が承認しなければならないメッセージリクエストとして届きます(両アカウント間に既に会話が存在する場合を除く)。詳しい説明は Automation DM Sent but Not Delivered を参照してください。

仕組み

オートメーションを作成する

使用したいトリガーとアクションを指定して POST /automations を実行します。オートメーションは即座に有効化されます。

エンドユーザーがエンゲージメントを行う

誰かがあなたの投稿にコメントする、ストーリーに返信する、DM を送信する、または DM にリアクションします。Meta が Webhook を Ayrshare に配信します。

Ayrshare がマッチしてディスパッチする

Instagram のスパム対策ヒューリスティクスの範囲内に収まるよう、エンゲージメントに 20〜60 秒のジッターが適用されます。その後エンジンはイベントにマッチするすべてのルールを検索し、アクションごとの重複排除と 1 日あたりの DM 上限をチェックし、各アクションを実行します。

発火した内容を確認する

GET /automations/:id/activity で監査ログ — すべてのディスパッチ試行、アクションごとの結果、および発生したエラー — が返されます。

Triggers

1 つのオートメーションに最大 50 個の triggers を紐付けできます。各トリガーは type フィールドを判別子とする union で、タイプ固有のフィールドは同じレベルに配置されます。各トリガーが利用できる場所は プラットフォーム 列に示されています。Facebook で必要な条件については Facebook ページを参照してください。

Type	発火条件	プラットフォーム	Config
`comment_keyword`	キーワードにマッチするコメントが投稿またはリールに付いたとき	`instagram`	`postId`(必須 — 投稿 ID、または `"all"`); `keywords`(必須、1 件以上)
`story_reply`	ユーザーが DM 経由でストーリーに返信したとき	`instagram`	`storyId`(任意 — ストーリー ID、または `"all"`)
`dm_reaction`	ユーザーがあなたの DM に絵文字でリアクションしたとき	`instagram`, `facebook`	`emoji`(任意 — 省略するとすべての絵文字で発火)
`dm_keyword`	ユーザーが送信した DM のテキストがキーワードにマッチしたとき	`instagram`, `facebook`	`keywords`(必須、1 件以上)

キーワードマッチングは大文字小文字を区別しない、単語単位でのマッチです。イベントは、設定されたキーワードのいずれか 1 つを含んでいれば、キーワードフィルタ付きトリガーを満たします。

`"all"` によるエバーグリーンルール

postId(または storyId)にリテラルの小文字文字列 "all" を設定すると、特定のコンテンツ 1 件ではなく、連携されたアカウント上のすべての投稿、リール、またはストーリーで発火します。新しいコンテンツが公開されても、投稿ごとの API 呼び出しなしで動作し続けるべきルールには、これが最適です:

{
  "type": "comment_keyword",
  "postId": "all",
  "keywords": ["LINK", "INFO"]
}

値は正確に "all" でなければなりません。"ALL" や " all" のような変形は、決してマッチしない投稿 ID として保存されるのではなく、バリデーションエラーとして拒否されます。 "all" が連携されたアカウントの範囲を超えて広がることはありません — あるプロファイル上のルールが別のプロファイルのコンテンツで発火することはできません。1 日あたりの DM 上限とエンゲージメントを起点とする送信ルールは、単一投稿のルールとまったく同じように適用されます。

重複排除はオートメーションと受信者ごとにカウントされ、投稿ごとではありません。"all" ルールでは、重複排除ウィンドウ(既定 7 日間)内に 2 つの異なる投稿にキーワードをコメントしたユーザーが DM を受け取るのは 1 回だけで、2 つ目のアクティビティは deduplicated として記録されます。より小さい dedupWindowMinutes はそのウィンドウを短くするだけで、重複排除を投稿ごとにするものではありません。0 に設定すると重複排除が無効になるため、同じ投稿への繰り返しコメントも含め、マッチするすべてのコメントで DM が送信されます。

ストーリートリガーでは、storyId を省略すると "all" と同じ動作になります。"all" を推奨します — 意図を明示的に示すことができ、省略は将来のリリースで廃止される予定です。事前の告知は Upcoming API Changes で行われます。

Facebook ページ

platform を facebook に設定すると、プロファイルに連携された Facebook ページでオートメーションを実行できます。DM はページから Messenger 経由で送信されます。

トリガー: dm_keyword と dm_reaction。コメントトリガーとストーリートリガーは現在 Instagram のみに対応しており、これらを使用する Facebook のオートメーションはバリデーションエラーとして拒否されます。
Messaging: Messages API で Facebook の DM を送信する場合と同様に、プロファイルで Facebook 向けに Messaging が有効化されている必要があります。
受信者: {{recipient_id}} はユーザーのページスコープ ID(PSID)です。Messenger の Webhook にはユーザー名が含まれないため、{{recipient_username}} は空になります。

{
  "platform": "facebook",
  "name": "Price list on request",
  "triggers": [{ "type": "dm_keyword", "keywords": ["price"] }],
  "actions": [{ "type": "send_dm", "message": "Here is our price list: https://example.com/prices" }]
}

Actions

1 つのオートメーションに最大 50 個の actions を紐付けできます。これらは順次実行され、各結果はアクティビティ行に記録されます。

Type	効果	Config
`send_dm`	ルールを発火させたユーザーに、テンプレート化されたメッセージまたは発火ごとに生成するテキストを使用して DM（Instagram、または Facebook ページから Messenger）を送信します。	`message`(必須、テンプレート対応); `messageUrl`(任意); `timeoutMs`(任意)
`fire_webhook`	オートメーションのコンテキストをアカウントレベルの Webhook URL に POST します(`POST /hook/webhook` で設定)。	`sendCompletedEvent`(任意、boolean — `automation.completed` も送信)。ペイロード形式は固定。下記を参照
`send_email`	プラットフォームのメールパイプラインを介してメールをキューに入れます。	`to`(必須、メールアドレス); `subject`(任意、テンプレート対応); `message`(必須、テンプレート対応)

アクションごとの重複排除ウィンドウ

すべての action は、その action のみに対して 既定の 7 日間 の受信者ごと重複排除ウィンドウを上書きする、オプションのトップレベル dedupWindowMinutes フィールドをタイプに関係なく受け入れます。

そのアクションで重複排除を完全に無効化するには 0 を設定します(受信者がすべてのイベントを期待する fire_webhook / send_email で一般的)。
上限は 525600(1 年)です。

Action with a 24h dedup override

{
  "type": "send_dm",
  "message": "Thanks {{recipient_username}}!",
  "dedupWindowMinutes": 1440
}

動的なメッセージ内容

既定では、send_dm はルールを発火させたすべての人に同じ message を送信します。人によって変わるのは {{recipient_username}} などのプレースホルダーだけです。アクションに messageUrl を設定すると、代わりにお客様自身のサーバーが各人向けの DM を作成します: ルールがマッチするたびに、お客様のエンドポイントに送信内容を問い合わせ、その回答を DM として送信します。例。投稿に「LINK」とコメントした人に返信するルールがあり、messageUrl がお客様のサーバーを指しているとします。Ava が「LINK please!」とコメントすると:

詳細をお客様の messageUrl に POST します: コメントした人("recipientUsername": "ava")、コメント内容、対象の投稿です。
お客様のサーバーが Ava 向けの返信(たとえば彼女専用に作成したトラッキングリンク付きのもの)を作成し、{ "message": "Hi ava, here's your link: https://example.com/r/12345" } と応答します。
そのテキストを、お客様が作成したとおりに DM として Ava に送信します。

お客様のサーバーが timeoutMs 以内に応答しない、エラーを返す、または使用できない内容を返した場合は、代わりにアクションの通常の message を Ava に送信するため、彼女は引き続き返信を受け取れます。 send_dm アクションには次のように追加します:

send_dm with messageUrl

{
  "type": "send_dm",
  "messageUrl": "https://yourapp.example.com/automations/message",
  "timeoutMs": 3000,
  "message": "Thanks for commenting! Here is the link: https://example.com"
}

messageUrl はテキストを問い合わせる先です。message は引き続き必須で、フォールバックとして使われます: お客様のサーバーに送信されることはなく、サーバーが時間内に応答しない、エラーを返す、または使用できない内容を返した場合(下記の警告を参照)に、代わりにこれを DM として送信します。timeoutMs は任意です(既定 3000、最大 5000)。 エンドポイントに送信される内容。 次の JSON ボディを含む POST です:

Callback request body

{
  "automationId":      "auto_9xKp2Lm4nQ",
  "triggerId":         "trg_a1b2c3",
  "trigger":           "comment_keyword",
  "platform":          "instagram",
  "recipientId":       "17841401234567890",
  "recipientUsername": "ava",
  "keyword":           "LINK",
  "activityId":        "auto_9xKp2Lm4nQ:trg_a1b2c3:comment.received:17912345678901234",
  "actionId":          "act_dm_1",
  "eventId":           "comment.received:17912345678901234",
  "commentId":         "17912345678901234",
  "commentText":       "LINK please!",
  "postId":            "17998765432109876",
  "storyId":           null,
  "timestamp":         "2026-05-12T09:14:22.000Z",
  "timeStamp":         1778577262
}

フィールド	意味
`automationId`, `triggerId`, `trigger`, `platform`	どのオートメーションとトリガーが発火したか。`fire_webhook` ペイロードと同じです
`recipientId`, `recipientUsername`	DM の送信先となる人。トリガーがユーザー名を持たない場合(たとえば `dm_keyword`)、`recipientUsername` は `null` です
`keyword`	マッチしたキーワード、または `null`
`activityId`	この発火のアクティビティエントリ。`GET /automations/:id/activity` と突き合わせることができます
`actionId`	問い合わせ元の `send_dm` アクション。`actionResults[].actionId` と一致します。1 つのエンドポイントで同じオートメーション上の複数の `send_dm` アクションに対応できます
`eventId`	発火の原因となったエンゲージメントに対する Ayrshare の ID
`commentId`	コメントトリガーの場合は Instagram のコメント ID。DM トリガーとストーリートリガーの場合は `null`
`commentText`	マッチしたテキスト: コメント、DM、またはリアクションの絵文字。存在しない場合(たとえば `story_reply`)は `null`
`postId`, `storyId`	エンゲージメントがあった投稿またはストーリー、または `null`
`timestamp`	リクエストを行った時刻(ISO 8601)
`timeStamp`	同じ時刻を秒単位の Unix 時間で表したもの。Webhook と同様に、コールバックが署名されている場合にのみ含まれます

Webhook シークレットを登録している場合、ボディは automations Webhook と同じシークレットを使い、同じ方法で署名されます: X-Authorization-Content-SHA256 は生のボディの HMAC-SHA256 で、X-Authorization-Timestamp にはボディの timeStamp が入ります。Webhook 用に既に使用している検証コードがそのまま使えます。シークレットが登録されているのにその時点で読み取れない場合、署名なしでコールバックを送信することはなく、代わりに message テンプレートを送信します。 指定できる URL。 messageUrl は公開 HTTPS アドレスでなければなりません。プライベート、ループバック、リンクローカル、またはクラウドメタデータのアドレスに解決される URL は拒否され、リダイレクトは追跡されません — 3xx 応答は失敗として扱われます。いずれの場合も、代わりにテンプレートが送信されます。 エンドポイントが返す内容。 最大 16 KB の JSON ボディで 200 を返し、1〜1000 文字の message 文字列を含めてください:

{ "message": "Hi ava — grabbed that link for you: https://example.com/r/12345" }

お客様のテキストはそのまま送信されます。{{placeholder}} の置換は適用されないため、生成したテキストに含まれるリテラルの {{ は、そのまま受信者に届きます。

message は引き続き必須であり、飾りではありません。 エンドポイントがタイムアウトした、non-2xx を返した、使用できないボディを返した、または繰り返し失敗した後に一時的にサーキットブレーカーが作動している場合は、代わりにレンダリングされた message テンプレートを送信します。この送信も失敗する可能性があります。たとえば、テンプレートが空にレンダリングされた場合(下記参照)や、Instagram が拒否した場合です。コールバックを再試行することはありません — 再試行すると受信者に 2 通のメッセージが送信されるおそれがあるためです。

timeoutMs の既定値は 3000 です。最大値は 5000 で、それより大きい値はオートメーションの作成時または更新時にバリデーションエラーとして拒否されます。この値は、レスポンスボディの読み取りを含むやり取り全体に適用されます。これを考慮に入れてください: DM はエンドポイントの応答後に送信されるため、遅いエンドポイントはメッセージを遅らせます。発火がどの経路をたどったかは GET /automations/:id/activity で確認できます。actionResults[] 内の send_dm エントリには、DM のテキストが確定した時点で messageSource が含まれます(その後に送信が失敗した場合も含む)。それより前にアクションが停止した場合(たとえば自身のアカウントへの skipped DM や deduplicated アクション)には含まれません:

`messageSource`	意味
`template`	`messageUrl` が設定されておらず、静的な `message` が使用された
`callback`	エンドポイントが応答し、そのテキストが使用された
`fallback`	`messageUrl` は設定されていたが使用できず、代わりに `message` が使用された

messageSource は DM がどのテキストから作成されたかを示すものであり、配信されたかどうかを示すものではありません。それについてはエントリの status を確認してください。フォールバック自体はアクションを失敗させません: テンプレートの DM が配信されると、エントリは sent となり、コールバックが使用されなかった理由が errorDetails に記載されます。その後テンプレートの DM も失敗した場合、エントリは failed となり、errorDetails には送信エラーに続いてコールバックの理由が記載されます。これに注意してください: そうしないと、毎回の発火で失敗しているコールバックが、正常に動作しているものとまったく同じように見えてしまいます。 message はそれ単体で送信可能な状態にしておいてください。受信者に対して空にレンダリングされ(たとえばユーザー名を持たない DM トリガーで {{recipient_username}} だけの場合)、かつコールバックのテキストが使用されない場合、DM は送信されず、アクションは failed となり、理由が errorDetails に記載されます。

Webhook イベント

POST /hook/webhook で登録した automations Webhook アクションには 2 つのイベントが配信されます。どちらも type フィールドを持ちます — 他のフィールドを読む前に、まずこのフィールドで分岐してください。

`type`	送信されるタイミング
`automation.triggered`	ルールの `fire_webhook` アクションが実行されたとき
`automation.completed`	ディスパッチが完了したとき(その結果とともに)

automation.completed は既定で無効です。オートメーションで有効にするには、その fire_webhook アクションに "sendCompletedEvent": true を設定します。それ以外の場合は無効のままなので、1 回の発火につき 1 つのペイロードを前提に構築された受信側は、引き続き正確に 1 つだけ受け取ります。automation.triggered はすべてのマッチの記録ではありません: fire_webhook 自体が実行されたときにのみ送信されるため、rate_limited または deduplicated で終わったマッチは automation.completed のみを生成します。ディスパッチの実行前に無効化または削除されたオートメーションについては、どちらのイベントも送信されません。

`automation.triggered`

{
  "type":              "automation.triggered",
  "automationId":      "auto_9xKp2Lm4nQ",
  "triggerId":         "trg_a1b2c3",
  "trigger":           "comment_keyword",
  "platform":          "instagram",
  "recipientId":       "17841401234567890",
  "recipientUsername": "jane_doe",
  "keyword":           "LINK",
  "activityId":        "auto_9xKp2Lm4nQ:trg_a1b2c3:comment.received:17912345678901234",
  "actionId":          "act_wh_1",
  "eventId":           "comment.received:17912345678901234",
  "commentId":         "17912345678901234",
  "commentText":       "LINK please",
  "postId":            "17895695668004550",
  "storyId":           null,
  "timestamp":         "2026-05-12T09:14:22.000Z"
}

activityId は GET /automations/:id/activity が返す行そのものなので、recipientId + triggerId + keyword によるマッチング — 複数の人が同じキーワードを同時にコメントすると曖昧になります — ではなく、両者を正確に突き合わせることができます。actionId はイベントを送信した fire_webhook アクションで、actionResults[].actionId と一致します。これにより、同じルール上の 2 つの fire_webhook アクションを区別できます。トリガーが設定しないフィールドは省略されるのではなく null になるため、形式は安定しています。recipientUsername は dm_keyword、dm_reaction、story_reply では null になります。Meta のペイロードにユーザー名が含まれないためです。commentId は comment_keyword と story_comment の場合にのみ、postId は comment_keyword の場合にのみ、storyId はストーリートリガーの場合にのみ設定されます。story_reply には keyword がありません。dm_keyword の場合、commentText は DM のテキストです。dm_reaction の場合、commentText と keyword はどちらもリアクションの絵文字です。

`automation.completed`

オートメーションがその fire_webhook アクションでオプトインした場合にのみ送信されます:

fire_webhook action with the outcome event on

{
  "type": "fire_webhook",
  "sendCompletedEvent": true
}

{
  "type":         "automation.completed",
  "automationId": "auto_9xKp2Lm4nQ",
  "triggerId":    "trg_a1b2c3",
  "trigger":      "comment_keyword",
  "platform":     "instagram",
  "recipientId":  "17841401234567890",
  "activityId":   "auto_9xKp2Lm4nQ:trg_a1b2c3:comment.received:17912345678901234",
  "eventId":      "comment.received:17912345678901234",
  "status":       "sent",
  "actionResults": [
    { "actionId": "act_dm_1", "type": "send_dm",      "status": "sent", "errorDetails": null, "messageSource": "callback" },
    { "actionId": "act_wh_1", "type": "fire_webhook", "status": "sent", "errorDetails": null }
  ],
  "errorDetails": null,
  "timestamp":    "2026-05-12T09:14:58.000Z"
}

status と各 actionResults[].status は、アクティビティログと同じ値 — sent、failed、rate_limited、deduplicated、skipped、auth_error — を使用するため、通常のケースではポーリングせずにディスパッチがどのように終わったかを知ることができます。ただし、このイベントの配信はベストエフォートです: 結果の記録とイベントのキューイングの間にプロセスが停止した場合、イベントは送信されません。アクティビティログが正となる記録なので、すべての結果が必要な場合は、結果を報告していない activityId について GET /automations/:id/activity と突合してください。send_dm の結果には、アクティビティログと同様に messageSource(template、callback、または fallback)も含まれるため、フォールバックし続けている messageUrl をポーリングせずに見つけることができます。結果は位置ではなく actionId で設定済みのアクションと照合してください — 同じタイプの 2 つのアクションはそれでしか区別できません。actionResults が空になるケースは 3 つあり、理由がある場合はトップレベルの errorDetails に記載されます: rate_limited(1 日あたりの上限に達した)、deduplicated(すべてのアクションが重複排除ウィンドウ内だった)、およびディスパッチが最大回数まで再試行されても完了しなかった後の failed です。最後のケースでは一部のアクションが既に実行されている可能性があるため、DM が送信済みで、automation.triggered も既に送信されている場合があります。 Webhook の配信は at-least-once であるため、同じイベントがまれに 2 回届くことがあり、再試行されたディスパッチは新しい hookId で automation.triggered を再送することがあります。hookId で重複排除しないでください。一方の処理が他方を抑止しないよう、イベントタイプごとに個別にキーを設定してください: automation.completed は activityId(各アクティビティには 1 つの結果があります)で、automation.triggered は activityId と actionId の組み合わせ(fire_webhook アクションごとに 1 つ)でキーを設定します。2 つのイベントは独立して配信されるため、まれに automation.completed が automation.triggered より先に届くことがあります。

Webhook が登録されていない場合

fire_webhook は、プロファイルに登録された automations アクションに POST し、なければ Primary Profile にフォールバックします。messages など別のアクションへのフォールバックはありません。どちらの登録も存在しない場合でも、automation.triggered は黙って破棄されるのではなく、アクションはアクティビティ行に failed として記録され、理由は actionResults[].errorDetails に記載されます。(automation.completed も送信先がないため、記録されません。)ディスパッチの全体的な status は通常の優先順位に従います: いずれかのアクションが認証エラーに該当すれば auth_error、次にいずれかのアクションが受理されていれば sent、それ以外は failed となります。したがって、Webhook の欠如がオートメーションの失敗統計にカウントされるのは、ルール上の他のアクションが何も送信しなかった場合のみです。別のアクションが送信した場合(かつ認証エラーに該当するものがない場合)、ディスパッチは sent で終了し、失敗した Webhook は actionResults[] にのみ表示されます。 fire_webhook の結果が sent であることは、イベントがあなたの URL への配信のためにキューに入れられたことを意味し、エンドポイントがそれを受理したことを意味するものではありません。配信はその後、独自のスケジュールで再試行されます。

テンプレート変数

send_dm.message、send_email.subject、および send_email.message は {{placeholder}} の置換をサポートします。不明なプレースホルダーは作成/更新時に拒否されます(473 バリデーションエラーとして)。これにより、タイプミスがそのまま {{foo}} としてお客様向けメッセージに紛れ込むことを防ぎます。

プレースホルダー	解決される値
`{{recipient_username}}`	コメントトリガーでは、エンゲージメントを行ったユーザーの Instagram ハンドル。DM トリガーとストーリー返信トリガーでは空、Facebook では常に空
`{{recipient_id}}`	エンゲージメントを行ったユーザーの ID。Instagram では Instagram スコープ ID (IGSID)、Facebook ではページスコープ ID (PSID)
`{{recipient_name}}`	予約済み。将来のエンリッチメントソースが値を提供するまでは空文字列に解決される
`{{sender_username}}`	予約済み。現在はすべてのプラットフォームで空文字列に解決される
`{{sender_name}}`	予約済み。現在はすべてのプラットフォームで空文字列に解決される
`{{comment_text}}`	トリガーを発火させたコメント / DM / ストーリー返信のテキスト
`{{comment_id}}`	発火したコメント / メッセージのプラットフォーム ID
`{{comment_sent_at}}`	イベントの ISO 8601 タイムスタンプ(利用可能な場合)
`{{matched_keyword}}`	マッチしたキーワード(または `dm_reaction` の場合は絵文字文字列)
`{{platform}}`	プラットフォーム識別子: `instagram` または `facebook`
`{{trigger_type}}`	トリガータイプ(例: `comment_keyword`)

sender_email / recipient_email はありません。 これらは意図的に公開されていません — 請求用メールアドレスが見知らぬ相手への DM に含まれる正当な理由はなく、Meta も IG の Webhook で受信者のメールアドレスを提供しません。これらのプレースホルダーを避けることで、意図しない情報開示を防ぎます。

テンプレート例:

Hey {{recipient_username}}, thanks for the comment "{{comment_text}}" — here is the link you wanted: https://example.com

レート制限と上限

プラン	アクティブなオートメーション数(プロファイルあたり)	1 日あたりの DM 上限(アカウントあたり)
Launch & Business	10	1,000
Enterprise	50	5,000

アクティブなオートメーションの上限は、親アカウント単位ではなく、User Profile ごとにカウントされます。アカウント配下の各プロファイルはそれぞれ Launch/Business は 10、Enterprise は 50 の枠を持つため、多数のプロファイルを持つアカウントでは各プロファイルでその数のオートメーションを実行できます。この上限はアクティブなオートメーションをカウントし、POST(作成)および PUT による再有効化(active: false → true)の双方で適用され、それぞれエラーコード 470 を返します。プロファイルごとの上限引き上げが必要ですか? サポートまでお問い合わせいただくことで、アカウントに対して上限を引き上げることができます。 1 日あたりの DM 上限 は Ayrshare の親アカウントごとに適用され、すべてのプロファイル間で共有されますが、プロファイルごとのサブ上限があるため、忙しい 1 プロファイルがアカウント全体のクォータを使い切ることはありません。DM 上限に達すると、アクティビティ行に rate_limited ステータスが記録され、DM は送信されません。 メッセージングの会話上限 も適用されます。send_dm にはプロファイルで Messaging アドオンが必要であり、送信される各 DM は、あなた自身が送信する DM と同様に、そのプロファイルの月間会話上限にカウントされます。上限に達すると、新しい受信者への send_dm は送信されず、アクティビティ行に failed ステータスが記録され、上限に関するメッセージが actionResults[].errorDetails に記載されます。コメントによってトリガーされた DM(comment_keyword および story_comment)は例外です: 上限に達していても引き続き送信され、カウントもされます。 1 つのオートメーションに対する構造的上限: triggers 1〜50 個、actions 1〜50 個。 Instagram 自体はアカウントあたり約 200 件/時の DM 上限を課しています。エンジンは 20〜60 秒のジッターでディスパッチをペーシングし、この上限を安全に下回るようにします。

アクティビティのステータス

GET /automations/:id/activity の行には、トップレベルの status と actionResults[] 内のアクションごとの status が含まれます。

ステータス	意味
`pending`	書き込まれたばかり。ワーカーがまだ取得していない状態
`in_flight`	ワーカーが現在ディスパッチ中
`sent`	少なくとも 1 つのアクションがプラットフォームに受理され、いずれのアクションも認証エラーに該当しなかった。`send_dm` の場合、これは Meta がメッセージを受理したことを意味し、受信者が受信したことは意味しない(下記の Note を参照)
`failed`	いずれのアクションも受理されず、少なくとも 1 つがプラットフォームに拒否された、または実行できなかった(かつ認証エラーには該当しない)。理由は `actionResults[].errorDetails` に記載されます
`auth_error`	アカウントの Instagram または Facebook ページの認証情報またはメッセージング権限が利用できなかった — 例えば、期限切れまたは取り消されたアクセストークン、Facebook Page が選択されていない、あるいはプロファイルで Messaging が有効化されていない、などです。DM は再試行されませんでした。受信者ごとの配信失敗は `failed` として記録され、ここには記録されません
`rate_limited`	1 日あたりの DM 上限(ティアまたはプロファイル単位)に達した。DM は送信されない
`deduplicated`	このアクションは、重複排除ウィンドウ内でこの受信者に対して既に発火済み
`skipped`	ディスパッチ前にオートメーションが抑止された — ファンアウトからディスパッチまでの間に無効化されたか削除された、アクションが設定されていない、またはトリガーとなったエンゲージメントがオートメーション自身のアカウントから発生した — 最も多いのは自身の投稿へのコメントです。この最後のケースではアクションは一切実行されません: DM は送信されず(アカウントは自分自身にメッセージを送信できません)、`fire_webhook` や `send_email` も実行されません。`automation.completed` にオプトインしたオートメーションは、このステータスとともに引き続きそのイベントを受信します

pending と in_flight は一時的な状態で、それ以外はすべて終端状態です。オートメーションに複数のアクションがある場合、トップレベルの status はアクションごとの結果から次の順序で導出されます: いずれかのアクションが認証エラーに該当すれば auth_error、次にいずれかのアクションが受理されていれば sent、次にすべてのアクションが重複排除されていれば deduplicated、次にすべてのアクションが意図的に抑止されていれば(skipped または deduplicated)skipped、それ以外は failed となります。アクションごとの詳細については actionResults[] を参照してください。

sent はプラットフォームによる受理の受領証であり、配信の受領証ではありません。 send_dm アクションは、Instagram アカウントから送信した場合も、Facebook ページから Messenger で送信した場合も、Meta がメッセージを受理した瞬間に sent とマークされます。オートメーションが記録するのはこの受理のみで、配信は追跡しません。Instagram はメッセージ配信をいかなる API にも公開しておらず、受信者が実際に受け取るかどうかは、受信者の Instagram Message requests 設定に依存し、Ayrshare はこれを読み取ることも影響を与えることもできません。Automation DM Sent but Not Delivered を参照してください。

エラーコード

API は 2 種類のエラー形式を返します。

ビジネスルールエラー はオートメーション固有の番号付き code を持ちます(例: { "action": "automation", "code": 469, ... })。
バリデーションエラー — 不正なリクエストボディ全般(必須/無効なフィールド、不明なテンプレート変数、認識されないキー)は、単一の 473 レスポンスとして返され、details オブジェクトに問題のあるフィールドが列挙されます。details はバリデータの出力(formErrors と fieldErrors)です。条件ごとのコードではなく、details で分岐してください。fieldErrors では、キーはトップレベルのリクエストフィールド(triggers、actions)です。特定のエントリ内の問題(例: トリガーで keywords が欠落)は、そのフィールド(例: triggers)配下で報告されます。一方、formErrors にはオブジェクトレベルの問題(認識されないキーなど)が含まれます。

Code	HTTP	意味
468	403	Business または Enterprise プランが必要
469	404	オートメーションが見つからない(呼び出し元が所有していない場合にも返される)
470	429	プランティアのアクティブなオートメーション上限に達した
471	400	このプロファイルで、要求されたプラットフォームにソーシャルアカウントが連携されていない
472	403	アカウントで機能がまだ利用できない — 早期アクセスについてはお問い合わせください
473	400	バリデーション失敗(不正なリクエストボディ) — `details` を確認してください

Launch プランも対象です。 Business Launch は Business ティアとして扱われるため、オートメーションは Launch、Business、Enterprise の各プランで利用できます。468 は、オートメーションを含まないプランに対してのみ返されます。

Meta が許可していないこと

一般的にリクエストされる機能のうち、Meta が公開 Instagram API で許可していないため、以下はサポートされていません。

新規フォロワーへの自動 DM。 Instagram はフォロー Webhook を公開していません。
見知らぬ相手への初回 DM。 Meta はビジネスアカウントがメッセージを送信する前に、受信者側からのエンゲージメント(コメント、返信、DM、リアクション)を必須としています。サポートされるすべての trigger はそのようなエンゲージメントを起点としますが、送信が許可されていることと、メッセージが配信されることは別です。受信者の Instagram Message requests 設定によって、Meta がメッセージを受理しつつ黙って破棄することは依然として起こりえます(Automation DM Sent but Not Delivered を参照)。
一斉アウトバウンドキャンペーン。 プラットフォームレベルで 1 時間あたりの DM 上限とスパム対策ヒューリスティクスが適用されます。

マルチプロファイル利用

エンドポイントは profileKey ヘッダーを尊重します。子プロファイルのキーを渡すと、そのプロファイル配下でオートメーションが作成/管理されます。プロファイルごとのサブ上限によってレート制限がプロファイル間で分割されるため、おしゃべりな 1 プロファイルが親アカウントのクォータを使い切ることはありません。

FAQ

新規フォロワーをトリガーにできますか?

いいえ。Instagram はフォロー Webhook を公開しておらず、Meta はサードパーティアプリが先にエンゲージメントを行っていないユーザーに DM を送信することを許可していません。サポートされるすべてのトリガー(comment_keyword、story_reply、dm_reaction、dm_keyword)はそのようなエンゲージメントを起点としており、これが送信を許容可能にしています。

アクティビティが sent になっているのに受信者に DM が届かないのはなぜですか?

sent は Meta がメッセージを受理したことを意味し、配信されたことを意味するものではありません。これは Instagram でも Facebook(ページからの Messenger)でも同じで、オートメーションが記録するのは受理のみで、配信は追跡しません。Instagram では、配信は受信者の Instagram Message requests 設定に依存します。受信者が全員からのメッセージリクエストを許可していない場合、Meta は成功レスポンスを返してメッセージを黙って破棄し、エラー、Webhook、その他のシグナルはあらゆる API 経路で発生しません。配信に成功したコメントトリガー DM でさえ、受信者が承認しなければならないメッセージリクエストとして届きます(既に会話が存在する場合を除く)。これは Instagram プラットフォームの恒久的な制限です。Automation DM Sent but Not Delivered を参照してください。

オートメーション発火時にアクセストークンが無効だった場合はどうなりますか?

アカウントの Instagram または Facebook ページの認証情報またはメッセージング権限が実際に失敗した場合 — 例えば、期限切れまたは取り消されたアクセストークン、Facebook Page が選択されていない、あるいはプロファイルで Messaging が有効化されていない、などのケース — アクティビティ行に auth_error ステータスが記録され、DM は再試行されません。アカウントの状態を解消すれば(再連携、Page の選択、または Messaging の有効化)、次にマッチしたエンゲージメントで通常通り発火します。これは真の認証情報および権限の失敗にのみ適用されます: 特定の DM が別の理由で配信できなかった場合 — 例えば、受信者が見つからなかった、またはトリガーとなったエンゲージメントが DM を送信するアカウント自身から発生した場合 — その行は failed または skipped として記録され、理由は actionResults[].errorDetails に記載されます。再連携しても結果は変わりません。

DM 送信前に遅延があるのはなぜですか?

各ディスパッチは、DM の送信が Instagram のスパム対策システムから見て自然に見えるよう、エンゲージメントの 20〜60 秒後にスケジュールされます。この遅延はルールがマッチする前にエンゲージメント自体に適用されるため、fire_webhook と send_email を含むルール上のすべてのアクションに適用されます。Webhook はコメントの直後ではなく、20〜60 秒後に届きます。アクティビティ行の created タイムスタンプはトリガーがマッチした時刻、completedAt はディスパッチが完了した時刻です。

アクティビティ行は永久に保持されますか?

アクティビティ行はトレースと分析のため無期限に保持されます。GET /automations/:id/activity エンドポイントはパフォーマンス上の理由から直近 30 日間の行を返します。(重複排除ガードは独自のアクションごとのウィンドウ — 既定 7 日間 — を使用し、これはアクティビティのルックバックとは無関係です。)

オートメーションを削除するとアクティビティ履歴も削除されますか?

いいえ。削除はソフト削除です。マスター行に deleted フラグが立ち、新規のディスパッチは発生しなくなりますが、履歴のアクティビティ行はアクティビティエンドポイントから引き続き読み取れます。

エンドポイント

POST /automations — 新しいオートメーションを作成する
GET /automations — オートメーションを一覧表示する
GET /automations/:id — トリガーとアクションを含むオートメーションを 1 件取得する
PUT /automations/:id — 部分更新。active: false で一時停止する
DELETE /automations/:id — ソフト削除
GET /automations/:id/activity — カーソルページネーション付きのディスパッチ監査ログ

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Automations API Overview

仕組み

Triggers

`"all"` によるエバーグリーンルール

Facebook ページ

Actions

アクションごとの重複排除ウィンドウ

動的なメッセージ内容

Webhook イベント

`automation.triggered`

`automation.completed`

Webhook が登録されていない場合

テンプレート変数

レート制限と上限

アクティビティのステータス

エラーコード

Meta が許可していないこと

マルチプロファイル利用

FAQ

エンドポイント

​仕組み

​Triggers

​"all" によるエバーグリーンルール

​Facebook ページ

​Actions

​アクションごとの重複排除ウィンドウ

​動的なメッセージ内容

​Webhook イベント

​automation.triggered

​automation.completed

​Webhook が登録されていない場合

​テンプレート変数

​レート制限と上限

​アクティビティのステータス

​エラーコード

​Meta が許可していないこと

​マルチプロファイル利用

​FAQ

​エンドポイント

仕組み

Triggers

`"all"` によるエバーグリーンルール

Facebook ページ

Actions

アクションごとの重複排除ウィンドウ

動的なメッセージ内容

Webhook イベント

`automation.triggered`

`automation.completed`

Webhook が登録されていない場合

テンプレート変数

レート制限と上限

アクティビティのステータス

エラーコード

Meta が許可していないこと

マルチプロファイル利用

FAQ

エンドポイント