更新履歴 June 28, 2026

UnifyPort API アップデート：会話ラベル、連絡先メッセージ、リクエストトレーシング — UnifyPort

v1安定版リリースから3週間、UnifyPort APIに最初の機能バッチが追加されました：WhatsAppチャットを整理するための会話ラベル、連絡先カードメッセージタイプ、すべてのAPI呼び出しを横断するリクエストトレーシング、そしてwebhookイベントリファレンスを大幅に実用的にする開発者体験の改善です。

以下が今回のリリース内容です。実際のエンドポイントとフィールド名を記載しています。

会話ラベル — 4つの新エンドポイント

会話にラベルを作成・一覧表示・更新・削除し、一括でタグ付け・タグ解除できるようになりました。WhatsAppがネイティブに提供するラベルシステムと同じものを、UnifyPortがConversationsカテゴリの4つのエンドポイントで統一的に提供します。

ラベル一覧

GET /v1/accounts/{account_id}/conversations/labels?limit=50&cursor=

ページネーション付きでラベルを返します。各ラベルは id と name を持ちます：

{
  "data": {
    "items": [
      { "id": "label_example", "name": "VIP" }
    ],
    "next_cursor": "",
    "has_more": false
  }
}

ラベルの作成または更新

POST /v1/accounts/{account_id}/conversations/labels/upsert

label_id が空なら新規作成、既存の label_id を渡すとリネーム：

{
  "label_id": "",
  "name": "VIP"
}

ラベルの削除

POST /v1/accounts/{account_id}/conversations/labels/delete

{
  "label_id": "label_example"
}

会話へのタグ付け・タグ解除

POST /v1/accounts/{account_id}/conversations/labels

action は add または remove。conversation_ids には少なくとも1つのIDが必要です：

{
  "label_id": "label_example",
  "action": "add",
  "conversation_ids": ["peer_example"]
}

4つのエンドポイントは現在WhatsApp専用です。他のプロバイダーは 501 unsupported_by_provider を返します。対応するエラーコード — list_conversation_labels_failed、upsert_label_failed、delete_label_failed、set_label_members_failed — はエラーリファレンスに記載されています。

連絡先（vCard）メッセージタイプ

POST /v1/messages で message.type: "contact" と構造化された contacts 配列を受け付けるようになりました。UnifyPortが自動的にvCardを生成します — 構造化JSONを送るだけで、受信者は標準的な連絡先カードを受け取ります。

{
  "account_id": "acc_example",
  "to": {
    "id": "user_example",
    "type": "user"
  },
  "message": {
    "type": "contact",
    "contacts": [
      {
        "name": "Jane Doe",
        "phones": [{ "number": "+8613800000000", "type": "CELL" }],
        "emails": [{ "address": "jane@example.com" }],
        "organization": "ACME",
        "title": "PM"
      }
    ]
  }
}

各カードには name が必須です。phones[].number、emails[].address、organization、title はオプションです。配列で単一カードまたは複数カードを送信できます — WhatsAppは単一カードをcontactタイプに、複数カードを contact_array にマッピングします。

空の contacts 配列または name が欠けたカードは 400 invalid_request を返します。WhatsApp以外のプロバイダーはサポート開始まで 400 unsupported_message_type を返します。

リクエストトレーシング — request_idとX-Request-Id

すべてのAPIレスポンス（成功・エラー問わず）にトップレベルの request_id フィールドが含まれ、同じ値が X-Request-Id レスポンスヘッダーとしても返されます。問題報告や失敗した呼び出しのデバッグ時にこのIDを引用してください。

クライアント側のリクエスト照合のため、独自の X-Request-Id リクエストヘッダーを送信すると、レスポンスで client_request_id としてエコーバックされます。別途マッピングレイヤーを維持することなく、送信APIコールと内部リクエストIDを関連付けられます。

実際のwebhookペイロードサンプル

APIリファレンスに、実際のデバイスwebhookパーサー（TelegramおよびWhatsApp）から抽出したリアルなペイロード構造が含まれるようになりました。

message.received はコンテンツタイプ別のペイロードを表示 — テキスト、画像、音声、ドキュメント、位置情報 — 空の data: {} プレースホルダーから推測する代わりに、各バリアントの正確なフィールド構造を確認できます。

group.updated は変更種別ごとのペイロードを表示：

リネーム — changes[].kind: "renamed"、新しいグループ name を含む
メンバー追加/削除 — changes[].kind: "member_added" または "member_removed"、参加者IDの members[] 配列を含む
管理者昇格/降格 — changes[].kind: "promoted" または "demoted"、members[] を含む

単一の group.updated イベントは複数の変更を同時に含むことができます — 例えば、1つのスナップショットでリネームとメンバー追加が同時に起こる場合です。

3つの新しい開発者ツール

ツールページに3つのブラウザベースユーティリティが追加されました。すべてクライアントサイドで動作します：

HMAC署名ジェネレーター — ブラウザでHMAC-SHA1/SHA256/SHA512署名を生成・検証。webhook signing_secret 検証のデバッグに便利
Unixタイムスタンプコンバーター — Unixタイムスタンプと人が読める日付を相互変換。秒/ミリ秒の自動検出付き
JSONフォーマッター — JSONのフォーマット、ミニファイ、バリデーション。シンタックスハイライトとワンクリックJSON Pathコピー対応

破壊的変更：2つのフィールドを削除

POST /v1/messages リファレンスから未実装だった2つのフィールドが削除され、実際のAPIサーフェスと一致するようになりました：

idempotency_key — 削除。ドキュメントに記載されていましたが、デバイスAPIでは実装されていませんでした。
provider_data.reply_to — ドキュメントサーフェスから削除。provider_data オブジェクトは現在 parse_mode を例示フィールドとして記載しています。

コードで idempotency_key や provider_data.reply_to を使用していた場合、実際にはノーオプだった動作に依存していなかったか確認してください。どちらのフィールドもAPIで処理されていませんでした。

次のステップ

会話ラベルと連絡先メッセージはWhatsAppファーストで提供されます。WhatsAppのアップストリームAPIがこれらの機能をネイティブにサポートしているためです。他のプロバイダーが同等の機能を追加するか、正規化レイヤーがギャップを埋められるようになれば、同じエンドポイントサーフェスで追加チャネルでも利用可能になります。501 unsupported_by_provider レスポンスは意図的なものです：リクエストをサイレントにドロップするのではなく、どのプロバイダーがまだ機能をサポートしていないかを正確に伝えます。

完全なAPIリファレンスは unifyport.ai/docs で公開中です。