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

連絡先（vCard）メッセージ送信

名刺（連絡先カード）を送信します。message.type は contact で、message.contacts は構造化された配列（1 枚または複数枚のカード）です。vCard は UnifyPort が生成します。各カードには name が必須で、phones[].number、emails[].address、organization、title は任意です。現在は WhatsApp のみ対応：contacts 配列が空、または name を欠くカードがある場合は 400 invalid_request を返し、WhatsApp 以外のプロバイダは 400 unsupported_message_type を返します。 WhatsApp 送信が成功し、チャネルが参照可能なメッセージ識別子を提供した場合に返ることがある不透明な返信ハンドル。親メッセージ id ではありません。

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

ヘッダー

X-Api-Key
string必須

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

Content-Type
string必須

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

パスパラメータ

このエンドポイントにパスパラメータはありません。

リクエストボディ

account_id
string必須

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

to
object必須

宛先（id と type）。

id
string必須

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

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 のときに送信する本文。

url
string

メディアメッセージで使用する公開メディア URL。

file_url
string

ファイル系プロバイダアダプタが対応する代替メディア URL。

file_key
string

対応時に使用するプロバイダ側またはストレージ側のファイル参照。

caption
string

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

contacts[]
object[]

message.type が contact のときに送信する構造化連絡先カード。

name
string

連絡先の表示名。各カードで必須です。

phones[]
object[]

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

number
string

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

type
string

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

emails[]
object[]

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

address
string

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

type
string

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

organization
string

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

title
string

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

provider_data
object

Telegram の parse_mode、または WhatsApp 音声の seconds / waveform などのプロバイダ固有オプション。引用返信にはトップレベルの reply_to を使用します。

seconds
integer

WhatsApp の audio メッセージで使用する任意の音声時間（秒）。0 以上を指定します。

waveform
string

WhatsApp の audio メッセージで使用する任意の波形データ文字列。

reply_to
object

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

reply_token
string

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

mentions[]
object[]

text または caption 内の {{@<id>}} プレースホルダから参照されるメンバー。

id
string

対応する {{@<id>}} プレースホルダが参照するプロバイダ側メンバー識別子。

レスポンスボディ

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": "contact",
    "contacts": [
      {
        "name": "Jane Doe",
        "phones": [{ "number": "+8613800000000", "type": "CELL" }],
        "emails": [{ "address": "jane@example.com" }],
        "organization": "ACME",
        "title": "PM"
      }
    ]
  }
}'

レスポンス

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