L Message（エルメ）API/Webhook リファレンス

エルメの外部連携は、方向の異なる2つの仕組みで構成されます。外部システムからエルメを操作する場合はAPIを、エルメ側で発生したイベントを外部システムで受け取る場合はWebhook転送機能を使用します。両者は独立しており、どちらか一方のみを利用することもできます。

いずれのケースでも、対象の友だちは lmessage_friend_id または line_friend_id で指定します。

• API：友だちの一覧／詳細の取得、タグをつける／外す、友だち情報の更新、ステップ配信の開始／停止、メッセージ送信、テンプレートの取得、カンバセーションの取得。
• LINE公式アカウントデータ転送機能：対象アカウントにLINE Platformから届いたすべてのイベントを転送します。イベント種別による絞り込みは行わず、エルメ側で処理可能かどうかも問いません。
• L Messageデータ転送機能：tag と friend_info の操作の2種類のみを対象とします。

• フォーム回答、ステップ配信などのその他のエルメ内部イベントのWebhook転送。後続フェーズで追加する場合は、実装前に個別のペイロード仕様を合意する必要があります。

Phase 1で対象とするAPIの一覧です。パラメータの詳細とサンプルは、各章のブロックに記載しています。

すべてのエンドポイントは /v1 配下に配置します（例：https://api.lmes.jp/v1/friends）。

すべてのリクエストに X-LME-API-KEY ヘッダーを付与します。APIキーは lme_live_sk_<32hex> 形式で、LOAごとに発行します。

X-LME-API-KEY: lme_live_sk_0123456789abcdef0123456789abcdef
Content-Type: application/json

サーバー側では、受け取ったAPIキーをもとに api_keys.key_lookup_hash = HMAC-SHA256(key, API_KEY_PEPPER) を照合し、対象のLOAおよび権限 scope（full／read）を特定します。あわせて is_deleted、status、expires_at を確認し、APIキーが有効かつ利用可能な状態であることを検証します。expires_at が null の場合は、有効期限なしとして扱います。

read 権限のAPIキーで書き込みAPI（POST/PUT/DELETE）を実行した場合は 403 forbidden を返します。書き込みを行う連携では full 権限のキーを使用してください。

APIキーは秘密情報として扱い、クライアントサイドに埋め込まないでください。

一覧取得APIは page と limit のクエリパラメータを受け付けます。

レスポンスの pagination オブジェクトには page、limit、total_items、total_pages、has_next が含まれます。has_next が false になるまで page を進めて取得してください。

リクエスト数はLOA単位でカウントし、1分単位の固定ウィンドウ（fixed window）方式とします。カウントは毎分の開始時にリセットされます。カウント対象は、APIキーによる認証が成功したリクエストのみです。

上限を超えた場合は HTTP 429 rate_limited と Retry-After ヘッダー（秒）を返します。指定された秒数だけ待機してから、再度呼び出してください。

/do_action、/messages/push、/messages/template では、Idempotency-Key ヘッダーにより同一リクエストの重複実行を防止できます。値は利用側で任意に設定でき、最大100文字まで指定できます（超過した場合は 400 invalid_request を返します）。

Idempotency-Key: push-12345-20260730

「操作種別 + 対象ID + 業務上のイベントID（または日時）」のように、同じ業務イベントに対して同じ値、別のイベントには別の値になる組み立て方を推奨します。ネットワークエラー時のリトライでは、初回と同じ値を送信してください。

すべてのAPIは、以下の構造でレスポンスを返します。pagination は一覧取得APIのみに含まれます。

{
  "success": true,
  "request_id": "req_20260730_001",
  "data": {},
  "pagination": {"page": 1, "limit": 100, "total_items": 1240, "total_pages": 13, "has_next": true}
}

CRMで初回同期を行う際、またはエルメ内の友だち一覧をページングや基本的なフィルタ条件で更新する際に使用します。

異なるフィルタ同士はAND条件で組み合わされます。同一フィルタ内に複数の値を指定した場合（カンマ区切り、またはパラメータの繰り返し指定）は、OR条件で組み合わされます。

GET /v1/friends?page=1&limit=100&line_names=Tanaka,Sato&tag_ids=101,102&added_date_from=2026-07-01&added_date_to=2026-07-30

curl -G "https://api.lmes.jp/v1/friends" \
  -H "X-LME-API-KEY: lme_live_sk_0123456789abcdef0123456789abcdef" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=100" \
  --data-urlencode "line_names=Tanaka,Sato" \
  --data-urlencode "tag_ids=101,102" \
  --data-urlencode "added_date_from=2026-07-01" \
  --data-urlencode "added_date_to=2026-07-30"

{
  "success": true,
  "request_id": "req_20260730_0001",
  "data": {
    "total_items": 250,
    "total_pages": 3,
    "friend_detail": [
      {
        "added_time": "2026-07-30",
        "friendtype": "new",
        "line_friend_id": "Uxxxxxxxx",
        "lmessage_friend_id": 12345,
        "line_name": "Tanaka",
        "system_name": "Tanaka CRM",
        "email": "customer@example.com",
        "phone": "09000000000"
      }
    ]
  }
}

1人の友だちの詳細情報（タグ、友だち情報、配信中のステップ配信）を取得します。

本APIは lmessage_friend_id のみを受け付けます。LINE Friend ID／メールアドレス／携帯電話は入力として受け付けません。LINE Friend IDしか分からない場合は、先に /friends で対象の lmessage_friend_id を特定してください。

GET /v1/friends/detail?lmessage_friend_id=12345

{
  "success": true,
  "request_id": "req_20260730_0003",
  "data": {
    "friend": {
      "lmessage_friend_id": 12345,
      "line_friend_id": "Uxxxxxxxx",
      "line_name": "Tanaka",
      "system_name": "Tanaka CRM",   // ← 追加
      "email": "customer@example.com",
      "phone": "09000000000",
      "tags": [
        { "id": 101, "name": "cart_abandonment" }
      ],
      "friend_info": [
        { "id": -3, "type": "TEXT", "name": "email", "value": "customer@example.com" },
        { "id": 5001, "type": "POINT", "name": "point", "value": 20 }
      ],
      "scenarios": [
        { "id": 88, "name": "cart_abandonment_reminder", "status": "following" }
      ]
    }
  }
}

/do_action で友だちにタグをつける／外す前に、タグIDを特定するため既存のタグ一覧を取得します。

GET /v1/tags?page=1&limit=100

{
  "success": true,
  "request_id": "req_20260730_0005",
  "data": {
    "tags": [
      { "id": 101, "name": "cart_abandonment", "friend_count": 25 }
    ]
  },
  "pagination": { "page": 1, "limit": 100, "total_items": 36, "total_pages": 1, "has_next": false }
}

/do_action で更新する友だち情報のフィールドIDを特定するために使用します。組み込み（標準）フィールドは負のID、カスタムフィールドは正のIDを使用します。

GET /v1/friend-info-fields?page=1&limit=100

{
  "success": true,
  "request_id": "req_20260730_0009",
  "data": {
    "fields": [
      { "field_id": -3, "title": "email", "field_type": "TEXT", "options": null },
      { "field_id": 5001, "title": "purchase_count", "field_type": "POINT", "options": null },
      {
        "field_id": 5002,
        "title": "member_rank",
        "field_type": "SELECT",
        "options": [
          { "option_id": 1, "label": "gold" },
          { "option_id": 2, "label": "silver" }
        ]
      }
    ]
  },
  "pagination": { "page": 1, "limit": 100, "total_items": 48, "total_pages": 1, "has_next": false }
}

ステップ配信一覧を取得し、/do_action で友だちのステップ配信を開始／停止する際に使用する scenario_id を特定します。

GET /v1/scenarios?page=1&limit=100

{
  "success": true,
  "request_id": "req_20260730_0013",
  "data": {
    "scenarios": [
      {
        "scenario_id": 88,
        "name": "cart_abandonment_reminder",
        "followers_count": 120,
        "completed_count": 80,
        "dropped_count": 5
      }
    ]
  },
  "pagination": { "page": 1, "limit": 100, "total_items": 1, "total_pages": 1, "has_next": false }
}

テンプレートを送信する前に、対象のテンプレートIDを特定するために使用します。取得した template_id は /messages/template で指定します。

GET /v1/templates?page=1&limit=100

{
  "success": true,
  "request_id": "req_20260730_0021",
  "data": {
    "templates": [
      { "template_id": 7001, "name": "shipping_complete_notice" },
      { "template_id": 7002, "name": "review_request" }
    ]
  },
  "pagination": { "page": 1, "limit": 100, "total_items": 24, "total_pages": 1, "has_next": false }
}

チャットの対応ステータスをCRMと同期するため、エルメ側の対応ステータスIDを取得します。このIDは、/do_action の handling_status アクション、および /conversations の handling_status_ids による絞り込みで使用します。

GET /v1/handling-statuses

{
  "success": true,
  "request_id": "req_20260730_0023",
  "data": [
    { "id": 12, "name": "deal_in_progress" },
    { "id": 13, "name": "follow_up" }
  ]
}

指定したLINEの友だちにメッセージを送信します。本APIは /messages/text と /messages/media を統合したAPIです。messages[] 配列にはテキストとメディアを混在させることができ、指定した順に送信されます。対応するメディア形式は image、video、audio のみです。

POST /v1/messages/push
Idempotency-Key: push-12345-20260730

{
  "friend_id": 12345,
  "id_type": "lmessage_friend_id",
  "messages": [
    {"type": "text", "text": "お問い合わせいただきありがとうございます。ご案内資料をお送りいたします。"},
    {"type": "image", "url": "https://example.com/images/guide.jpg", "preview_url": "https://example.com/images/guide_preview.jpg"},
    {"type": "video", "url": "https://example.com/videos/intro.mp4", "preview_url": "https://example.com/videos/intro_preview.jpg"},
    {"type": "audio", "url": "https://example.com/audio/guide.m4a", "duration": 60000}   // ← .mp3 から修正
  ],
  "mark_confirmed": true
}

curl -X POST "https://api.lmes.jp/v1/messages/push" \
  -H "X-LME-API-KEY: lme_live_sk_0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: push-12345-20260730" \
  -d '{
    "friend_id": 12345,
    "id_type": "lmessage_friend_id",
    "messages": [
      {"type": "text", "text": "ご案内資料をお送りいたします。"}
    ],
    "mark_confirmed": true
  }'

{
  "success": true,
  "request_id": "req_20260730_0018"
}

指定した友だちに既存のテンプレートを送信します。templates[] 配列を使用し、1リクエストで最大5件のテンプレートを送信できます。テンプレートIDは /templates から取得します。

POST /v1/messages/template
Idempotency-Key: template-12345-7001-20260730

{
  "friend_id": 12345,
  "id_type": "lmessage_friend_id",
  "templates": [
    {"template_id": 7001},
    {"template_id": 7002}
  ]
}

{
  "success": true,
  "request_id": "req_20260730_0019"
}

LOAの1対1チャットにおけるカンバセーション一覧を取得します。並び順は、ブックマークしたカンバセーションを先頭に表示し、以降は最新のメッセージ順となります。確認／未確認、対応ステータス、友だちの名前、タグ、表示状態による絞り込みに対応しており、CRM側で返信待ちのカンバセーションや、特定の条件に該当するカンバセーションを検索する際に使用します。

異なるフィルタ同士はAND条件で組み合わされます。同一フィルタ内に複数の値を指定した場合はOR条件となります（タグのみ tag_mode に従います）。名称によるフィルタはカンマで値を区切るため、名称自体にカンマを含む場合はIDによるフィルタをご利用ください。

GET /v1/conversations?page=1&limit=100&confirm_status=1&handling_status_ids=12,13&tag_names=vip,cart_abandonment&tag_mode=or

curl -G "https://api.lmes.jp/v1/conversations" \
  -H "X-LME-API-KEY: lme_live_sk_0123456789abcdef0123456789abcdef" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=100" \
  --data-urlencode "confirm_status=1" \
  --data-urlencode "handling_status_ids=12,13" \
  --data-urlencode "tag_names=vip,cart_abandonment" \
  --data-urlencode "tag_mode=or"

{
  "success": true,
  "request_id": "req_20260916_0025",
  "data": {
    "conversations": [
      {
        "lmessage_friend_id": 12345,
        "line_friend_id": "U1234abcd...",
        "line_name": "Tanaka",
        "system_name": "Tanaka CRM",
        "last_message": "こんにちは",
        "last_message_date": "2026-09-16T10:00:00+09:00",
        "confirm_status": "unread",
        "handling_status": { "id": 12, "name": "deal_in_progress" }
      }
    ]
  },
  "pagination": { "page": 1, "limit": 100, "total_items": 36, "total_pages": 1, "has_next": false }
}

CRMやオートメーションツールがカンバセーションの文脈を確認できるよう、1人の友だちについて直近100件のメッセージを取得します。

GET /v1/conversations/detail?lmessage_friend_id=12345

{
  "success": true,
  "request_id": "req_20260730_0022",
  "data": {
    "lmessage_friend_id": 12345,
    "messages": [
      {
        "delivery_date": "2026-07-30T13:00:00+09:00",
        "sender": "friend",
        "message_type": "text",
        "data": "相談したいのですが"
      },
      {
        "delivery_date": "2026-07-30T13:00:05+09:00",
        "sender": "LINE_OA",
        "message_type": "template",
        "data": [
          { "type": "text", "content": "お問い合わせいただきありがとうございます。" },
          { "type": "image", "content": "https://.../guide.jpg" }
        ]
      },
      {
        "delivery_date": "2026-07-30T13:00:08+09:00",
        "sender": "LINE_OA",
        "message_type": "pdf",
        "data": { "file_name": "doc.pdf", "file_size": 67209, "url": "https://.../doc.pdf", "file_name_original": "document.pdf" }
      }
    ],
    "handling_status": { "id": 12, "name": "deal_in_progress" },   // ← compliant_statuses から改称
    "display_status": "display",
    "block_status": "normal",
    "favorite": "yes"
  }
}

1リクエストで、複数の友だちに対して1つ以上のアクションを実行します。本APIは、次の個別APIを統合したものです：/update-tag、/friend-info-field-update、/operate-scenarios、/change-handling-statuses、/change-block-statuses、/change-favorite-statuses。

• リクエストには、友だちIDの配列（lmessage_friend_ids[]）とアクションの配列（actions[]）を指定します。
• 各アクションは、lmessage_friend_ids[] に含まれるすべての友だちに適用され、指定した順に順次実行されます。
• 各アクションは type（アクションの種別）＋ action（操作）＋ 種別ごとの固有パラメータで構成されます。構造は、エルメで現在使用しているアクション体系に準拠しています。

POST /v1/do_action
Idempotency-Key: do-action-20260730-001

{
  "lmessage_friend_ids": [12345, 12346],
  "actions": [
    { "type": "tag", "action": "add", "tag_ids": [101] },
    { "type": "friend_info", "action": "point_plus", "field_id": 5001, "value": "10" },
    { "type": "scenario", "action": "start", "scenario_id": 88 },
    { "type": "handling_status", "action": "attach", "handling_status_id": 12 },
    { "type": "block", "action": "hide" },
    { "type": "favorite", "action": "add" },
    { "type": "confirm_status", "action": "confirm" }   // ← 追加
  ]
}

curl -X POST "https://api.lmes.jp/v1/do_action" \
  -H "X-LME-API-KEY: lme_live_sk_0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: do-action-20260730-001" \
  -d '{
    "lmessage_friend_ids": [12345, 12346],
    "actions": [
      { "type": "tag", "action": "add", "tag_ids": [101] }
    ]
  }'

{
  "success": true,
  "request_id": "req_20260730_0024"
}

エルメでは独立した2つの転送機能をご利用いただけます。各機能は送信先URLとオン／オフを個別に設定でき、一方の設定を変更しても、もう一方には影響しません。受信側では、どちらか一方のみを利用することも、異なるURLを設定して両方を利用することもできます。

転送機能を有効化した場合、エルメ側は有効化した時点以降に発生したイベントのみを転送します。それ以前の過去データが遡って送信されることはありません。受信側で過去データが必要な場合は、転送機能ではなく別途APIからご取得ください。

イベントごとに設定を再取得する処理を避けるため、エルメ側は転送設定を1分ごとに読み込む方式としています。そのため「Webhook転送」画面で「保存する」を押しても、変更内容は即時には反映されません。最大約1分の間、転送処理は変更前の設定で動作します。特に以下の3つのケースにご注意ください。

• 転送機能を有効化した直後：この待機時間中に発生したイベントは転送されない可能性があり、その場合エラー一覧にも表示されません（システム上はまだ無効の状態として扱われるためです）。先に有効化を行い、約1分お待ちいただいてから動作確認を開始してください。
• 転送機能を無効化した直後、または送信先URLを変更した直後：この待機時間中は、変更前の送信先にもリクエストが届く可能性があります。変更前のエンドポイントの停止は、1分以上経過してから実施してください。
• シークレットを再生成した直後：最も慎重な連携が必要なケースです。詳細はシークレットのライフサイクルをご参照ください。

特に記載がない限り、2つの転送機能の両方に適用されます。

LINE Platformからエルメへ届いたイベントを、加工や変換を行わずにそのまま転送します。

{
  "destination": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "events": [
    {
      "type": "message",
      "replyToken": "xxxxxxxxxxxxxxxx",
      "source": { "type": "user", "userId": "Uxxxxxxxx" },
      "timestamp": 1789000000000,
      "message": { "id": "987654321", "type": "text", "text": "こんにちは" }
    }
  ]
}

HTTP/1.1 200 OK

HTTP 2xxを返却いただければ十分です。レスポンスボディの内容は参照しません。

友だちに対して tag の付与・解除、または friend_info の登録・更新・削除が行われた際に、エルメのイベントとして転送します。エルメ側は events[] 配列を含むリクエストを1件送信します。各要素は発生した1件の操作を表し、操作内容と、友だちを識別する2つのフィールドで構成されます。

{
  "events": [
    {
      "lmessage_friend_id": 12345,
      "line_friend_id": "Uxxxxxxxx",
      "type": "tag",
      "action": "add",
      "tag_id": 101
    },
    {
      "lmessage_friend_id": 12345,
      "line_friend_id": "Uxxxxxxxx",
      "type": "friend_info",
      "action": "set",
      "field_id": -1,
      "value": "山田太郎"
    },
    {
      "lmessage_friend_id": 12345,
      "line_friend_id": "Uxxxxxxxx",
      "type": "friend_info",
      "action": "clear",
      "field_id": 5001
    }
  ]
}

HTTP/1.1 200 OK

認証ヘッダー（X-Lme-Signature）が付与されるのは L Messageデータ転送機能のみです。LINE公式アカウントデータ転送機能には付与されません。

POST /your/webhook/endpoint HTTP/1.1
Content-Type: application/json; charset=utf-8
X-Lme-Signature: whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Lme-Delivery-Id: 3f2a8c10-9d4b-4e21-8a77-1c5e9b0d6f34
X-Lme-Timestamp: 1789000000000

シークレットを再生成される際は、受信側にて旧シークレットと新シークレットの両方を約2分間受け付けるようにし、その後に旧シークレットを破棄してください。即時に新シークレットのみへ切り替えた場合、待機時間中のリクエストが拒否され、双方に誤りがないにもかかわらずエラー一覧に記録されます。

利用者は「Webhook転送」画面にてエラー一覧を確認できます。一覧は転送機能ごとに分かれています。

• 1回目：イベント発生時に即時送信します。タイムアウトまたは5xxで失敗した場合は1分待機して再送し、それ以外のエラーはその時点でエラーを記録します。
• 2〜3回目：最大2回まで、1分間隔で再送します。内容および X-Lme-Delivery-Id は初回と同一です。いずれかで成功した場合は終了し、エラーは記録しません。
• 3回失敗後：3回すべてがタイムアウトまたは5xxとなった場合（初回から約2分後）、利用者が確認できるエラー記録を1件登録します。

エンドポイントが408または504を返却した場合、文言中の「10秒」は実際の状況と一致しません（エルメ側は速やかに応答を受け取っており、タイムアウトを申告しているのはエンドポイント側です）。この表示が紛らわしいと受信側でご判断される場合は、エラーコード列に値があるかどうかに応じて、2種類の文言に分けることも可能です。

• 10秒以内にHTTP 2xxを返却してください。これを超えた場合は失敗として扱われます。重い処理は非同期化し、受信後すぐに応答することを推奨します。
• 重複受信に対応してください。X-Lme-Delivery-Id を重複排除のキーとしてご利用ください。
• 受信順序に依存しない実装としてください。必要に応じて X-Lme-Timestamp をご利用ください。
• L Messageデータ転送機能では、X-Lme-Signature の値を設定済みのシークレットと文字列比較して検証してください（再生成時は新旧2つを約2分間受け付け）。

友だち情報の標準項目は負の field_id、カスタム項目は正の field_id を使用します。以下は、Webhook転送仕様に記載されている標準項目の一覧です。最新の全項目は /friend-info-fields から取得してください。