# 法人ユーザー向けオプションAPIリファレンス
本ドキュメントに記載の機能は、所定の申請等を行った法人ユーザーのみがご利用いただけます。自社のLINE公式アカウントでご利用になりたいお客様は、担当営業までご連絡いただくか、弊社パートナー (opens new window)にお問い合わせください。
# 共通仕様
# ステータスコード
『Messaging APIリファレンス』の「ステータスコード」を参照してください。
# レスポンスヘッダー
法人ユーザー向けオプションAPIのレスポンスには、以下のHTTPヘッダーが含まれます。
レスポンスヘッダー | 説明 |
---|---|
x-line-request-id | リクエストID。各リクエストごとに発行されるIDです。 |
# ミッションスタンプAPI
ミッションスタンプは、ミッションの達成を条件としてユーザーに提供するスタンプです。スタンプをインセンティブに、ユーザーに「ID情報の連携」や「会員登録」、「アンケート回答」などを促すことができます。
# ミッションスタンプを送る(v3)
ユーザーに、任意のタイミングでミッションスタンプを送信します。
「ミッションスタンプを送る(v2)」と異なり、このエンドポイントを呼び出すサーバーのIPアドレスまたはネットワークアドレスを、LINE Developersコンソールに登録する必要はありません。
リクエストの例
# 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
と空のレスポンスボディを返します。
# エラーレスポンス
エラー発生時は、以下の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 に指定したスタンプセットに対応していません。 |
# ミッションスタンプを送る(v2)
ユーザーに、任意のタイミングでミッションスタンプを送信します。
このエンドポイントを呼び出すサーバーのIPアドレスまたはネットワークアドレスを、LINE Developersコンソールに登録する必要があります。対象のチャネルの[セキュリティ管理]タブに、サーバーのIPアドレスまたはネットワークアドレスを追加してください。
リクエストの例
# HTTPリクエスト
POST https://api.line.me/v2/missionSticker/send
# リクエストヘッダー
Content-Type
application/json
X-Line-ChannelId
チャネルID。LINE Developersコンソールで確認できます。
X-Line-ChannelSecret
チャネルシークレット。LINE Developersコンソールで確認できます。
X-Line-Trusted-User-With-ACL
ミッションスタンプAPIの利用権限が付与されたときに、割り当てられた値。詳しくは、担当営業にお問い合わせください。
# リクエストボディ
to
String
送信先のユーザーID
messages
Array
packageId
プロパティとisPresent
プロパティを含むオブジェクトの配列。1個のみ指定できます。
messages[].packageId
String
スタンプセットのパッケージID
messages[].isPresent
Boolean
false
# レスポンス
ステータスコード200
と以下のプロパティを含むJSONオブジェクトを返します。
ticketId
String
LINEの内部で使われる値。
ticketId
が返された場合、APIリクエストは成功しています。
レスポンスの例
# エラーレスポンス
エラー発生時は、以下のJSONデータを含むレスポンスボディが返されます。
message
String
エラー情報を含むメッセージ。詳しくは、以下の「エラーメッセージ」を参照してください。
# エラーメッセージ
エラーのJSONレスポンスのmessage
プロパティに含まれる、主なエラーメッセージは以下のとおりです。
メッセージ | 説明 |
---|---|
authentication failed | 以下のいずれか、または両方です。
|
CHANNEL_MISSION_STICKER_NOT_USABLE | チャネルに、ミッションスタンプAPIの利用権限が付与されていない。 |
# オーディエンスマッチAPI
# レート制限
オーディエンスマッチAPIのAPIリクエストに関するレート制限は、Messaging APIのレート制限と同じです。
# メッセージタイプ
Messaging APIのメッセージタイプをすべて利用できます。
以下のメッセージタイプでは、URIアクション以外のアクションは設定できません。
URIアクション以外のアクションを設定すると、メッセージは送信されません。また、同じリクエストに含まれるその他のメッセージも送信されません。
# サポートされていない機能
オーディエンスマッチAPIでは、以下のプロパティやリクエストヘッダーは利用できません。
- emojisプロパティ
- X-Line-Retry-Keyリクエストヘッダー
- trackingIdプロパティ
# 電話番号を利用してメッセージを送る
ユーザーの電話番号に基づいたターゲティング配信を行います。
メッセージはプライバシーポリシー(2022年3月改訂) (opens new window)に同意済みのユーザーにのみ送信され、未同意のユーザーには送信されません。
そのため、指定した送信先の数よりも配信されたメッセージの数が少なくなることがあります。
リクエストの例
# HTTPリクエスト
POST https://api.line.me/bot/ad/multicast/phone
# リクエストヘッダー
Content-Type
application/json
Authorization
Bearer {channel access token}
# リクエストボディ
to
ハッシュ化した電話番号の配列
メッセージの送信先(E.164形式に正規化された電話番号を、SHA256でハッシュ化した値)。
最大件数:150
messages
メッセージオブジェクトの配列
送信するメッセージ。
最大件数:5
notificationDisabled
Boolean
true
:メッセージ送信時に、ユーザーに通知されない。false
:メッセージ送信時に、ユーザーに通知される。ただし、LINEで通知をオフにしている場合は通知されません。
デフォルト値はfalse
です。
# レスポンス
ステータスコード200
と空のJSONオブジェクトを返します。
レスポンスの例
# 電話番号を利用したメッセージ配信の結果を取得する
「電話番号を利用してメッセージを送る」で配信したメッセージの配信結果を取得します。
リクエストの例
# HTTPリクエスト
GET https://api.line.me/v2/bot/message/delivery/ad_phone?date={date}
# リクエストヘッダー
Content-Type
application/json
Authorization
Bearer {channel access token}
# クエリパラメータ
date
メッセージが送信された日付
- フォーマット:
yyyyMMdd
(例:20190831
) - タイムゾーン:UTC+9
# レスポンス
ステータスコード200
と以下の情報を含むJSONオブジェクトを返します。
status
String
集計処理の状態。以下のいずれかの値です。
ready
:メッセージ数を取得できます。unready
:date
に指定した日付のメッセージ数の集計がまだ完了していません。たとえば、配信当日や未来の日付を指定した場合に返されます。通常、集計処理は配信の翌日中に完了します。unavailable_for_privacy
:該当日の通数の合計が20通未満です。out_of_service
:date
に指定した日付が、集計システムの稼働開始日(2018年03月31日)より前です。
success
Long
date
に指定した日付に、電話番号を利用して配信されたメッセージの数。status
の値がready
の場合にのみ、レスポンスに含まれます。
# Mark-as-Read
# ユーザーからのメッセージに既読を付ける
特定のユーザーから送信されたすべてのメッセージに、任意のタイミングで"既読"を表示できます。
リクエストの例
# 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オブジェクトを返します。
レスポンスの例
# 任意の集計単位で統計情報を取得する
多くのエンドユーザーにプッシュメッセージやマルチキャストメッセージを送信する場合に、統計情報を集計できる機能です。この集計単位のことを「ユニット」と呼びます。ユニットを作成する手続きはありません。メッセージ送信時に任意のユニット名を付与するだけで、ユニットごとに統計情報を確認できます。
# メッセージ送信時に任意の集計単位のユニット名を付与する
プッシュメッセージやマルチキャストメッセージを送信する際に、任意の集計単位のユニット名を付与します。プッシュメッセージやマルチキャストメッセージの送信方法については、『Messaging APIリファレンス』の「メッセージ」を参照してください。
既に送信したメッセージに後からユニット名を付与したり、ユニット名を変更したりすることはできません。
同じユニット名を付与してメッセージを送ると、メッセージの内容や吹き出し数、吹き出しの順番が異なっていても、統計情報はまとめて集計されます。同一のユニット名を付与した複数のメッセージを送るときは、吹き出しの内容を揃えて送ることをおすすめします。
# リクエストボディ
customAggregationUnits
プロパティは、以下のエンドポイントのリクエストボディにて指定可能です。
customAggregationUnits
文字列の配列
任意の集計単位のユニット名。大文字と小文字は区別されます。たとえばpromotion_a
とpromotion_A
は別のユニットとして扱われます。
- 最大ユニット数:1
- 最大文字数:30
- 使用可能文字種:半角英数字(
a
〜z
、A
~Z
、0
~9
)、アンダースコア(_
)
リクエストの例
# ユニットごとの統計情報を取得する
LINE公式アカウントから送信したプッシュメッセージやマルチキャストメッセージに対して、ユーザーがどのように操作したかを示す統計情報をユニットごとに確認できます。
なお統計情報は1メッセージ(message)単位、および1吹き出し(bubble)単位で取得できます。
統計情報は、メッセージの送信時刻から14日間(1,209,600秒間)のみ更新されます。それ以降は更新されません。
たとえば2021年2月1日の21:15:00に送信した場合、統計情報は2021年2月15日の21:15:00まで更新されます。
ナローキャストメッセージまたはブロードキャストメッセージについて、メッセージごとの統計情報を取得したい場合は、次のエンドポイントを使用してください。
リクエストの例
# HTTPリクエスト
GET https://api.line.me/v2/bot/insight/message/event/aggregation?customAggregationUnit={customAggregationUnit}&from={from}&to={to}
# リクエストヘッダー
Authorization
Bearer {channel access token}
# クエリパラメータ
customAggregationUnit
String
メッセージ送信時に指定した任意の集計単位のユニット名。大文字と小文字は区別されます。たとえばpromotion_a
とpromotion_A
は別のユニットとして扱われます。
from
String
集計対象期間の開始日。
- フォーマット:
yyyyMMdd
(例:20210301
) - タイムゾーン:UTC+9
to
String
集計対象期間の終了日。終了日は、開始日の30日後まで指定できます。たとえば、開始日が20210301
の場合、終了日は20210331
まで指定できます。
- フォーマット:
yyyyMMdd
(例:20210331
) - タイムゾーン:UTC+9
# レスポンス
ステータスコード200
と以下の情報を含むJSONオブジェクトを返します。
統計情報の数値は、多少の誤差を含むことがあります。
またプライバシーを保護するため、次のような場合、個人の操作に関するプロパティの値はnull
になります。
- プロパティの値が20未満だった場合
- プロパティの値が20以上であっても、そのイベントを発生させた実人数が20人未満だった場合(たとえば
messages[].mediaPlayed
は30だが、messages[].uniqueMediaPlayed
が15だった場合は、どちらの値もnull
になります)
overview
Object
メッセージに関する統計情報。
overview.uniqueImpression
Number
メッセージを開封した人数。少なくとも1つの吹き出しを表示した人数です。
overview.uniqueClick
Number
メッセージ内のいずれかのURLをタップした人数。
overview.uniqueMediaPlayed
Number
メッセージ内のいずれかの動画または音声の再生を開始した人数。
overview.uniqueMediaPlayed100Percent
Number
メッセージ内のいずれかの動画または音声を最後まで視聴した人数。
messages
Array
吹き出しに関する情報を表す配列。
messages[].seq
Number
吹き出しの通し番号。
messages[].impression
Number
吹き出しが表示された回数。
messages[].mediaPlayed
Number
吹き出し内の動画または音声が再生開始された回数。
messages[].mediaPlayed25Percent
Number
吹き出し内の動画または音声が再生開始され、25%再生された回数。
messages[].mediaPlayed50Percent
Number
吹き出し内の動画または音声が再生開始され、50%再生された回数。
messages[].mediaPlayed75Percent
Number
吹き出し内の動画または音声が再生開始され、75%再生された回数。
messages[].mediaPlayed100Percent
Number
吹き出し内の動画または音声が再生開始され、100%再生された回数。
messages[].uniqueMediaPlayed
Number
吹き出し内の動画または音声を再生開始した人数。
messages[].uniqueMediaPlayed25Percent
Number
吹き出し内の動画または音声を再生開始し、25%再生した人数。
messages[].uniqueMediaPlayed50Percent
Number
吹き出し内の動画または音声を再生開始し、50%再生した人数。
messages[].uniqueMediaPlayed75Percent
Number
吹き出し内の動画または音声を再生開始し、75%再生した人数。
messages[].uniqueMediaPlayed100Percent
Number
吹き出し内の動画または音声を再生開始し、100%再生した人数。
clicks
Array
タップしたURLに関する情報を表す配列。
clicks[].seq
Number
URLが含まれていた吹き出しの通し番号。
clicks[].url
String
URL。
clicks[].click
Number
吹き出し内のURLをタップした回数。
clicks[].uniqueClick
Number
吹き出し内のURLをタップした人数。
clicks[].uniqueClickOfRequest
Number
メッセージ内のURLのうちurl
と同じURLをタップした人数。ほかの吹き出しに同じURLが設定されている場合に、1人のユーザーが各URLをタップした場合でも、1回だけカウントされます。
レスポンスの例
# 当月に利用したユニットの数を取得する
当月に利用した任意の集計単位のユニット数を取得します。
任意の集計単位で統計情報を取得する機能では、1つのチャネルにつき当月中に最大で1,000種類のユニット名を利用できます。ユニット数は毎月1日にリセットされて、また1からカウントされます。当月中に1,001種類目のユニット名を付与した場合、メッセージの送信はできますが、当該ユニット名は付与されていないものとして扱われます。
リクエストの例
# HTTPリクエスト
GET https://api.line.me/v2/bot/message/aggregation/info
# リクエストヘッダー
Authorization
Bearer {channel access token}
# レスポンス
ステータスコード200
と以下の情報を含むJSONオブジェクトを返します。
numOfCustomAggregationUnits
Number
今月利用した統計情報集計のユニット数。
レスポンスの例
# 当月に利用したユニット名のリストを取得する
当月に利用した統計情報集計のユニット名のリストを取得します。
リクエストの例
# HTTPリクエスト
GET https://api.line.me/v2/bot/message/aggregation/list
# リクエストヘッダー
Authorization
Bearer {channel access token}
# クエリパラメータ
limit
String
1回のリクエストで取得する統計情報集計のユニットの最大数です。デフォルト値は100
です。
最大値:100
start
String
継続トークンの値。レスポンスで返されるJSONオブジェクトのnext
プロパティに含まれます。1回のリクエストで任意の集計単位のユニットをすべて取得できない場合は、このパラメータを指定して残りの配列を取得します。
# レスポンス
ステータスコード200
と以下の情報を含むJSONオブジェクトを返します。
customAggregationUnits
文字列の配列
今月利用した統計情報集計のユニット名のリスト。
next
String
継続トークン。統計情報集計のユニット名の、次の配列を取得するために使用します。このプロパティは、前回までのレスポンスのcustomAggregationUnits
で取得しきれなかったユニットがある場合にのみ返されます。
レスポンスの例
# LINE通知メッセージAPI
# レート制限
LINE通知メッセージAPIは、Messaging APIのレート制限に準拠します。
# LINE通知メッセージを送る
ユーザーの電話番号を指定してLINE通知メッセージを送るAPIです。
LINE通知メッセージを送る場合、Messaging APIチャネルの[セキュリティ設定]タブで、LINEプラットフォームのAPIを呼び出せるサーバーのIPアドレスを登録しないでください。リクエスト元のIPアドレスを制限した状態でLINE通知メッセージを送ると、送信に失敗することがあります。設定方法について詳しくは、「セキュリティを設定する(任意)」を参照してください。
メッセージはプライバシーポリシー(2022年3月改訂) (opens new window)に同意済みのユーザーにのみ送信され、未同意のユーザーには送信されません。
リクエストの例
# 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の例
# リクエストボディ
to
メッセージの送信先。E.164形式に正規化しSHA256でハッシュ化した電話番号を指定してください。
- グループトークと複数人トークは送信対象として指定できません。
- 複数の電話番号を送信対象として指定することはできません。
- 日本、タイ、台湾、インドネシアで発行された電話番号かつ、LINEアプリにおいて電話番号による認証を行うことができる電話番号 (opens new window)のみが送信対象として指定できます。これら以外の電話番号が指定された場合、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年03月31日)より前です。
success
Number
date
に指定した日付に、LINE通知メッセージAPIを使って送信されたメッセージの数。status
の値がready
の場合にのみ、レスポンスに含まれます。
レスポンスの例
# エラーレスポンス
HTTP ステータスコード400
番台のエラーと共に、エラーの情報を含むJSONオブジェクトを返します。共通仕様の「エラーレスポンス」を参照してください。