メッセージ

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

引用付き返信を送信します。受信した 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 を使用します。

リクエストボディ

account_id

string必須

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

minLength: 1

to

object必須

宛先（id と type）。

id

string必須

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

minLength: 1

type

string必須

宛先タイプ：user、group、または channel。

enum: user, group, channel

message

object必須

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

type

string必須

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

enum: text, image, video, audio, document, file, contact

text

string

message.type=text のときに必須の空でない本文。

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

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

minLength: 1

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

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

provider_data

object

Telegram の parse_mode、WhatsApp audio / video の seconds（0 以上の整数）、または audio 専用の waveform などのプロバイダ固有オプション。video の場合のみ、seconds の指定範囲は 0 から 4294967295 です。引用返信にはトップレベルの reply_to を使用します。

seconds

integer

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

minimum: 0

waveform

string

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

reply_to

object

引用返信の対象。受信 webhook の data.message.reply_token を変更せず、送信リクエストの reply_to.reply_token に設定します。

reply_token

string

受信 webhook の data.message.reply_token から変更せずにコピーする不透明な返信トークン。

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 送信が成功し、チャネルが参照可能なメッセージ識別子を提供した場合に返ることがある不透明な返信ハンドル。親メッセージ 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 送信が成功し、チャネルが参照可能なメッセージ識別子を提供した場合に返ることがある不透明な返信ハンドル。親メッセージ id ではありません。

レスポンス

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 から生成しないでください。引用返信に対応するチャネルが必要です。