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

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

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

# 共通仕様

# ステータスコード

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

# ミッションスタンプ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 以下のいずれか、または両方です。
  • リクエストヘッダーのX-Line-ChannelId、X-Line-ChannelSecret、X-Line-Trusted-User-With-ACLに設定した値のいずれかが間違っている。
  • APIを呼び出したサーバーがLINE Developersコンソールの[セキュリティ管理]タブに登録されていない。
CHANNEL_MISSION_STICKER_NOT_USABLE チャネルに、ミッションスタンプAPIの利用権限が付与されていない。

# オーディエンスマッチAPI

# レート制限

オーディエンスマッチAPIのAPIリクエストに関する制限は、Messaging APIのレート制限と同じです。

# メッセージタイプ

Messaging APIのメッセージタイプをすべて利用できます。

利用できないアクションについて

以下のメッセージタイプでは、URIアクション以外のアクションは設定できません。

URIアクション以外のアクションを設定すると、メッセージは送信されません。また、同じリクエストに含まれるその他のメッセージも送信されません。

# サポートされていない機能

オーディエンスマッチAPIでは、以下のプロパティやリクエストヘッダーは利用できません。

# モバイル広告IDを利用してメッセージを送る

ユーザーが保有するモバイル広告ID(IFA:Identifier for Advertisers)に基づいたターゲティング配信を行います。

リクエストの例

# HTTPリクエスト

POST https://api.line.me/v2/bot/ad/message/multicast

# リクエストヘッダー

Content-Type

application/json

Authorization

Bearer {channel access token}

# リクエストボディ

to

Object

必須

メッセージの送信先(IFA)。

to.type

String

必須

ifa

to.ids

Array

必須

IFA文字列の配列。
最大件数:150

messages

Array

必須

送信するメッセージのメッセージオブジェクトの配列。
最大件数:5

notificationDisabled

Boolean

任意
  • true:メッセージ送信時に、ユーザーに通知されない。
  • false:メッセージ送信時に、ユーザーに通知される。ただし、LINEで通知をオフにしている場合は通知されません。

デフォルト値はfalseです。

# レスポンス

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

レスポンスの例

# モバイル広告IDを利用したメッセージ配信の結果を取得する

モバイル広告IDを利用してメッセージを送る」で配信したメッセージの配信結果を取得します。

リクエストの例

# HTTPリクエスト

GET https://api.line.me/v2/bot/message/delivery/ad_ifa?date={date}

# リクエストヘッダー

Content-Type

application/json

Authorization

Bearer {channel access token}

# クエリパラメータ

date

必須

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

  • フォーマット:yyyyMMdd(例:20190831
  • タイムゾーン:UTC+9

# レスポンス

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

status

String

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

  • ready:メッセージ数を取得できます。
  • unreadydateに指定した日付のメッセージ数の集計がまだ完了していません。たとえば、配信当日や未来の日付を指定した場合に返されます。通常、集計処理は配信の翌日中に完了します。
  • unavailable_for_privacy:該当日の通数の合計が20通未満です。
  • out_of_servicedateに指定した日付が、集計システムの稼働開始日(2018年03月31日)より前です。

success

Long

dateに指定した日付に、モバイル広告IDを利用して配信されたメッセージの数。statusの値がreadyの場合にのみ、レスポンスに含まれます。

# 電話番号を利用してメッセージを送る

ユーザーの電話番号に基づいたターゲティング配信を行います。

リクエストの例

# 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:メッセージ数を取得できます。
  • unreadydateに指定した日付のメッセージ数の集計がまだ完了していません。たとえば、配信当日や未来の日付を指定した場合に返されます。通常、集計処理は配信の翌日中に完了します。
  • unavailable_for_privacy:該当日の通数の合計が20通未満です。
  • out_of_servicedateに指定した日付が、集計システムの稼働開始日(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_apromotion_Aは別のユニットとして扱われます。

  • 最大ユニット数:1
  • 最大文字数:30
  • 使用可能文字種:半角英数字(azAZ09)、アンダースコア(_

リクエストの例

# ユニットごとの統計情報を取得する

LINE公式アカウントから送信したプッシュメッセージやマルチキャストメッセージに対して、ユーザーがどのように操作したかを示す統計情報をユニットごとに確認できます。

なお統計情報は1メッセージ(message)単位、および1吹き出し(bubble)単位で取得できます。

message and bubbles

記録される統計情報について

統計情報は、メッセージの送信時刻から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_apromotion_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で取得しきれなかったユニットがある場合にのみ返されます。

レスポンスの例