← API リファレンス
メッセージPOST

テキストメッセージ送信

テキストメッセージを送信します。message.text は空にできません。固有フィールドは provider_data、引用返信はトップレベルの reply_to を使います。 WhatsApp 送信が成功し、チャネルが参照可能なメッセージ識別子を提供した場合に返ることがある不透明な返信ハンドル。親メッセージ id ではありません。

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

ヘッダー

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
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

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

リクエスト

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": "user_example",
    "type": "user"
  },
  "message": {
    "type": "text",
    "text": "Hello from UnifyPort"
  },
  "provider_data": {
    "parse_mode": "markdown"
  }
}'

レスポンス

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