WhatsApp番号の接続（API）

自社のアプリから、WhatsApp番号をワークスペースに接続する処理を開始します。Wbiztoolが新しいWhatsAppセッションを開き、QRコードをあなたのWebhook URLに送信します。そのQRコードをスマートフォンの持ち主に見せ、WhatsAppでスキャンしてもらうと、番号からメッセージを送信できるようになります。

ご自身の番号を手動でリンクする場合は、WhatsApp番号を接続するの手順に従ってください。

POST /api/v1/whatsapp-client/create/は完全に同じエイリアスで、同じコードを実行し、同じレスポンスを返します。どちらのパスも引き続き使用できます。

接続の流れ#

APIの呼び出しは接続を開始するだけです。QRコードは後から、あなたのWebhook URLに届きます。

1. 接続APIを呼び出す

   電話番号とwebhook_urlを送信します。レスポンスでwhatsapp_client_idが返るので、保存しておいてください。

2. QRコードを受け取る

   Webhookがstatus=qr_generatedを受け取り、qr_imageにQRコードの画像が含まれます。その画像をスマートフォンの持ち主に見せてください。Wbiztoolがスキャンを待っている間、QRコードは数秒ごとに再送信されるため、常に最新のものを表示してください。スキャンできる時間は約2分です。それを過ぎた場合や、WhatsAppがコードの再読み込みを求めた場合はnot_connectedを受け取ります。APIを再度呼び出して新しいコードを取得してください。

3. WhatsAppでスキャンする

   スマートフォンでWhatsAppを開き、リンク済みデバイス → デバイスをリンクを選んでコードをスキャンします。

4. 結果を受け取る

   番号がリンクされるとWebhookがstatus=connectedを受け取ります。時間内にコードがスキャンされなかった場合や接続に失敗した場合はstatus=not_connectedを受け取ります。connectedイベントは、接続ステータスがConnectedを返す数秒前に届くことがあります。まずWebhookに応答し、その後、最大1分間、数秒ごとに接続ステータスをポーリングしてください。Webhookハンドラーの中で1回だけ確認することはしないでください。

クイック例#

curl -X POST https://wbiztool.com/api/v1/whatsapp/connect/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_number": "919876543210",
    "webhook_url": "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET"
  }'

import requests

response = requests.post(
    "https://wbiztool.com/api/v1/whatsapp/connect/",
    json={
        "client_id": 12345,
        "api_key": "YOUR_API_KEY",
        "whatsapp_number": "919876543210",
        "webhook_url": "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
    },
    timeout=30,
)
result = response.json()  # read the body even when the HTTP code is 400 or 403

if result.get("status") == 1:
    print("Waiting for QR code, whatsapp_client_id", result["whatsapp_client_id"])
else:
    print("Failed:", result.get("message"))

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/whatsapp/connect/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: 12345,
    api_key: "YOUR_API_KEY",
    whatsapp_number: "919876543210",
    webhook_url: "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
  }),
});
const result = await response.json(); // read the body even when the HTTP code is 400 or 403

if (result.status === 1) {
  console.log("Waiting for QR code, whatsapp_client_id", result.whatsapp_client_id);
} else {
  console.error("Failed:", result.message);
}

<?php
$payload = [
    'client_id'       => 12345,
    'api_key'         => 'YOUR_API_KEY',
    'whatsapp_number' => '919876543210',
    'webhook_url'     => 'https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET',
];

$ch = curl_init('https://wbiztool.com/api/v1/whatsapp/connect/');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($result['status'] ?? 0) === 1) {
    echo 'Waiting for QR code, whatsapp_client_id ' . $result['whatsapp_client_id'];
} else {
    echo 'Failed: ' . ($result['message'] ?? 'no response');
}

12345とYOUR_API_KEYはご自身の値に置き換えてください。値の確認場所は認証をご覧ください。

リクエストパラメータ#

公式クライアントを使う#

Pythonクライアントは、/api/v1/whatsapp-client/create/を代わりに呼び出します。

from wbiztool_client import WbizToolClient

client = WbizToolClient(api_key="YOUR_API_KEY", client_id=12345)

result = client.create_whatsapp_client(
    whatsapp_number="919876543210",
    webhook_url="https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
)
print(result)

Pythonクライアントは、APIがHTTP 400または403を返すとrequests.exceptions.HTTPErrorを発生させるため、呼び出しをtry/exceptで囲んでください。

レスポンス#

接続リクエストが作成されると、APIはHTTP 200を返します。

{
  "message": "Whatsapp Client Created",
  "whatsapp_client_id": 678,
  "status": 1
}

"status": 1はリクエストが作成されたことを意味し、番号が接続されたことを意味するわけではありません。以前に追加したものの接続されていない番号でAPIを再度呼び出すと、同じwhatsapp_client_idが返り、新しい接続の試行が始まります。

エラー#

POST以外のリクエストには、HTTP 200で空のオブジェクト{}が返ります。

同じアカウントのオーナーがこの番号を別のワークスペースですでに追加している場合、リクエストがHTTP 500で失敗することがあります。目的のワークスペースでWhatsApp設定から番号を接続するか、サポートにお問い合わせください。

Webhookイベント#

Wbiztoolは各ステップでwebhook_urlにPOSTを送信します。ボディはJSONではなく、フォームエンコード（application/x-www-form-urlencoded）です。

QRコードの準備完了（スキャンを待っている間、数秒ごとに再送信されます。URLは同じであることがよくあります）：

status=qr_generated&whatsapp_client_id=678&qr_image=...

番号の接続完了（同じ接続に対して複数回送信されることがあります）：

status=connected&whatsapp_client_id=678

接続失敗（例：QRコードが時間内にスキャンされなかった場合）：

status=not_connected&whatsapp_client_id=678

URLは公開されていてアクセスできる必要があり、数秒以内に応答してください。Wbiztoolはタイムアウトなしで応答を待ちます。サーバーにアクセスできない場合、番号が接続済みとして保存される前に接続処理が止まることがあります。HTTPステータスコードはどれでも受け付けられます。配信に失敗しても再試行されず、後で番号の接続が切れても何も送信されません。接続後の番号の状態を追跡するには、接続ステータスをポーリングしてください。

Webhookの代わりにポーリングする#

サーバーがWebhookを受信できない場合でも、QRコードを取得するためにWebhookは必要です。ただし、接続結果についてはWebhookに頼る必要はありません。QRコードがスキャンされた後、Connectedが返るまで数秒ごとにwhatsapp_client_idを指定して接続ステータスを呼び出してください。アカウント一覧では、すべての番号について同じ情報を確認できます。

ヒント#

• 重複イベントに対応する：connectedは2回届くことがあります。ハンドラーは複数回実行されても問題ないようにしてください。
• 最新のQRコードを表示する：新しいqr_generatedイベントが届くたびに画像を置き換え、https URLにはキャッシュを回避するクエリを追加してください。古いコードは使えなくなります。
• 約2分以内にスキャンする：それを過ぎるとnot_connectedを受け取ります。APIを再度呼び出して新しいコードを取得してください。
• 10分経ってもQRコードが届かない場合：リクエストの期限が切れています。APIを再度呼び出してください。
• ダッシュボードからの接続のほうが簡単です：ご自身の番号をリンクする場合は、WhatsApp設定でコードをスキャンしてください。