ユーザーが WhatsApp、Instagram、TikTok のアカウントをアプリに接続できるようにする方法
ユーザーが WhatsApp、Instagram、TikTok のアカウントをアプリに接続できるようにするには、easyCoexistence の Partner API で接続セッションを作成し、ホスト型の URL にユーザーを案内します。ユーザーはそこで Meta の Embedded Signup を使って WhatsApp 番号を接続するか、Instagram、Facebook、TikTok、YouTube、LinkedIn などのチャンネルにサインインします。その後、新しい接続またはチャンネルの ID とともに redirect_url に戻ります。リンクの有効期間は 1 時間です。
接続リンクの有効期間。それを過ぎるとセッションは「expired」と表示され、新しいセッションが必要です。
1 つのアカウントが同時に保持できる接続セッション数と、1 時間あたり 100 件の新規セッションの上限。
セッションは作成、オープン、接続済み、キャンセル、期限切れのいずれかで、GET /connect-sessions/:id がその状態を返します。
WhatsApp 番号のメッセージ Webhook を別の宛先に転送するために Meta が受け付ける、代替コールバック URL の最大長。
接続リンクはどのように動作しますか?
決済ページと同じ仕組みです。バックエンドでセッションを作成し、お使いのフロントエンドからお客様をそのホスト型 URL に案内します。お客様は easycoexistence.com のページで接続し、ブラウザは redirect_url に戻ります。その後バックエンドが結果を確認し、新しい接続の認証情報を取得します。いずれも API キーを使って行います。
リクエストには何を含めますか?
https://easycoexistence.com/api/v1/connect-sessions に JSON ボディを POST し、API キーを Bearer トークンとして渡します。必須なのは redirect_url のみです:
redirect_url: お客様が完了後に到着する https の URL。- channel: whatsapp(既定値)、またはお使いのアカウントで利用可能なソーシャルネットワーク。小文字の名前で指定します(例:instagram、tiktok、youtube)。
external_ref: このお客様を示すご自身の ID。200 文字まで。partner_name: ホスト型ページに表示される名前。80 文字まで。既定ではアカウント名が使われます。webhook_urlとwebhook_verify_token: 番号のみで、必ず両方を一緒に指定します。Meta は接続の時点から、その番号のメッセージをここに配信します。
curl -X POST https://easycoexistence.com/api/v1/connect-sessions \
-H "Authorization: Bearer $EC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel": "whatsapp",
"redirect_url": "https://app.example.com/connect/return",
"external_ref": "customer_4821",
"partner_name": "ClinicApp",
"webhook_url": "https://hooks.example.com/wa/<long-random-secret>",
"webhook_verify_token": "another-long-random-string"
}'何が返されますか?
201 でセッションが返されます。お客様を url に案内し、後でセッションを検索するために cs_ で始まる id を保存してください。expires_at は作成から 1 時間後になります。connection_id または channel_id は、セッションのチャンネルに応じて、お客様が接続した時点で入ります。GET /connect-sessions/:id は、いつでも同じ形式を返します。
{
"id": "cs_…",
"url": "https://easycoexistence.com/connect/cs_…",
"channel": "whatsapp",
"status": "created",
"external_ref": "customer_4821",
"connection_id": null,
"channel_id": null,
"token_ready": false,
"redirect_url": "https://app.example.com/connect/return",
"webhook_url": "https://hooks.example.com/wa/<long-random-secret>",
"last_error": null,
"expires_at": "2026-10-31T15:00:00.000Z",
"opened_at": null,
"finished_at": null,
"created_at": "2026-10-31T14:00:00.000Z"
}セッションの作成でどのエラーが返される可能性がありますか?
どのエラーも同じ形式で、code と message を持つオブジェクトです。message には修正すべき点が書かれています。セッションの作成では次が返されることがあります:
- 400
invalid_jsonまたはinvalid_request: ボディが JSON オブジェクトではない、またはフィールドの検証に失敗した(https でないredirect_urlなど)。 - 400
channel_unavailable: このアカウントでそのチャンネルは開かれていません。message に利用可能なチャンネルが列挙されます。 - 401 unauthorized: API キーがない、または無効です。
- 402
billing_required: アカウントにカードが未登録です。このアカウント経由で接続されたものはすべて、ここに請求されます。 - 429
cap_reached: すでに 50 件のセッションが開いています。完了または期限切れを待ってください。 - 429
rate_limited: 1 時間に 100 件を超えています。message に待機時間が示されます。
完了後、お客様はどこに戻りますか?
redirect_url に、結果がクエリ文字列に追加された状態で戻ります。同じ結果がセッションにも保存されており、バックエンドは GET /connect-sessions/:id で読み取ります:
- session: セッション ID。cs_ に続けてランダムな文字列。
- status: connected、またはお客様が「キャンセルして戻る」を選んだ場合は cancelled。
external_ref: セッションに値があった場合の、お客様の ID。connection_id: 新しい番号の ID。/connections で使用します。channel_id: 新しいソーシャルアカウントの ID。/channels で使用します。
https://app.example.com/connect/return?session=cs_…&status=connected&external_ref=customer_4821&connection_id=…セッションにはどのステータスがありますか?
5 種類あります。GET /connect-sessions/:id は現在のステータスを返します。あわせて opened_at、finished_at、last_error も返し、last_error は直近の試行が失敗した理由を示します:
- created: バックエンドが作成した状態。まだ開かれていません。
- opened: お客様がホスト型ページを読み込みました。
- connected: 番号またはソーシャルアカウントが接続され、その ID がセッションに記録されています。
- cancelled: お客様が「キャンセルして戻る」で離脱しました。
- expired: セッションが完了する前に 1 時間が経過しました。
リンクはどのくらいの期間有効ですか?
作成から 1 時間です。その後、ホスト型ページはお客様に、リンクの期限が切れたことを伝え、status=cancelled を付けて redirect_url に戻るボタンを表示します。セッションは expired と表示されます。アカウントは同時に 50 件のセッションを開いておけ、1 時間に 100 件を作成できます。これは、Meta が初回のオンボーディングをすべて、すべてのアカウントで共有されるアプリ全体の上限に計上するためです。
external_ref は何をしますか?
各接続をお客様に紐づけます。送信した値は、セッションが作成する番号またはチャンネルに保存され、リダイレクトに追加され、それに関するすべてのステータスイベントに含まれます。そのため、GET /connections?external_ref=customer_4821 と GET /channels?external_ref=customer_4821 で、そのお客様が接続したものを一覧できます。Facebook や LinkedIn のサインインでは、1 回で複数の Page が接続されることがあります。リダイレクトには最初の Page が示され、フィルターでは残りが一覧されます。変わる可能性のあるメールアドレスではなく、ご自身のデータベースの安定した ID を使ってください。
お客様がキャンセルした場合や、サインインに失敗した場合はどうなりますか?
それは発生した場所によって異なります。セッションには記録が残ります:
- Meta のポップアップが失敗した、または閉じられた: リンクが開いている間に、お客様は同じページで「接続する」をもう一度押します。
- ソーシャルのサインインがキャンセルされた、または拒否された: お客様は理由とともにホスト型ページに戻り、リンクが期限切れになるまで再試行できます。
- アカウントが別の easyCoexistence のアカウントですでに接続されている:
last_errorにその旨が記録され、お客様は別のアカウントでサインインします。 - お客様が「キャンセルして戻る」を選んだ:
redirect_urlに status=cancelled が渡され、セッションは閉じられます。別の試行には新しいセッションを作成してください。 - リンクが期限切れになった: 新しいセッションを作成してください。
お客様のトークンが発行されずに番号が接続された場合はどうなりますか?
Meta は、お客様ご自身のビジネストークンを発行せずに Embedded Signup を完了させることがあります。その場合、ホスト型ページは数秒かかる手順をもう一度行うよう求めます。お客様がこれを飛ばすと、セッションは token_ready が false の connected と表示され、お使いのイベント URL には connection.token_missing が届きます。番号の ID は有効なのでメッセージは受信できますが、新しい接続セッションで再接続され、トークンが発行されるまで送信はできません。
webhook_url が Meta の確認に通らなかった場合はどうなりますか?
それでも番号は接続されます。Meta は webhook_url を GET のハンドシェイクで確認します。エンドポイントは hub.verify_token が一致したとき hub.challenge を返せば通過します。失敗した場合、セッションの last_error は webhook_url was not applied で始まり、Meta の理由が続きます。エンドポイントが応答するようになったら、PUT /connections/:id/webhook で送信先を設定できます。接続から 24 時間以内に設定すれば、連絡先の一度限りのインポートと、お客様が共有に同意していればチャット履歴も受信できます。
お客様には何が表示されますか?
easycoexistence.com のページが表示され、partner_name に設定した名前が出ます。アカウント、メールアドレス、カードの入力は不要です。WhatsApp 番号の場合は、利用条件の簡単なチェックリストが表示され、その後 Meta のポップアップと、WhatsApp Business アプリでスキャンする QR コードが表示されます。ソーシャルアカウントの場合は「TikTok で続行」のようなボタンが 1 つ表示され、ネットワーク独自の同意画面が同じタブで開くため、スマートフォンでも動作します。
よくある間違い
- クエリ文字列だけを信用すること。誰でも URL に status=connected と入力できるため、お客様を接続済みとして扱う前に、バックエンドから GET /connect-sessions/:id で確認してください。
- リンクを iframe に埋め込むこと。リダイレクトまたは新しいタブで案内してください。ホスト型ページとそこから開くサインインは、その方法で動作するように設計されています。
- リンクを事前に作成すること。各リンクは 1 時間有効で、開いているすべてのリンクが上限 50 件に含まれます。お客様が接続しようとするタイミングでセッションを作成してください。
- 200 文字を超える webhook_url を送ること。Meta が受け付ける代替コールバック URL は 200 文字までなので、それより長い URL は適用されず、番号はそれなしで接続されます。
easyCoexistence は、お客様の WhatsApp 番号、そして Instagram、Facebook、TikTok、YouTube、LinkedIn のアカウントなど、さらに多くのチャンネルを、1 つのホスト型リンクでお使いのソフトウェアに接続します。その後、接続ごとの認証情報、Webhook、署名付きステータスイベントをバックエンドに渡します。料金は接続 1 件あたり月額 US$ 9 から、接続を増やすほど下がり US$ 0.75 まで。最初の 3 日間は無料トライアルです。
よくある質問
1 つの接続リンクを 2 回使えますか?
いいえ。リンクは 1 つの番号、または 1 回のソーシャルサインインで完了します。Facebook や LinkedIn では複数の Page が接続されることがあります。その後リンクは connected と表示されるため、次の接続には新しいセッションを作成してください。
リンクをメールやチャットで送れますか?
はい。お客様が 1 時間以内に開けば問題ありません。URL のセッション ID がページの認可の役割を果たすため、各リンクはそのリンクを作成したお客様にだけ送ってください。
ホスト型ページはスマートフォンで動作しますか?
ソーシャルのサインインは動作します。同じタブで開くためです。WhatsApp 番号はパソコンから接続するのが最適です。スマートフォンでは Meta のポップアップが新しいタブで開き、QR コードをスキャンするにはそのスマートフォンが必要になります。
ポーリングせずにお客様の接続を知るにはどうすればよいですか?
ダッシュボードの「Profile」「Developers」からステータスイベント URL を設定してください。接続が完了すると、easyCoexistence は署名付きで external_ref を含む connection.connected または channel.connected を送信します。
続きを読む
最初のチャンネルを 2 分で接続しましょう。
プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。
- 3 日間無料
- いつでも解約可能
- 公式 API のみ使用
- 24/7 監視
確認日