日本語

# 法人ユーザー向けオプション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 以下のいずれか、または両方です。
        • リクエストヘッダーの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では、以下のプロパティやリクエストヘッダーは利用できません。

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

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

        LINEのプライバシーポリシー（2022年3月改定）に同意済みのユーザーのみが対象となります

        メッセージはプライバシーポリシー（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）単位で取得できます。

                      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_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です。

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

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

                                  LINEのプライバシーポリシー（2022年3月改定）に同意済みのユーザーのみが対象となります

                                  メッセージはプライバシーポリシー（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でハッシュ化した電話番号を指定してください。

                                      注意

                                      messages

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

                                      必須

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

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

                                      # レスポンス

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

                                      レスポンスの例

                                        # エラーレスポンス

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

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

                                        message

                                        String

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

                                        エラーレスポンスの例

                                          # 送信済みの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オブジェクトを返します。共通仕様の「エラーレスポンス」を参照してください。