法人ユーザー向けオプションAPIリファレンス
本ドキュメントに記載の機能は、所定の申請等を行った法人ユーザーのみがご利用いただけます。自社のLINE公式アカウントでご利用になりたいお客様は、担当営業までご連絡いただくか、弊社パートナーにお問い合わせください。
共通仕様
ステータスコード
『Messaging APIリファレンス』の「ステータスコード」を参照してください。
レスポンスヘッダー
法人ユーザー向けオプションAPIのレスポンスには、以下のHTTPヘッダーが含まれます。
レスポンスヘッダー | 説明 |
---|---|
x-line-request-id | リクエストID。各リクエストごとに発行されるIDです。 |
ミッションスタンプAPI
ミッションスタンプは、ミッションの達成を条件としてユーザーに提供するスタンプです。スタンプをインセンティブに、ユーザーに「ID情報の連携」や「会員登録」、「アンケート回答」などを促すことができます。
ユーザーにミッションスタンプを提供する
ミッションを達成したユーザーに、ミッションスタンプのダウンロード権限を付与します。
リクエストの例
HTTPリクエスト
POST https://api.line.me/shop/v3/mission
リクエストヘッダー
Content-Type
application/json
Authorization
Bearer {channel access token}
リクエストボディ
to
String
ダウンロード権限を付与するユーザーのユーザーID
productType
String
STICKER
productId
String
スタンプセットのパッケージID
sendPresentMessage
Boolean
false
レスポンス
ステータスコード200
と空のレスポンスボディを返します。
エラーレスポンス
エラー発生時は、エラーに応じたHTTPステータスコードと、以下のJSONデータを含むレスポンスボディが返されます。
message
String
エラー情報を含むメッセージ。詳しくは、以下の「エラーメッセージ」を参照してください。
エラーメッセージ
主なエラーのHTTPステータスコードと、JSONデータのmessage
プロパティに含まれるエラーメッセージは以下のとおりです。
コード | メッセージ | 説明 |
---|---|---|
400 | invalid request | to に指定した送信先のユーザーIDが無効です。 |
400 | illegal argument | productId に指定したスタンプセットがミッションスタンプとして設定されていません。 |
400 | not_sales_period | productId に指定したスタンプセットが有効期間外です。 |
400 | not sale for country | to に指定した送信先のユーザーの国では、productId に指定したスタンプセットが利用できません。 |
400 | not sale for device | to に指定した送信先のユーザーが利用している端末は、productId に指定したスタンプセットに対応していません。 |
400 | not sale for version | to に指定した送信先のユーザーが利用しているLINEアプリのバージョンは、productId に指定したスタンプセットに対応していません。 |
403 | not allowed to use the API | チャネルに、ミッションスタンプAPIの利用権限が付与されていません。 |
404 | not found | productId に指定したスタンプセットが存在しません。 |
既読API
ユーザーからのメッセージに既読を付ける
特定のユーザーから送信されたすべてのメッセージに「既読」を表示できます。
リクエストの例
HTTPリクエスト
POST https://api.line.me/v2/bot/message/markAsRead
レート制限
2,000リクエスト/秒
リクエストヘッダー
Content-Type
application/json
Authorization
Bearer {channel access token}
リクエストボディ
chat.userId
String
対象のユーザーID。
レスポンス
ステータスコード200
と空の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に準拠しています。
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
レート制限
2,000リクエスト/秒
リクエストヘッダー
Content-Type
application/json
Authorization
Bearer {channel access token}
{channel access token}
には、モジュールチャネルのチャネルアクセストークンを指定してください。
リクエストボディ
botId
String
モジュールチャネルにアタッチされたLINE公式アカウントのボットのユーザーID。
ボットのユーザーIDは、「モジュールチャネルの提供者の操作で連携(アタッチ)する」のレスポンスやAttachedイベントで取得できます。
レスポンス
成功時は、ステータスコード200
を返します。
エラーレスポンス
以下のHTTPステータスコードと、エラーレスポンスを返します。
コード | 説明 |
---|---|
400 | モジュールチャネルを連携解除(デタッチ)できませんでした。次のような理由が考えられます。
|
詳しくは、『Messaging APIリファレンス』の「ステータスコード」および「エラーレスポンス」を参照してください。
エラーレスポンスの例
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
レート制限
2,000リクエスト/秒
リクエストヘッダー
Content-Type
application/json
Authorization
Bearer {channel access token}
{channel access token}
には、モジュールチャネルのチャネルアクセストークンを指定してください。
ボットのユーザーIDを指定するヘッダー
モジュールチャネルにアタッチされたLINE公式アカウントのボットのユーザーID。
ボットのユーザーIDは、「モジュールチャネルの提供者の操作で連携(アタッチ)する」のレスポンスやAttachedイベントで取得できます。
本ヘッダーの名前(パラメーター名)は、実際にLINEマーケットプレイスに参画するお客様に限定して公開しています。
パスパラメータ
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 | chatId パラメータに、不正なIDが指定されています。 |
404 | 主導権(Chat Control)を取得できませんでした。次のような理由が考えられます。
|
423 | 別のチャネルが、一定期間内(数秒程度)に主導権(Chat Control)を取得していた場合。 |
詳しくは、『Messaging APIリファレンス』の「ステータスコード」および「エラーレスポンス」を参照してください。
エラーレスポンスの例
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
レート制限
2,000リクエスト/秒
リクエストヘッダー
Content-Type
application/json
Authorization
Bearer {channel access token}
{channel access token}
には、モジュールチャネルのチャネルアクセストークンを指定してください。
ボットのユーザーIDを指定するヘッダー
モジュールチャネルにアタッチされたLINE公式アカウントのボットのユーザーID。
ボットのユーザーIDは、「モジュールチャネルの提供者の操作で連携(アタッチ)する」のレスポンスやAttachedイベントで取得できます。
本ヘッダーの名前(パラメーター名)は、実際にLINEマーケットプレイスに参画するお客様に限定して公開しています。
パスパラメータ
chatId
userId
、roomId
、またはgroupId
レスポンス
成功時は、ステータスコード200
を返します。
エラーレスポンス
以下のHTTPステータスコードと、エラーレスポンスを返します。
コード | 説明 |
---|---|
400 | chatId パラメータに、不正なIDが指定されています。 |
詳しくは、『Messaging APIリファレンス』の「ステータスコード」および「エラーレスポンス」を参照してください。
エラーレスポンスの例
モジュールチャネル専用のWebhookイベントオブジェクト
Attachedイベント
モジュールチャネルが、LINE公式アカウントにアタッチされたことを示すイベントです。モジュールチャネルのWebhook URLサーバーに送信されます。
timestampなど
「共通プロパティ」を参照してください。
ただし、mode
はactive
固定です。
type
String
module
module.type
String
attached
module.botId
String
アタッチされたLINE公式アカウントのボットのユーザーID
module.scopes
Array of strings
LINE公式アカウントの管理者によって許可されたスコープを示す文字列の配列です。
Attachedイベントの例
Detachedイベント
モジュールチャネルが、LINE公式アカウントからデタッチされたことを示すイベントです。モジュールチャネルのWebhook URLサーバーに送信されます。
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}
レート制限
2,000リクエスト/秒
リクエストヘッダー
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です。ボットにプロフィール画像を設定していない場合は、レスポンスに含まれません。
next
String
継続トークン。ボットの基本情報の、次の配列を取得するために使用します。このプロパティは、取得しきれなかったボットの基本情報が存在する場合にのみ返されます。
継続トークンの有効期間は24時間(86,400秒間)です。
レスポンスの例