メッセージ

メッセージへの返信（引用）

引用付き返信を送信します。受信した message.received イベントの data.message.reply_token を、そのまま reply_to.reply_token に渡してください。これは不透明な暗号化ハンドルであり、自分で組み立てたり変更したりしてはいけません。現在は WhatsApp のみ対応：他のプロバイダは 501 unsupported_by_provider を返し、改ざんされた token は 400 invalid_reply_token になります。

POSThttps://api.unifyport.ai/v1/messages

対応チャネル

呼び出す前に

対象ワークスペースの X-Api-Key をサーバー側で使用します。実行前にすべてのプレースホルダーを置き換えます。

認証フローを完了し runtime_status を確認します。認証と接続は別の状態で、HTTP 成功だけでは準備完了と判断できません。

パラメーターの取得元

account_id: アカウント作成・取得応答の data.id を使います。識別子は X-Api-Key のワークスペースに属します。アカウント取得
to.id · to.type: 返信時は message.received の data.conversation.id と data.conversation.type を to.id と to.type にコピーします。新規宛先はチャネルの識別子規則に従います。統一メッセージ送信の対応状況

リクエスト

curl -X POST "https://api.unifyport.ai/v1/messages" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acc_example",
  "to": {
    "id": "8600000000000@s.whatsapp.net",
    "type": "user"
  },
  "message": {
    "type": "text",
    "text": "Sure - replying to your question above."
  },
  "reply_to": {
    "reply_token": "<data.message.reply_token from the inbound event>"
  }
}'

リクエストパラメータ

ヘッダー

X-Api-Key

string必須

ワークスペース API キー。このヘッダーからワークスペースを特定します。

Content-Type

string必須

JSON のリクエストボディを送る場合は application/json を使用します。

リクエストボディ

provider_data

object

プロバイダ固有の送信オプション。対応するプロバイダとメッセージタイプでのみ有効です。WhatsApp audio/video の seconds は 0 以上の整数です。video の場合のみ 0 から 4294967295 の範囲を使用し、waveform は audio 専用です。引用返信がサポートされる場合はトップレベルの reply_to を使用します。sticker の provider_data は省略するか空オブジェクトにします。オブジェクト以外は 400 invalid_request、空でないオブジェクトは 400 provider_invalid_request を返します。

seconds

integer

WhatsApp の audio および video メッセージで使用する任意の長さ（秒）を 0 以上の整数で指定します。video の場合のみ、指定範囲は 0 から 4294967295 です。

minimum: 0

waveform

string

WhatsApp の audio メッセージで使用する任意の波形データ。空でない値は標準 Base64 でエンコードされ、デコード後に解析可能な JSON 波形データである必要があります。空文字列は未指定として扱い、その他の形式エラーは HTTP 400 provider_invalid_request を返します。

account_id

string必須

メッセージを送信するプロバイダアカウント。

minLength: 1

to

object必須

宛先（id と type）。

id

string必須

プロバイダ側の宛先識別子。

minLength: 1

type

string必須

標準の会話タイプ：user、group、channel。WhatsApp コミュニティのお知らせグループも引き続き group を使用します。

enum: user, group, channel

message

object必須

正規化されたメッセージペイロード。テキストは message.text、メディアは message.url を使用します。

type

string必須

メッセージタイプ：text、image、video、audio、document、file、contact、link_preview、poll、または sticker。

enum: text, image, video, audio, document, file, contact, link_preview, poll, sticker

text

string

text と link_preview で必須の空でない本文。link_preview では空白以外の文字を含める必要があり、WhatsApp では link_preview.url の原文も本文に含める必要があります。

minLength: 1

caption

string

image、video、document、file メッセージの任意のキャプション。

url

string

空でない絶対 HTTP(S) URL。メディアは url / file_url / file_key のいずれかが必須です。

format: uri · pattern: ^[Hh][Tt][Tt][Pp][Ss]?://

file_url

string

空でない代替の絶対 HTTP(S) URL。メディアはいずれかのソースが必須です。

format: uri · pattern: ^[Hh][Tt][Tt][Pp][Ss]?://

file_key

string

空でないプロバイダまたはストレージのファイル参照。

contacts[]

object[]

message.type=contact のときに必須の空でないカード配列。

minItems: 1

name

string

各カードで必須の空でない表示名。

minLength: 1

phones[]

object[]

連絡先カードに含める電話番号の一覧。

number

string

電話番号。各 phone 項目で必須です。

type

string

CELL や WORK などの任意の電話種別。

emails[]

object[]

連絡先カードに含めるメールアドレスの一覧。

address

string

メールアドレス。各 email 項目で必須です。

format: email

type

string

WORK や HOME などの任意のメール種別。

organization

string

連絡先に関連付ける任意の組織名。

title

string

連絡先に関連付ける任意の役職名。

link_preview

object

message.type=link_preview 専用で text とともに必須です。他のペイロードと混在できません。共通構造では url のみ必須で、任意の title と description は空文字列を許可しますが null は不可です。本 API の WhatsApp 送信ポリシーでは空でない title/image_url が必須で、title は最大 255、description は最大 1024 Unicode 文字です。

url

string

必須の対象リンク。ホスト名を持ち空白を含まない絶対 HTTP(S) URI。角括弧内のアドレスは IPv6 リテラルのみ許可します。原文を保持し、リソースへのアクセス可否は保証しません。

pattern: ^[Hh][Tt][Tt][Pp][Ss]?://(?:[^/?#@\s]*@)?(?:\[[0-9A-Fa-f:.]+\]|[^/?#:@\s\[\]]+)(?::[0-9]*)?(?:[/?#]|$)

title

string

任意のプレビュータイトル。空文字列は可、null は不可です。WhatsApp では空でない値が必須で、最大 255 Unicode 文字です。

description

string

任意のプレビュー概要。空文字列は可、null は不可です。WhatsApp では最大 1024 Unicode 文字です。

image_url

string

任意の画像 URI。WhatsApp では空でない値が必須です。ホスト名を持ち空白を含まない絶対 HTTP(S) URI とし、角括弧内のアドレスは IPv6 リテラルのみ許可します。原文を保持し、リソースへのアクセス可否は保証しません。

pattern: ^[Hh][Tt][Tt][Pp][Ss]?://(?:[^/?#@\s]*@)?(?:\[[0-9A-Fa-f:.]+\]|[^/?#:@\s\[\]]+)(?::[0-9]*)?(?:[/?#]|$)

poll

object

message.type=poll 専用で必須です。text や他のペイロードと混在できません。question、options、max_selections が必須です。質問と選択肢のタイトルは原文を保持します。共通構造では質問の長さ、選択肢の最大数、タイトルの重複を制限しませんが、プロバイダが追加制限を設ける場合があります。

question

string

必須の投票の質問。空白以外の文字を含める必要があり、原文を保持します。

minLength: 1 · pattern: \S

options[]

object[]

必須の選択肢配列。2 件以上が必要で、各選択肢に title が必須です。

minItems: 2

title

string

必須の選択肢タイトル。空白以外の文字を含める必要があります。送信時に trim、大文字小文字の変更、Unicode 正規化は行いません。

minLength: 1 · pattern: \S

max_selections

integer

必須の投票者ごとの最大選択数で、投票人数ではありません。1 から options の件数までの整数を API が検証します。1.0、1e0 など整数値を表す数は 1 と同等で、非整数は無効です。

minimum: 1

reply_to

object

引用返信の対象。引用可能なメッセージイベントの data.message.reply_token または送信応答の data.reply_token を reply_to.reply_token にそのまま設定します。元のアカウントと会話で使い、メッセージ ID で代用しないでください。

reply_token

string

引用可能なメッセージイベントの data.message.reply_token または送信応答の data.reply_token から得る不透明なハンドル。元のアカウントと会話でそのまま使い、メッセージ ID で代用しないでください。

minLength: 1

mentions[]

object[]

グループメッセージの @ 対象リスト。type=member は対応する Provider メンバー id を使用します。type=all は @全員を意味し、Provider がサポートする場合のみ有効です。サポートされない場合は unsupported_message_type を返します。

type

string

@ 対象の種類。省略時は旧リクエストとの互換性のため member として扱います。type=member では id が必須で、type=all では id を指定せず、グループチャットにのみ適用されます。

enum: member, all

id

string

type=member の場合に必須の Provider メンバー識別子。

minLength: 1

結果の確認

後続イベントとの照合や調査のため message_id と provider_ref を保存します。accepted は配達完了を意味しません。チャネルが対応する場合にのみ、受領イベントで配達を確認してください。識別子の形式はチャネルにより異なります。

reply_token — WhatsApp 送信が成功し引用コンテキストが完全な場合に返る任意の空でない不透明なハンドル。新規送信した投票も含み、通常のテキストで引用できます。利用できなければ省略され、accepted 状態は変わりません。元のアカウントと会話でそのまま使います。メッセージ ID ではありません。

レスポンス 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "message_id": "msg_example",
    "account_id": "acc_example",
    "status": "accepted",
    "provider_ref": "provider_msg_example",
    "reply_token": "<opaque WhatsApp reply handle>"
  }
}

レスポンスボディ

message_id

string

受理されたメッセージの UnifyPort メッセージ識別子（msg_...）。

account_id

string

このレスポンスが対象とするプロバイダアカウント。

status

string

受理ステータス。accepted はメッセージがプロバイダへの配信待ちにキューイングされたことを意味します。

provider_ref

string

プロバイダが割り当てたあとの、プロバイダ側メッセージ参照。

reply_token

string

WhatsApp 送信が成功し引用コンテキストが完全な場合に返る任意の空でない不透明なハンドル。新規送信した投票も含み、通常のテキストで引用できます。利用できなければ省略され、accepted 状態は変わりません。元のアカウントと会話でそのまま使います。メッセージ ID ではありません。

minLength: 1

レスポンス

200

200 OK

リクエスト成功。レスポンスボディの例を参照してください。

400

Bad Request

リクエストボディ、パス、またはパラメータが不正です。

401

Unauthorized

X-Api-Key ヘッダが欠落しているか無効です。

409

Conflict

要求された操作が、既存のプロバイダアカウントまたはリソースと競合しています。

500

Internal Server Error

サービスで予期しないエラーが発生しました。

501

Not Implemented

選択したプロバイダはこの操作を実装していません。

502

Bad Gateway

プロバイダアダプタまたは上流サービスが操作を完了できませんでした。

失敗時の対応

HTTP 状態と error.code/numeric_code を確認し、request_id を保存します。原因に応じてパラメーター修正・認証・状態確認を行い、送信や書き込みの再試行前に前回の結果を確認します。エラーリファレンス

invalid_request · 10000 · 400: 必須項目、形式、チャネルの条件を確認して修正します。
invalid_api_key · 11001 · 401: X-Api-Key とワークスペースの有効性を確認します。
provider_not_ready · 30009 · 409: 認証と接続を復旧し、前回の結果を確認してから再試行します。
unsupported_message_type · 36000 · 400: 対応する操作や形式を選びます。同じリクエストの再送で対応範囲は変わりません。
invalid_reply_token · 36006 · 400: 受信した reply_token をそのままコピーし、メッセージ ID から生成しないでください。引用返信に対応するチャネルが必要です。