法人ユーザー向けオプションAPIリファレンス

# 法人ユーザー向けオプションAPIリファレンス

オプション機能を利用するには手続きが必要です

本ドキュメントに記載の機能は、所定の申請等を行った法人ユーザーのみがご利用いただけます。自社のLINE公式アカウントでご利用になりたいお客様は、担当営業までご連絡いただくか、弊社パートナー (opens new window)にお問い合わせください。

# 共通仕様

# ステータスコード

『Messaging APIリファレンス』の「ステータスコード」を参照してください。

# レスポンスヘッダー

法人ユーザー向けオプションAPIのレスポンスには、以下のHTTPヘッダーが含まれます。

レスポンスヘッダー	説明
x-line-request-id	リクエストID。各リクエストごとに発行されるIDです。

# ミッションスタンプAPI

ミッションスタンプは、ミッションの達成を条件としてユーザーに提供するスタンプです。スタンプをインセンティブに、ユーザーに「ID情報の連携」や「会員登録」、「アンケート回答」などを促すことができます。

# ミッションスタンプを送る（v3）

ユーザーに、任意のタイミングでミッションスタンプを送信します。

リクエストの例

# HTTPリクエスト

POST https://api.line.me/shop/v3/mission

# リクエストヘッダー

Content-Type

必須

application/json

Authorization

必須

Bearer {channel access token}

# リクエストボディ

String

必須

送信先のユーザーID

productType

String

必須

STICKER

productId

String

必須

スタンプセットのパッケージID

sendPresentMessage

Boolean

必須

false

# レスポンス

ステータスコード200と空のレスポンスボディを返します。

# エラーレスポンス

エラー発生時は、以下のJSONデータを含むレスポンスボディが返されます。

message

String

エラー情報を含むメッセージ。詳しくは、以下の「エラーメッセージ」を参照してください。

# エラーメッセージ

エラーのJSONレスポンスのmessageプロパティに含まれる、主なエラーメッセージは以下のとおりです。

メッセージ	説明
invalid request	`to`に指定した送信先のユーザーIDが無効です。
not found	`productId`に指定したパッケージIDが無効です。
internal error	`productId`に指定したパッケージIDが無効です。
not allowed to use the API	チャネルに、ミッションスタンプAPIの利用権限が付与されていない。
not_sales_period	スタンプセットを送信した日時が、スタンプセットの有効期間外です。
not sale for country	`to`に指定した送信先のユーザーの国では、`productId`に指定したスタンプセットが利用できません。
not sale for device	`to`に指定した送信先のユーザーが利用している端末は、`productId`に指定したスタンプセットに対応していません。
not sale for version	`to`に指定した送信先のユーザーが利用しているLINEアプリは、`productId`に指定したスタンプセットに対応していません。

# 既読API

# ユーザーからのメッセージに既読を付ける

特定のユーザーから送信されたすべてのメッセージに「既読」を表示できます。

リクエストの例

# HTTPリクエスト

POST https://api.line.me/v2/bot/message/markAsRead

# リクエストヘッダー

Content-Type

必須

application/json

Authorization

必須

Bearer {channel access token}

# リクエストボディ

chat.userId

String

必須

対象のユーザーID。

# レスポンス

ステータスコード200と空のJSONオブジェクトを返します。

レスポンスの例

# LINE通知メッセージAPI

# レート制限

LINE通知メッセージAPIは、Messaging APIのレート制限に準拠します。

# LINE通知メッセージが送信される条件

以下の条件をすべて満たす場合に、ユーザーに対してメッセージが送信されます。

LINE通知メッセージの送信対象として指定した電話番号が、ユーザーがLINEに登録している電話番号と一致していること
ユーザーがLINEに登録している電話番号が有効であること（SMSによる電話番号認証を、一定期間内に一度実施している）
ユーザーがLINE通知メッセージの受信に同意していること
ユーザーがLINE通知メッセージ送信元であるLINE公式アカウントをブロックしていないこと
LINE通知メッセージの送信対象として指定した電話番号が、日本、タイ、台湾、インドネシアで発行された電話番号かつ、LINEアプリにおいて電話番号による認証を行うことができる電話番号 (opens new window)であること
ユーザーが「LINEのプライバシーポリシー（2022年3月改訂） (opens new window)」に同意していること

LINEアプリでのLINE通知メッセージの設定について詳しくは、『LINEみんなの使い方ガイド』の「LINE通知メッセージを受信する方法 (opens new window)」を参照してください。

# LINE通知メッセージを送る

ユーザーの電話番号を指定してLINE通知メッセージを送るAPIです。

リクエスト元IPアドレスの制限について

LINE通知メッセージを送る場合、Messaging APIチャネルの［セキュリティ設定］タブで、LINEプラットフォームのAPIを呼び出せるサーバーのIPアドレスを登録しないでください。リクエスト元のIPアドレスを制限した状態でLINE通知メッセージを送ると、送信に失敗することがあります。設定方法について詳しくは、「セキュリティを設定する（任意）」を参照してください。

リクエストの例

# HTTPリクエスト

POST https://api.line.me/bot/pnp/push

# リクエストヘッダー

サポートしていない機能

LINE通知メッセージAPIでは、リトライキー（X-Line-Retry-Key）を使ったAPIリクエストの再試行はできません。

Content-Type

必須

application/json

Authorization

必須

Bearer {channel access token}

X-Line-Delivery-Tag

任意

Webhookを介して、配信完了イベントのdelivery.dataプロパティで返される文字列。詳しくは、「メッセージの送信通知を受信する」を参照してください。
最小文字数：16
最大文字数：100

X-Line-Delivery-Tagの例

# リクエストボディ

必須

メッセージの送信先。E.164形式に正規化しSHA256でハッシュ化した電話番号を指定してください。

メッセージの送信条件について詳しくは、「LINE通知メッセージが送信される条件」を参照してください。

注意

グループトークと複数人トークは送信対象として指定できません。
複数の電話番号を送信対象として指定することはできません。

messages

メッセージオブジェクトの配列

必須

送信するメッセージ。最大件数：5

詳しくは、「LINE通知メッセージAPIで送信可能なメッセージ」を参照してください。

# レスポンス

ステータスコード200と空のJSONオブジェクトを返します。

レスポンスの例

# エラーレスポンス

HTTPステータスコード400番台のエラーと共に、エラーの情報を含むJSONオブジェクトを返します。共通仕様の「エラーレスポンス」を参照してください。

以下のHTTPステータスコード422と共に発生するエラーは、LINE通知メッセージAPI専用のエラーです。

message

String

LINE通知メッセージAPIによる LINE通知メッセージの送信に失敗しました。以下のような理由が考えられます。

メッセージ送信対象に指定した電話番号に紐づくLINEユーザーが存在しません。
メッセージ送信対象に指定した電話番号は、LINE通知メッセージのサービス対象国で発行されたものではありません。
メッセージ送信対象に指定した電話番号に紐づくLINEユーザーがLINE通知メッセージの受信を拒否しています。
メッセージ送信対象に指定した電話番号に紐づくLINEユーザーは、LINEのプライバシーポリシー（2022年3月改定） (opens new window)に同意していません。

エラーレスポンスの例

# 送信済みのLINE通知メッセージの数を取得する

/bot/pnp/pushエンドポイントを使って送信された、LINE通知メッセージの数を取得します。

詳しくは、LINE通知メッセージドキュメントの「送信済みLINE通知メッセージの数を取得する」を参照してください。

リクエストの例

# HTTPリクエスト

GET https://api.line.me/v2/bot/message/delivery/pnp

# リクエストヘッダー

Authorization

必須

Bearer {channel access token}

# クエリパラメータ

date

必須

メッセージが送信された日付

フォーマット：yyyyMMdd（例：20211231）
タイムゾーン：UTC+9

# レスポンス

ステータスコード200と以下の情報を含むJSONオブジェクトを返します。

status

String

集計処理の状態。以下のいずれかの値です。

ready：メッセージ数を取得できます。
unready：dateに指定した日付のメッセージ数の集計がまだ完了していません。しばらくしてからリクエストを再実行してください。通常、集計処理は翌日中に完了します。
out_of_service：dateに指定した日付が、集計システムの稼働開始日（2018年3月31日）より前です。

success

Number

含まれないことがあります

dateに指定した日付に、LINE通知メッセージAPIを使って送信されたメッセージの数。statusの値がreadyの場合にのみ、レスポンスに含まれます。

レスポンスの例

# エラーレスポンス

HTTP ステータスコード400番台のエラーと共に、エラーの情報を含むJSONオブジェクトを返します。共通仕様の「エラーレスポンス」を参照してください。

# モジュール

# モジュールチャネルの提供者の操作で連携（アタッチ）する

モジュールチャネルをLINE公式アカウントにアタッチします。アタッチするためには、LINE公式アカウントの管理者に認可を要求し、認可コードを取得する必要があります。モジュールの認可フローについて詳しくは、『モジュールドキュメント』の「モジュールチャネルを連携（アタッチ）する」を参照してください。

このAPIを利用する際には、Authorizationヘッダーもしくはリクエストボディのどちらかを使って、モジュールチャネルのチャネルIDとチャネルシークレットを指定する必要があります。

リクエストの例

# HTTPリクエスト

POST https://manager.line.biz/module/auth/v1/token

# リクエストヘッダー

Content-Type

必須

application/x-www-form-urlencoded

Authorization

任意

Basic {base64({Channel ID}:{Channel Secret})}

{base64({Channel ID}:{Channel Secret})}には、「モジュールチャネルのチャネルID」と「モジュールチャネルのチャネルシークレット」を:で連結し、Base64でエンコードした文字列を指定してください。モジュールチャネルのチャネルIDとチャネルシークレットは、LINE Developersコンソールで確認できます。

リクエストボディ内でclient_idおよびclient_secretを指定する代わりに、このヘッダを使ってモジュールチャネルのチャネルIDとチャネルシークレットを指定できます。

# リクエストボディ

grant_type

String

必須

authorization_code

code

String

必須

LINEプラットフォームから渡された認可コードを指定します。

redirect_uri

String

必須

認証と認可のためのURLで指定したredirect_uriを指定します。

code_verifier

String

任意

認可コード横取り攻撃への対策としてOAuth 2.0の拡張仕様で定義されるPKCE（Proof Key for Code Exchange）を利用した場合に指定します。

RFC 7636 (opens new window)に準拠しています。

client_id

String

任意

Authorizationヘッダーを使用する代わりに、このパラメータを使ってモジュールチャネルのチャネルIDを指定できます。モジュールチャネルのチャネルIDは、LINE Developersコンソールで確認できます。

client_secret

String

任意

Authorizationヘッダーを使用する代わりに、このパラメータを使ってモジュールチャネルのチャネルシークレットを指定できます。モジュールチャネルのチャネルシークレットは、LINE Developersコンソールで確認できます。

region

String

任意

認証と認可のためのURLでregionに値を指定した場合、同じ値を指定してください。

basic_search_id

String

任意

認証と認可のためのURLでbasic_search_idに値を指定した場合、同じ値を指定してください。

scope

String

任意

認証と認可のためのURLでscopeに値を指定した場合、同じ値を指定してください。

brand_type

String

任意

認証と認可のためのURLでbrand_typeに値を指定した場合、同じ値を指定してください。

# レスポンス

成功時は、ステータスコード200と以下の情報を含むJSONオブジェクトを返します。

bot_id

String

LINE公式アカウントのボットのユーザーID。

ボットのユーザーIDは、Messaging APIやAcquire Control APIを呼び出す際に利用します。

注意

ボットのユーザーIDは、LINE Developersコンソールで、Messaging APIチャネルの［チャネル基本設定］タブに表示される［あなたのユーザーID］ではありません。

scope

String

LINE公式アカウントの管理者によって許可された権限（スコープ）。

レスポンスの例

# エラーレスポンス

以下のHTTPステータスコードを返します。

400 Bad Request
403 Forbidden

# モジュールチャネルの管理者の操作でモジュールチャネルを連携解除（デタッチ）する

LINE公式アカウントからモジュールチャネルをデタッチします。

リクエストの例

# HTTPリクエスト

POST https://api.line.me/v2/bot/channel/detach

# リクエストヘッダー

Content-Type

必須

application/json

Authorization

必須

Bearer {channel access token}

{channel access token}には、モジュールチャネルのチャネルアクセストークンを指定してください。

# リクエストボディ

botId

String

必須

モジュールチャネルにアタッチされたLINE公式アカウントのボットのユーザーID。

ボットのユーザーIDは、「モジュールチャネルの提供者の操作で連携（アタッチ）する」のレスポンスやAttachedイベントで取得できます。

# レスポンス

成功時は、ステータスコード200を返します。

# エラーレスポンス

HTTPステータスコード400を返します。

# Acquire Control API

Standby Channelが主導権（Chat Control）を取得する場合は、Acquire Control APIを呼び出します。

それまでActive Channelだったチャネルは、自動的にStandby Channelに切り替わります。

警告

現在提供しているモジュールの仕組みにおいては、本APIを呼び出す必要はありません。そのため本APIの実装は任意となります。

本APIは現状、想定外の問題等によりチャットの主導権が切り替わった際にのみ利用します。

リクエストの例

# HTTPリクエスト

POST https://api.line.me/v2/bot/chat/{chatId}/control/acquire

# リクエストヘッダー

Content-Type

必須

application/json

Authorization

必須

Bearer {channel access token}

{channel access token}には、モジュールチャネルのチャネルアクセストークンを指定してください。

ボットのユーザーIDを指定するヘッダー

必須

モジュールチャネルにアタッチされたLINE公式アカウントのボットのユーザーID。

ボットのユーザーIDは、「モジュールチャネルの提供者の操作で連携（アタッチ）する」のレスポンスやAttachedイベントで取得できます。

ヘッダーの詳細については参画される際に別途提供いたします

本ヘッダーの名前（パラメーター名）は、実際にLINEマーケットプレイス (opens new window)に参画するお客様に限定して公開しています。

# パスパラメータ

chatId

必須

userId、roomId、またはgroupId

# リクエストボディ

expired

Boolean

任意

True：制限時間（ttl）を経過すると、主導権（Chat Control）がPrimary Channelに戻ります。（デフォルト）
False：制限時間がなく、主導権（Chat Control）は時間経過では変わりません。

ttl

Number

任意

主導権（Chat Control）がPrimary Channelに戻るまでの時間（モジュールチャネルがActive Channelでいられる時間）。秒で指定します。最大値は1年間（3600 * 24 * 365）。デフォルト値は3600（1時間）です。

※expiredの値がfalseの場合は、無視されます。

# レスポンス

成功時は、ステータスコード200を返します。

# エラーレスポンス

以下のHTTPステータスコードを返します。

400 Bad Request
403 Forbidden
404 Not Found
423 Locked
- 一定期間内（数秒程度）で、別のチャネルが主導権（Chat Control）を取得した際に発生するエラーです。

# Release Control API

Active Channelが持っている主導権（Chat Control）を、Primary Channelに返却する場合は、Release Control APIを呼び出します。

警告

現在提供しているモジュールの仕組みにおいては、本APIを呼び出す必要はありません。そのため本APIの実装は任意となります。

本APIは現状、想定外の問題等によりチャットの主導権が切り替わった際にのみ利用します。

リクエストの例

# HTTPリクエスト

POST https://api.line.me/v2/bot/chat/{chatId}/control/release

# リクエストヘッダー

Content-Type

必須

application/json

Authorization

必須

Bearer {channel access token}

{channel access token}には、モジュールチャネルのチャネルアクセストークンを指定してください。

ボットのユーザーIDを指定するヘッダー

必須

モジュールチャネルにアタッチされたLINE公式アカウントのボットのユーザーID。

ボットのユーザーIDは、「モジュールチャネルの提供者の操作で連携（アタッチ）する」のレスポンスやAttachedイベントで取得できます。

ヘッダーの詳細については参画される際に別途提供いたします

本ヘッダーの名前（パラメーター名）は、実際にLINEマーケットプレイス (opens new window)に参画するお客様に限定して公開しています。

# パスパラメータ

chatId

必須

userId、roomId、またはgroupId

# レスポンス

成功時は、ステータスコード200を返します。

# エラーレスポンス

以下のHTTPステータスコードを返します。

400 Bad Request
403 Forbidden
404 Not Found

# モジュールチャネル専用のWebhookイベントオブジェクト

# Attachedイベント

モジュールチャネルが、LINE公式アカウントにアタッチされたことを示すイベントです。モジュールチャネルのWebhook URLサーバーに送信されます。

timestampなど

「共通プロパティ」を参照してください。

ただし、modeはactive固定です。

type

String

module

module.type

String

attached

module.botId

String

アタッチされたLINE公式アカウントのボットのユーザーID

module.scopes

Array

LINE公式アカウントの管理者によって許可されたスコープを示す文字列の配列です。

Attachedイベントの例

# Detachedイベント

モジュールチャネルが、LINE公式アカウントからデタッチされたことを示すイベントです。モジュールチャネルのWebhook URLサーバーに送信されます。

LINE公式アカウントを削除する操作をしたときにはDetachされません

LINE Official Account ManagerでLINE公式アカウントを削除する操作をしたときは、モジュールチャネルはデタッチされません。

削除する操作をしてから3か月が経過し、LINE公式アカウントの分析データを含むすべての情報が完全に削除されると、自動的にデタッチされます。

timestampなど

「共通プロパティ」を参照してください。

ただし、modeはactive固定です。

type

String

module

module.type

String

detached

module.botId

String

連携解除されたLINE公式アカウントのボットのユーザーID

module.reason

String

連携解除された理由

bot_deleted：LINE公式アカウントの分析データを含むすべての情報が完全に削除されました。

Detachedイベントの例

# Activatedイベント

Acquire Control APIを呼び出して、モジュールチャネルがActive Channelに切り替わったことを示すイベントです。モジュールチャネルのWebhook URLサーバーに送信されます。

注意

Acquire Control APIで指定した有効期間がきれて、主導権（Chat Control）が切り替わった場合は、Activatedイベントは送信されません。

timestamp、sourceなど

「共通プロパティ」を参照してください。

ただし、modeはactive固定です。

type

String

activated

chatControl.expireAt

Number

“active”が維持される期限。

Activatedイベントの例

# Deactivatedイベント

Acquire Control APIまたはRelease Control APIを呼び出して、モジュールチャネルがStandby Channelに切り替わったことを示すイベントです。モジュールチャネルのWebhook URLサーバーに送信されます。

注意

Acquire Control APIで指定した有効期間がきれて、主導権（Chat Control）が切り替わった場合は、Deactivatedイベントは送信されません。

timestamp、sourceなど

「共通プロパティ」を参照してください。

ただし、modeはactive固定です。

type

String

deactivated

Deactivatedイベントの例

# botSuspendイベント

LINE公式アカウントが一時停止状態（Suspend）になったことを示すイベントです。モジュールチャネルのWebhook URLサーバーに送信されます。

このイベントを受信したときは、以下のような処理を行うことを推奨します。

モジュールチャネルの管理画面に「LINE公式アカウントが利用できない状態になっているため、この管理画面は利用できません」といったメッセージを表示し、管理画面の利用を停止する。
いったん一時停止状態になっても、一時停止状態から復帰する可能性（botResumeイベントを受信する可能性）があります。すべての情報を保持しておくことを推奨します。

注意

Primary ChannelにはbotSuspendイベントは送信されません。

botSuspendイベントを受信したあとでDetachedイベントを受信した場合は、LINE公式アカウントがモジュールチャネルの利用を停止し、契約を解除したことを示します。

timestampなど

「共通プロパティ」を参照してください。

ただし、modeはactive固定です。

type

String

botSuspended

botSuspendイベントの例

# botResumedイベント

LINE公式アカウントが一時停止状態から復帰したことを示すイベントです。モジュールチャネルのWebhook URLサーバーに送信されます。

このイベントを受信したときは、モジュールチャネルの管理画面で「LINE公式アカウントが利用できない状態になっているため、この管理画面は利用できません」といったメッセージを非表示にし、管理画面の利用を再開することを推奨します。

注意

Primary ChannelにはbotResumedイベントは送信されません。

timestampなど

「共通プロパティ」を参照してください。

ただし、modeはactive固定です。

type

String

botResumed

botResumedイベントの例

# モジュールをアタッチしたボットのリストを取得する

モジュールチャネルをアタッチした、複数のLINE公式アカウントのボットの基本情報をリストで取得します。

リクエストの例

# HTTPリクエスト

GET https://api.line.me/v2/bot/list?limit={limit}&start={continuationToken}

# リクエストヘッダー

Authorization

必須

Bearer {channel access token}

{channel access token}には、モジュールチャネルのチャネルアクセストークンを指定してください。

# クエリパラメータ

limit

任意

基本情報を取得するボットの最大個数を指定します。デフォルト値は100です。
最大値：100

start

任意

継続トークンの値。レスポンスで返されるJSONオブジェクトのnextプロパティに含まれます。1回のリクエストでボットの基本情報をすべて取得できない場合は、このパラメータを指定して残りの配列を取得します。

# レスポンス

成功時は、ステータスコード200と以下の情報を含むJSONオブジェクトを返します。

bots

Array

ボットの基本情報を表すBot list Item objectの配列。

bots[].userId

String

ボットのユーザーID

bots[].basicId

String

ボットのベーシックID

bots[].premiumId

String

含まれないことがあります

ボットのプレミアムID。プレミアムIDが未設定の場合、この値は含まれません。

bots[].displayName

String

ボットの表示名

bots[].pictureUrl

String

含まれないことがあります

プロフィール画像のURL。「https://」から始まる画像URLです。ボットにプロフィール画像を設定していない場合は、レスポンスに含まれません。

String

含まれないことがあります

継続トークン。ボットの基本情報の、次の配列を取得するために使用します。このプロパティは、取得しきれなかったボットの基本情報が存在する場合にのみ返されます。

継続トークンの有効期限は24時間（86,400秒間）です。

レスポンスの例

# エラーレスポンス

HTTPステータスコード400を返します。

エラーレスポンスの例

レート制限 LINE通知メッセージが送信される条件 LINE通知メッセージを送る送信済みのLINE通知メッセージの数を取得する

モジュール

モジュールチャネルの提供者の操作で連携（アタッチ）するモジュールチャネルの管理者の操作でモジュールチャネルを連携解除（デタッチ）する Acquire Control API Release Control API モジュールチャネル専用のWebhookイベントオブジェクトモジュールをアタッチしたボットのリストを取得する