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

# Automations API Overview

> エンゲージメントをトリガーとする Instagram オートメーション — エンドユーザーがコメント、ストーリーへの返信、DM へのリアクション、DM 送信を行った際に DM、Webhook、メールを発火させます

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "business") {
      displayPlans = ["Launch", "Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
    }
  }
  return <Note>
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.

{maxPackRequired && <span onClick={() => window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
 <span className="px-1.5 py-0.5 rounded text-sm" style={{
    backgroundColor: '#C264B6',
    color: 'white',
    fontSize: '12px'
  }}>
   Max Pack required
 </span>
</span>}
</Note>;
};

<PlansAvailable plans={["business", "enterprise"]} maxPackRequired={false} />

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

Automations エンドポイントを使用すると、Instagram で発生したエンゲージメントに自動的に反応するルールを定義できます。各オートメーションは、1 つ以上の **triggers**(ルールを発火させるイベント)と 1 つ以上の **actions**(発火時に発生する処理)を組み合わせます。1 つのルールで複数のトリガーを監視し、複数のアクションをディスパッチできます — 同じエンゲージメントから分析パイプラインへ Webhook を発火 AND DM を送信することも可能です。

このエンジンは完全に Meta のポリシー枠内で動作し(フォローによる DM トリガーなし、見知らぬ相手への初回メッセージなし、一斉送信の大量アウトバウンドなし)、Ayrshare のアカウントごとのレート制限、受信者ごとの重複排除、および冪等な Webhook 取り込みを継承します。

## 仕組み

<Steps>
  <Step title="オートメーションを作成する">
    使用したいトリガーとアクションを指定して `POST /automations` を実行します。オートメーションは即座に有効化されます。
  </Step>

  <Step title="エンドユーザーがエンゲージメントを行う">
    誰かがあなたの投稿にコメントする、ストーリーに返信する、DM を送信する、または DM にリアクションします。Meta が Webhook を Ayrshare に配信します。
  </Step>

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

  <Step title="発火した内容を確認する">
    `GET /automations/:id/activity` で監査ログ — すべてのディスパッチ試行、アクションごとの結果、および発生したエラー — が返されます。
  </Step>
</Steps>

## Triggers

1 つのオートメーションに最大 **50 個の triggers** を紐付けできます。各トリガーは `type` フィールドを判別子とする union で、タイプ固有のフィールドは同じレベルに配置されます。v1 ではすべての triggers は Instagram のみに対応しています。

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

キーワードマッチングは**大文字小文字を区別しない**、単語単位でのマッチです。イベントは、設定されたキーワードのいずれか 1 つを含んでいれば、キーワードフィルタ付きトリガーを満たします。ストーリートリガーで `storyId` を省略すると、連携された全アカウントのすべてのストーリーで発火します。

## Actions

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

| Type           | 効果                                                                                                     | Config                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
| `send_dm`      | ルールを発火させたユーザーに、[テンプレート化されたメッセージ](#template-variables) を使用して Instagram DM を送信します。                       | `message`(必須、テンプレート対応)                                           |
| `fire_webhook` | オートメーションのコンテキストをアカウントレベルの Webhook URL に POST します([`POST /hook/webhook`](/apis/webhooks/register) で設定)。 | *(なし — ペイロード形式は固定。[下記](#fire_webhook-payload) を参照)*              |
| `send_email`   | プラットフォームのメールパイプラインを介してメールをキューに入れます。                                                                    | `to`(必須、メールアドレス); `subject`(任意、テンプレート対応); `message`(必須、テンプレート対応) |

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

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

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

```json Action with a 24h dedup override theme={"system"}
{
  "type": "send_dm",
  "message": "Thanks {{recipient_username}}!",
  "dedupWindowMinutes": 1440
}
```

### `fire_webhook` payload

`fire_webhook` が実行されると、以下の JSON ボディがアカウントレベルの Webhook URL に POST されます。

```json theme={"system"}
{
  "automationId":      "auto_9xKp2Lm4nQ",
  "triggerId":         "trg_a1b2c3",
  "trigger":           "comment_keyword",
  "platform":          "instagram",
  "recipientId":       "17841401234567890",
  "recipientUsername": "jane_doe",
  "keyword":           "LINK",
  "timestamp":         "2026-05-12T09:14:22.000Z"
}
```

トリガーがこれらを設定しない場合(例: `dm_keyword` は Meta のペイロードにユーザー名を含まない、`story_reply` にはキーワードがない)、`recipientUsername` と `keyword` は `null` になります。

## テンプレート変数

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

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

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

テンプレート例:

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

## レート制限と上限

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

アクティブなオートメーションの上限は、親アカウント単位ではなく、**[User Profile](/apis/profiles/overview) ごと**にカウントされます。アカウント配下の各プロファイルはそれぞれ Business 10 / Enterprise 50 の枠を持つため、多数のプロファイルを持つアカウントでは各プロファイルでその数のオートメーションを実行できます。この上限はアクティブなオートメーションをカウントし、`POST`(作成)および `PUT` による再有効化(`active: false → true`)の双方で適用され、それぞれエラーコード `470` を返します。プロファイルごとの上限引き上げが必要ですか? [サポートまでお問い合わせ](mailto:support@ayrshare.com)いただくことで、アカウントに対して上限を引き上げることができます。

**1 日あたりの DM 上限** は Ayrshare の親アカウントごとに適用され、すべてのプロファイル間で共有されますが、プロファイルごとのサブ上限があるため、忙しい 1 プロファイルがアカウント全体のクォータを使い切ることはありません。DM 上限に達すると、アクティビティ行に `rate_limited` ステータスが記録され、DM は送信されません。

1 つのオートメーションに対する構造的上限: **triggers 1〜50 個**、**actions 1〜50 個**。

Instagram 自体はアカウントあたり約 200 件/時の DM 上限を課しています。エンジンは 20〜60 秒のジッターでディスパッチをペーシングし、この上限を安全に下回るようにします。

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

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

| ステータス          | 意味                                           |
| -------------- | -------------------------------------------- |
| `pending`      | 書き込まれたばかり。ワーカーがまだ取得していない状態                   |
| `in_flight`    | ワーカーが現在ディスパッチ中                               |
| `sent`         | すべてのアクションが成功                                 |
| `failed`       | 少なくとも 1 つのアクションが失敗(かつ認証エラーには該当しない)           |
| `auth_error`   | Instagram のアクセストークンが無効だった。DM は再試行されない        |
| `rate_limited` | 1 日あたりの DM 上限(ティアまたはプロファイル単位)に達した。DM は送信されない |
| `deduplicated` | このアクションは、重複排除ウィンドウ内でこの受信者に対して既に発火済み          |
| `skipped`      | ファンアウトからディスパッチまでの間にオートメーションが無効化されたか削除された     |

`pending` と `in_flight` は一時的な状態で、それ以外はすべて終端状態です。

## エラーコード

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` を確認してください |

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

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

* **新規フォロワーへの自動 DM。** Instagram はフォロー Webhook を公開していません。
* **見知らぬ相手への初回 DM。** Meta はビジネスアカウントがメッセージを送信する前に、受信者側からのコンタクト開始(コメント、返信、DM、リアクション)を必須としています — これは本機能でサポートしているすべての trigger が満たす条件です。
* **一斉アウトバウンドキャンペーン。** プラットフォームレベルで 1 時間あたりの DM 上限とスパム対策ヒューリスティクスが適用されます。

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

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

## FAQ

<AccordionGroup>
  <Accordion title="新規フォロワーをトリガーにできますか?">
    いいえ。Instagram はフォロー Webhook を公開しておらず、Meta はサードパーティアプリが会話を開始していないユーザーに DM を送信することを許可していません。サポートされるすべてのトリガー(`comment_keyword`、`story_reply`、`dm_reaction`、`dm_keyword`)は「ユーザーが最初にコンタクトした」という要件を満たしています。
  </Accordion>

  <Accordion title="オートメーション発火時にアクセストークンが無効だった場合はどうなりますか?">
    アクティビティ行に `auth_error` ステータスが記録され、DM は再試行されません。アカウントを再連携すれば、次にマッチしたエンゲージメントで通常通り発火します。
  </Accordion>

  <Accordion title="DM 送信前に遅延があるのはなぜですか?">
    各 `send_dm` のディスパッチは、Instagram のスパム対策システムから見て自然に見えるよう、エンゲージメントの 20〜60 秒後にスケジュールされます。`fire_webhook` および `send_email` アクションにはジッターはありません。アクティビティ行の `created` タイムスタンプはトリガーがマッチした時刻、`completedAt` はディスパッチが完了した時刻です。
  </Accordion>

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

  <Accordion title="オートメーションを削除するとアクティビティ履歴も削除されますか?">
    いいえ。削除はソフト削除です。マスター行に `deleted` フラグが立ち、新規のディスパッチは発生しなくなりますが、履歴のアクティビティ行はアクティビティエンドポイントから引き続き読み取れます。
  </Accordion>
</AccordionGroup>

## エンドポイント

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