# API リファレンス：文面

> https://okaeri.tech/developers/reference/messages/ の Markdown 版。

文面（`messages`）の操作です。共通の決まり（認証・レート制限・エラーの形）は[概要](https://okaeri.tech/developers/index.md)を、型の詳細は[スキーマ](https://okaeri.tech/developers/reference/schemas.md)を参照してください。

- [GET /api/v1/messages](https://okaeri.tech/developers/reference/messages.md#listMessages)　文面の一覧（`listMessages`）
- [POST /api/v1/messages](https://okaeri.tech/developers/reference/messages.md#createMessage)　文面の作成（`createMessage`）
- [GET /api/v1/messages/{message_id}](https://okaeri.tech/developers/reference/messages.md#getMessage)　文面の取得（`getMessage`）
- [PATCH /api/v1/messages/{message_id}](https://okaeri.tech/developers/reference/messages.md#updateMessage)　文面の更新（`updateMessage`）
- [DELETE /api/v1/messages/{message_id}](https://okaeri.tech/developers/reference/messages.md#deleteMessage)　文面の削除（`deleteMessage`）
- [POST /api/v1/messages/{message_id}/duplicate](https://okaeri.tech/developers/reference/messages.md#duplicateMessage)　文面の複製（`duplicateMessage`）
- [GET /api/v1/message_variables](https://okaeri.tech/developers/reference/messages.md#listMessageVariables)　文面で使える変数の一覧（`listMessageVariables`）
- [GET /api/v1/message_examples](https://okaeri.tech/developers/reference/messages.md#listMessageExamples)　文面の例文の一覧（`listMessageExamples`）
- [POST /api/v1/message_previews](https://okaeri.tech/developers/reference/messages.md#previewMessage)　文面のプレビュー（`previewMessage`）
- [POST /api/v1/messages/estimate](https://okaeri.tech/developers/reference/messages.md#estimateSmsSegments)　SMS の文字数と課金通数の見積（`estimateSmsSegments`）

## GET /api/v1/messages

**文面の一覧**

operationId：`listMessages`　必要なスコープ：`messages:read`

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `channel` | クエリ | `string`（null 可） | — | 値：`sms`・`email`（今後増えることがある） |
| `limit` | クエリ | `integer` | — | 1〜200・既定値 `50` |
| `cursor` | クエリ | `string`（null 可） | — | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 200 | 成功 | [MessageListOut](https://okaeri.tech/developers/reference/schemas.md#MessageListOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## POST /api/v1/messages

**文面の作成**

operationId：`createMessage`　必要なスコープ：`messages:write`

### リクエストの本文（JSON）

型：[MessageIn](https://okaeri.tech/developers/reference/schemas.md#MessageIn)（必須）

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `channel` | `string` | 必須 | 値：`sms`・`email`（今後増えることがある） |
| `subject` | `string`（null 可） | — | — |
| `body` | `string`（null 可） | — | — |
| `body_html` | `string`（null 可） | — | — |
| `header_image_url` | `string`（null 可） | — | — |
| `link_url` | `string`（null 可） | — | — |
| `link_params` | `object`（項目は未掲載） | — | 既定値 `{}` |
| `blocks` | 任意の値 の配列（null 可） | — | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 201 | 成功 | [MessageOut](https://okaeri.tech/developers/reference/schemas.md#MessageOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 409 | 状態の衝突（`invalid_request`）。`idempotency_key_in_progress`（同じ `Idempotency-Key` の要求が処理中） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## GET /api/v1/messages/{message_id}

**文面の取得**

operationId：`getMessage`　必要なスコープ：`messages:read`

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `message_id` | パス | `string`（uuid） | 必須 | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 200 | 成功 | [MessageOut](https://okaeri.tech/developers/reference/schemas.md#MessageOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 404 | 対象が見つからない（`not_found`）。他のテナントの ID を指した時も同じ 404 | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## PATCH /api/v1/messages/{message_id}

**文面の更新**

operationId：`updateMessage`　必要なスコープ：`messages:write`

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `message_id` | パス | `string`（uuid） | 必須 | — |

### リクエストの本文（JSON）

型：[MessagePatch](https://okaeri.tech/developers/reference/schemas.md#MessagePatch)（必須）

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `channel` | `string`（null 可） | — | 値：`sms`・`email`（今後増えることがある） |
| `subject` | `string`（null 可） | — | — |
| `body` | `string`（null 可） | — | — |
| `body_html` | `string`（null 可） | — | — |
| `header_image_url` | `string`（null 可） | — | — |
| `link_url` | `string`（null 可） | — | — |
| `link_params` | `object`（項目は未掲載）（null 可） | — | — |
| `blocks` | 任意の値 の配列（null 可） | — | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 200 | 成功 | [MessageOut](https://okaeri.tech/developers/reference/schemas.md#MessageOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 404 | 対象が見つからない（`not_found`）。他のテナントの ID を指した時も同じ 404 | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## DELETE /api/v1/messages/{message_id}

**文面の削除**

operationId：`deleteMessage`　必要なスコープ：`messages:write`

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `message_id` | パス | `string`（uuid） | 必須 | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 204 | 成功（本文なし） | — |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 404 | 対象が見つからない（`not_found`）。他のテナントの ID を指した時も同じ 404 | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 409 | 状態の衝突（`invalid_request`）。`message_in_use`（ステップが使っている文面） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## POST /api/v1/messages/{message_id}/duplicate

**文面の複製**

operationId：`duplicateMessage`　必要なスコープ：`messages:write`

複製（実体コピー）。作成と同じ検証・権限（`body_html` の直書きは owner / admin だけ）。

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `message_id` | パス | `string`（uuid） | 必須 | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 201 | 成功 | [MessageOut](https://okaeri.tech/developers/reference/schemas.md#MessageOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 404 | 対象が見つからない（`not_found`）。他のテナントの ID を指した時も同じ 404 | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 409 | 状態の衝突（`invalid_request`）。`idempotency_key_in_progress`（同じ `Idempotency-Key` の要求が処理中） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## GET /api/v1/message_variables

**文面で使える変数の一覧**

operationId：`listMessageVariables`　必要なスコープ：`messages:read`

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `campaign_id` | クエリ | `string`（uuid） | 必須 | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 200 | 成功 | [MessageVariablesOut](https://okaeri.tech/developers/reference/schemas.md#MessageVariablesOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 404 | `campaign_id` のキャンペーンが見つからない（`not_found`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## GET /api/v1/message_examples

**文面の例文の一覧**

operationId：`listMessageExamples`　必要なスコープ：`messages:read`

全プランで使える。プランの上限（1シナリオのステップ数）は、作った文面をステップに置く時に見る。

SMS の【ショップ名】は置き場。店名に書き換えないままでは、そのシナリオを有効化できない。

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `channel` | クエリ | `string`（null 可） | — | 値：`sms`・`email`（今後増えることがある） |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 200 | 成功 | [MessageExampleListOut](https://okaeri.tech/developers/reference/schemas.md#MessageExampleListOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## POST /api/v1/message_previews

**文面のプレビュー**

operationId：`previewMessage`　必要なスコープ：`messages:read`

### リクエストの本文（JSON）

型：[MessagePreviewIn](https://okaeri.tech/developers/reference/schemas.md#MessagePreviewIn)（必須）

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `campaign_id` | `string`（uuid） | 必須 | — |
| `subject` | `string`（null 可） | — | — |
| `blocks` | 任意の値 の配列 | 必須 | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 200 | 成功 | [MessagePreviewOut](https://okaeri.tech/developers/reference/schemas.md#MessagePreviewOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 404 | `campaign_id` のキャンペーンが見つからない（`not_found`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 409 | 状態の衝突（`invalid_request`）。`idempotency_key_in_progress`（同じ `Idempotency-Key` の要求が処理中） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## POST /api/v1/messages/estimate

**SMS の文字数と課金通数の見積**

operationId：`estimateSmsSegments`　必要なスコープ：`messages:read`

SMS 本文から文字数と課金通数の目安を返す。保存しない（読み取りスコープ `messages:read`）。数え方は文面の保存時に入る通数の目安（`sms_segments`）と同じ。

- **目安である**：URL の変数は送信時と同じ長さで展開するが、**商品名（`{{product_name}}`）は字面（16文字）のまま数える**。実際の商品名の長さは使うキャンペーンで変わるので、送信時の通数とはずれうる（実績は配信の `segments`）
- キャリアが分からないのでワーストケース（docomo の刻み）で数える
- 本文が上限（URL 展開後で660文字）を超えると 422 `sms_body_too_long`
- POST なのでテストキーでは `OKAERI-Dry-Run: true` が付くが、そもそも何も保存しない

### リクエストの本文（JSON）

型：[SmsEstimateIn](https://okaeri.tech/developers/reference/schemas.md#SmsEstimateIn)（必須）

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `body` | `string` | 必須 | 1文字以上 |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 200 | 成功 | [SmsEstimateOut](https://okaeri.tech/developers/reference/schemas.md#SmsEstimateOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 409 | 状態の衝突（`invalid_request`）。`idempotency_key_in_progress`（同じ `Idempotency-Key` の要求が処理中） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |