APIを使用して他ツールから変数付きメッセージを送る方法

機能概要

TalkLabelのAPIを利用すると、外部ツール（例：hacomono）からエクスポートした顧客データを、メッセージ内で変数として動的に置き換えることができます。
これにより、外部システムのデータを自動配信に活用し、個別最適化されたメッセージを送信できます。

設定方法（手順）

STEP1:API認証を行う

1. API認証
   TalkLabel APIはBearerトークン認証を採用しています。各リクエストに以下のヘッダーを必須で付与してください：

Authorization: Bearer {YOUR_AUTH_KEY}
このヘッダーはHTTPの一般的な認証フレームワークで定義されています (Authorization – HTTP | MDN – MDN Web Docs, HTTP authentication – HTTP | MDN – MDN Web Docs)。

2. JSONフォーマット
   リクエスト／レスポンスはすべてJSON形式です。JSONはオブジェクトや配列による軽量なデータ交換フォーマットで、ほとんどのプログラミング言語でサポートされています (RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format, JSON)。
3. REST APIの基礎
   TalkLabel APIはREST原則に則って設計されており、HTTPメソッド（GET, POST, PUT, DELETE）とステータスコードを活用します。エンドポイントごとに一意のURLを使い、適切なメソッドで操作を行ってください (HTTP Methods – REST API Tutorial)。
4. hacomonoからの変数エクスポート
   hacomono管理画面から顧客情報（例：価格、氏名）をCSVまたはJSONでエクスポートし、JavaScriptオブジェクトや配列に整形します。たとえば：

// hacomonoからエクスポートしたJSON例
[
{ “price”: 1000, “customer_name”: “山田太郎”, “email”: “taro@example.com” },
{ “price”: 2000, “customer_name”: “佐藤花子”, “email”: “hanako@example.com” }
]
このデータをもとに、次ステップの変数登録用ペイロードを準備します (JSON)。

STEP2:変数リストの登録

• 変数リストの登録
  エンドポイント
  POST https://app.talklabel.com/api/v1/channels/{channel_uuid}/message_variables
  認証：Bearerトークン
  Content-Type：application/json (TalkLabel API)
  リクエストボディ例
  {
  “system”: “hacomono”,
  “name_and_variables”: [
  {
  “name”: “商品価格”,
  “variable”: “price”
  },
  {
  “name”: “顧客名”,
  “variable”: “customer_name”
  }
  ]
  }
  system：任意の識別子（ここでは“hacomono”）
  name_and_variables：登録したい変数名と、後で送信するキーをペアで定義 (TalkLabel API)
  cURLサンプル
  curl –request POST \
  “https://app.talklabel.com/api/v1/channels/CHANNEL_UUID/message_variables” \
  –header “Authorization: Bearer YOUR_AUTH_KEY” \
  –header “Content-Type: application/json” \
  –data ‘{
  “system”: “hacomono”,
  “name_and_variables”: [
  { “name”: “商品価格”, “variable”: “price” },
  { “name”: “顧客名”, “variable”: “customer_name” }
  ]
  }’
  成功すると、登録された変数の情報がJSONで返却されます (TalkLabel API)。

STEP3:メッセージ送信時の変数利用

• メッセージ送信時の変数利用
  エンドポイント
  POST https://app.talklabel.com/api/v1/channels/{channel_uuid}/action_messages
  認証：Bearerトークン
  Content-Type：application/json (HTTP authentication – HTTP | MDN – MDN Web Docs)
  リクエストボディ例
  {
  “friend_uuid”: “FRIEND_UUID”,
  “messages”: [
  {
  “type”: 1,
  “text”: “こんにちは {{customer_name}}様、商品の価格は{{price}}円です。”
  }
  ],
  “variables”: {
  “customer_name”: “山田太郎”,
  “price”: 1000
  }
  }
  friend_uuid：配信対象のフレンドUUID
  messages[].text：あらかじめ登録した変数を{{variable}}形式でプレースホルダー指定
  variables：プレースホルダー名と実際の置換値をマッピング (HTTP Methods – REST API Tutorial)
  cURLサンプル
  curl –request POST \
  “https://app.talklabel.com/api/v1/channels/CHANNEL_UUID/action_messages” \
  –header “Authorization: Bearer YOUR_AUTH_KEY” \
  –header “Content-Type: application/json” \
  –data ‘{
  “friend_uuid”: “FRIEND_UUID”,
  “messages”: [
  {
  “type”: 1,
  “text”: “こんにちは {{customer_name}}様、商品の価格は{{price}}円です。”
  }
  ],
  “variables”: {
  “customer_name”: “山田太郎”,
  “price”: 1000
  }
  }’
  正常に送信されると、メッセージUUIDなどが返却されます (HTTP Methods – REST API Tutorial)。