開発者

Wisebird API: 顧客チャットを自社システムに接続

REST API、Webhook、MCP。自社システムとの接続に

詳しい説明を読む

開発者向けWisebird APIは、チャットの取得、検索、メッセージ送信、タグとメンバーの管理を行うREST APIとWebhookです。企業ごとのAPIキーとBearer認証を使い、Idempotency-Key、test event付きの署名付きWebhook、Try it形式のsandbox、MCP、複数企業を管理するpartner APIに対応しています

APIを使い始めるには何が必要ですか

  1. ビジネスごとにAPI keyを作成アプリのビジネス設定で作成し、すぐにコピーして保管。keyが全文表示されるのは1回だけです
  2. keyはBearerで送信すべてのリクエストでAuthorizationヘッダーに入れます。query stringには含めず、HTTPSを使用
  3. まずsandboxでテストアプリのTry itモードでテスト用ビジネスにリクエストを送り、その後で本番ビジネスのkeyを使用

サンプル · チャット一覧を取得

curl https://wisebird.cloud/external/v1/conversations?status=open&limit=20 \
  -H "Authorization: Bearer wb_live_xxxxxxxxxxxxxxxx"

どんなendpointがありますか

すべてのendpointは1つのhostの下にあり、JSONを返します。schema付きの完全なドキュメントはアプリ内にあります

グループMethodとpath用途
ConversationsGET /external/v1/conversationsチャット一覧。ステータス、チャネル、タグ、担当者で絞り込み
GET /external/v1/conversations/{id}メッセージと顧客カード付きの個別チャット詳細
GET /external/v1/conversations/searchメッセージ、顧客名、電話番号からチャットを検索
POST /external/v1/conversations/{id}/messagesお客様にメッセージを送信。text、image、video、audio、fileに対応
TagsGET, POST /external/v1/tagsタグの読み取りと作成、チャットへのタグの付与と解除
MembersGET /external/v1/membersメンバーとロールの一覧。チャットの割り当てに使用
WebhooksGET, POST /external/v1/webhooksendpointを登録し、eventを選んでtest eventを送信

サンプル · Idempotency-Key付きでメッセージを送信

curl -X POST https://wisebird.cloud/external/v1/conversations/cnv_123/messages \
  -H "Authorization: Bearer wb_live_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 7f3c2a1e-order-4512-confirm" \
  -H "Content-Type: application/json" \
  -d '{"type":"text","text":"ご注文 #4512 を承りました。2営業日以内に発送します。"}'

# 添付ファイルの送信: type を image | video | audio | file に変更し、ファイルの url を渡します
# -d '{"type":"image","url":"https://example.com/receipt.png","caption":"領収書です"}'
  • Idempotency-Keyメッセージごとの一意の値。同じキーで再送すると同じ結果が返り、お客様に二重送信されません
  • チャネルの制限ファイルの種類とサイズはチャネルによって異なります
  • Messengerビジネス側から始めるメッセージには24時間の制限があります

Webhookは何を通知し、署名はどう検証しますか

endpointを登録し、eventを選んでtest eventを送るだけ。実際のチャットを待たずにすぐテストできます

Eventv1v2発生タイミング
message.receivedありありお客様がどのチャネルからメッセージを送っても
message.sentありありAIまたはチームがメッセージを送信すると、payloadで送信者を示します
conversation.handoffありありAIが理由と要約を添えてチャットをチームに引き継ぎ
conversation.assignedなしありチャットがメンバーに割り当てられた
conversation.taggedなしありチャットにタグが追加または解除された
lead.createdなしありリードフォームまたはAIが新しいリードをパイプラインに作成
order.createdなしありチャットからの売上や注文を記録

v2ではpayloadにeventとフィールドが追加されています。v1も引き続き使えますが、新しいエンドポイントにはv2を推奨します

サンプル · あなたのendpointが受け取るpayloadと署名header

POST /your-endpoint HTTP/1.1
Content-Type: application/json
X-Wisebird-Event: conversation.handoff
X-Wisebird-Signature: t=1760600000,v1=5f1c…e2a9
X-Wisebird-Delivery: evt_01HZX…

{"id":"evt_01HZX…","version":"v2","type":"conversation.handoff",
 "business_id":"biz_42","created_at":"2026-10-16T09:30:00+07:00",
 "data":{"conversation_id":"cnv_123","channel":"line","reason":"customer_requested_human",
         "summary":"施術前に炎症性ニキビについて質問あり。医師の診察を希望"}}

# 署名の検証: HMAC-SHA256(secret, t + "." + raw_body) その後 v1 と constant-time で比較します
# t が現在時刻から許容範囲以上ずれていれば拒否し、リプレイを防ぎます

MCP、sandbox、partner API

  • Try it形式のSandboxアプリ内の開発者ページからテスト用ビジネスにリクエストを送り、結果をすぐ表示。実際の顧客には影響しません
  • MCP外部のAIツールが同じAPIキーの権限下でWisebirdをtoolとして呼び出せる
  • partner API1つのkeyで複数のビジネスを管理し、共有ウォレットのクレジットを使用。パートナー向け
  • 権限とログすべてのリクエストをactivity logに記録し、設定画面からkeyをすぐに無効化できます

サンプル · partner APIで管理対象の企業を指定

curl https://wisebird.cloud/external/v1/conversations?status=open \
  -H "Authorization: Bearer wb_partner_xxxxxxxxxxxxxxxx" \
  -H "X-Wisebird-Business: biz_42"

関連ページ

パートナープログラム

複数企業の管理、共有クレジットウォレット、一括プラン

詳細を見る

セキュリティとPDPA

データはタイ国内に保存、役割と権限、activity log

詳細を見る

CRM / パイプライン

LINEグループ、Telegram、Discord、またはあなたのwebhookへの通知ルール

通知を見る

よくある質問

WisebirdのAPIキーはどこで作成しますか

アプリのビジネス設定ページで作成します。キーは作成時に一度だけ全体が表示されるので、すぐコピーして保管してください。紛失した場合は無効化して再作成します

APIキーをquery stringで送れますか

できません。keyはHTTPS経由でAuthorization headerにBearerとして送るのみです。query stringのkeyは、URLがlogに記録されやすいため拒否されます

誤って同じメッセージを再送したらどうなりますか

メッセージごとに固有のIdempotency-Key headerを付けます。同じkeyで再送しても同じ結果が返り、お客様に重複送信されません。retryに適しています

WebhookがWisebirdからのものだとどう検証しますか

すべてのeventにはendpointのsecretから計算した署名がheaderに含まれます。生のbodyから計算して処理前に比較してください。test eventを送ってテストできます

実際のお客様に影響しないsandboxはありますか

あります。アプリの開発者ページのTry itモードはテスト用ビジネスにリクエストを送り、実際のお客様には届きません。本物の署名付きでWebhook test eventも送れます

MCPはWisebirdで何に使えますか

外部のAIツールが、チャット検索、顧客カード取得、メッセージ送信などWisebirdの機能を同じAPIキーの権限下でtoolとして呼び出せる

最初のAPIキーは無料プランで作成可能

登録してチャネルを接続し、sandboxで最初のリクエストを送ってみましょう