Messaging APIのテキストメッセージ（v2）のシンタックスが決まるまで

2026/06/11

こんにちは。Messaging APIの開発を担当しているエンジニアの羽原です。

Messaging APIには、メンションやLINE絵文字を簡単に埋め込むことができるテキストメッセージ（v2）というメッセージタイプがあります。従来のテキストメッセージと異なり、メンションや絵文字を入れる位置を本文の中で直接指定できるのが特徴です。

この記事では、テキストメッセージ（v2）のシンタックスが現在の形になるまでに行った設計判断を紹介します。

テキストメッセージ（v2）のシンタックス
なぜsubstitutionプロパティで置換する形にしたのか
なぜ新しくtextV2というタイプを設けたのか
おわりに

テキストメッセージ（v2）のシンタックス

設計の話に入る前に、まずテキストメッセージ（v2）のシンタックスをおさらいしておきます。

json

{
  "type": "textV2",
  "text": "Hello {you}! {smile}",
  "substitution": {
    "you": {
      "type": "mention",
      "mentionee": {
        "type": "user",
        "userId": "U0123456789ab..."
      }
    },
    "smile": {
      "type": "emoji",
      "productId": "...",
      "emojiId": "..."
    }
  }
}

textの中に{you}や{smile}のようなプレースホルダーを書き、substitutionプロパティでそれぞれの中身（メンションやLINE絵文字の情報）を指定する形式です。

このシンタックスでは、置換内容をsubstitutionプロパティに分けて指定します。また、既存のtextタイプを拡張するのではなく、新しくtextV2タイプとして定義しています。ここからは、この形に至るまでの設計判断を1つずつ振り返っていきます。

なぜ`substitution`プロパティで置換する形にしたのか

最初の候補として挙がっていたのは、メンションや絵文字に必要な情報をテキストの中だけで完結させる形式でした。たとえば次のようなシンタックスです。

json

{
  "type": "text",
  "text": "Hello {@U0123456789ab...}! {:smile:}"
}

しかし、この形式は採用を見送りました。その理由は、シンタックスの誤用によってユーザーIDが露出するような事態を避けるためです。たとえば{}を入れ忘れてHello @U0123456789ab...!と送ってしまうと、本来メンションになるはずだった生のユーザーIDがそのまま本文として相手のトークに表示されてしまいます。LINE公式アカウントは、企業や店舗の顧客とのコミュニケーション手段としてご利用いただいているプロダクトです。そのため、保守的で事故を起こしにくい設計にする必要があったのです。

そこで採用したのが、冒頭で示したsubstitutionプロパティによる置換方式です。この方式であれば、ユーザーIDのような取り扱いに注意が必要な情報をsubstitutionの中だけで扱うことができます。そのため、text側でtypoしても相手に見えるのは{you}のようなプレースホルダー名にとどまり、生のユーザーIDが本文に露出する事態を避けやすい構造になっています。

なぜ新しく`textV2`というタイプを設けたのか

当初は新しいタイプを作らず、既存のtextタイプのまま機能を拡張する案も検討していました。しかし、プレースホルダーを扱うには{と}を制御文字として扱う必要があります。一方で、既存のtextタイプでそのルールを導入すると後方互換性を保てないという問題に行き当たります。

{と}は制御文字として扱うため、これらをそのままテキストとして送信したい場合に備えて、textV2タイプではPythonのstr.formatで使われているエスケープシンタックス（{{、}}）を採用しました。もしこのルールをtextタイプに適用してしまうと、これまで{{example}}という文字列をそのまま送信していた開発者の実装では、テキストの内容が{example}に変わってしまいます。既存のコードの挙動を変えてしまうわけにはいきません。

つまり、textタイプには次の2つのモードが必要になります。

{と}を制御文字として扱い、文字として使う場合は{{や}}にエスケープが必要なモード
{と}を単なる文字として扱う従来のモード

この2つを区別する方法として、substitutionプロパティの有無で切り替える案が考えられます。新しいモードを使う開発者はsubstitutionを指定しているはずで、一方既存のコードはこのプロパティを使っていないため、自然な発想と言えます。ただし、substitutionの状態を「要素あり」「{}（空オブジェクト）」「nullまたは未指定」の3パターンに分けたとき、真ん中の{}をどちらに分類するかが問題になります。

{}を新モード側として扱えば、{}とnullで挙動が分かれることになります。この場合、空オブジェクトとnullをどちらも空の値として扱う言語やフレームワークでは、開発者の意図とは違うモードで送信されるおそれがあります。これは、JSONベースのAPIを設計するときに注意が必要な罠の1つです。

逆に{}を従来モード側として扱う場合、置換要素数が0個のときには{や}のエスケープ処理を例外的に行わないか、ダミー要素を入れて新モードにするかの対応が必要になります。いずれの場合も、使い方に本来不要なはずの工夫が求められることになります。

どちらの分類でも問題が残るため、substitutionプロパティの有無でモードを切り替える方式は諦め、モードをtypeの段階で固定することにしました。これが、textV2を新しいタイプとして切り出した最大の理由です。textタイプの挙動は従来のまま保ちつつ、textV2タイプでは後方互換性に縛られずに置換シンタックスを設計できるようになりました。