如何将 WhatsApp Business Calling API 与 WebRTC 集成以启用客户语音通话

直到最近，要在企业应用与 WhatsApp 超过 30 亿用户之间实现实时语音通话，仍需依赖复杂的电信基础设施。Meta 于 2025 年 7 月推出的 WhatsApp Business Calling API 改变了这一现状，企业可通过VoIP 和 WebRTC 技术，将语音通话直接集成到 WhatsApp 对话中。

该语音 API 在 WhatsApp 内开启变革性客户体验，例如：

能够与客户对话的 AI 对话代理。
一键式远程医疗咨询，直接在聊天窗口内进行。
即时、直接联系客服人员，无需“致电我们……”。

本文将指导您如何将 WhatsApp Business Calling API 与自定义 WebRTC 应用集成，实现高效的客户语音交互。我们将阐释系统架构、解析 WebRTC 的核心作用，并逐步演示构建简易的网页版呼叫代理控制面板。

了解 WhatsApp Business Calling API 以实现客户语音通话

WhatsApp Business Calling API 使企业能够与 WhatsApp 用户发起和接收 VoIP 通话。

该 API 采用“自带 VoIP 系统”模式。WhatsApp 的母公司 Meta 负责连接用户端，而您负责连接企业端。

可将WhatsApp通话视为由两部分组成：

“WhatsApp 端”：此连接段将 WhatsApp 用户连接到 Meta 的基础架构。调用 API 会为您管理此连接段。
“企业端连接”：它将 Meta 的基础设施与您企业的 VoIP 系统连接起来。WebRTC正是在这里发挥作用。

整体架构示意如下：

WhatsApp 用户→ Meta 的信令与 RTC 基础设施→您的信令与 RTC 基础设施→您的应用程序

WebRTC 如何为 WhatsApp 中的客户语音通话提供支持

WebRTC 是一种开放标准技术，它实现了通话的“业务部分”。它允许您的应用程序（例如 Web 浏览器中的客户服务代理控制面板）与 Meta 的服务器建立直接的实时音频连接，从而处理通话。

此集成的核心是使用SDP（会话描述协议）进行“握手” 。这是一个协商过程，您的应用程序和 Meta 的服务器会就如何交换音频数据达成一致。

流程如下：

Meta 会向您的服务器发送 SDP Offer。这是一个描述此次调用技术细节的提案。
您的服务器会将此 offer 传递给您的 WebRTC 应用程序。
您的 WebRTC 应用程序生成SDP Answer，同意条款并提供其自身的详细信息。
您的服务器会将 Answer 返回给 Meta。

其结果是在 Meta 的基础架构和您的 WebRTC 应用程序之间实现安全、实时的音频交换。

将 WhatsApp Business Calling API 与 WebRTC 集成的前提条件

在利用 WhatsApp Business Calling API 进行开发之前，必须按如下方式配置WhatsApp Cloud API：

获取云 API 访问权限：在 developers.meta.com 注册。
创建应用和业务组合：若尚未拥有，您需创建新的 Meta 应用并设置业务组合。后者将提供测试电话号码供您启动服务。
获取访问令牌：在您的业务组合中，创建一个系统用户访问令牌。需包含whatsapp_business_messaging和whatsapp_business_management权限。
配置 Webhook：必须设置一个安全的 HTTPS 端点，以便接收来自 Meta 的 Webhook 通知。此 Webhook 必须订阅calls字段。这是 WhatsApp 与您的应用程序进行通话的入口点，每次通话的初始 SDP offer 均在此处接收。
启用测试号码的呼叫功能：这是关键步骤。您必须向 Graph API 的/{your-phone-number-id}/settings的端点发送 POST请求，并附带以下 JSON 信息以激活呼叫功能：

curl -X POST https://graph.facebook.com/v24.0/<your-phone-id>/settings \
-H 'Authorization: Bearer <your-token>' \
-H 'Content-Type: application/json' \
-d '{"calling":{"status":"ENABLED"}}'

使用 WebRTC 和 WhatsApp 构建客户语音通话演示

我们的演示由一个简单的服务器（Node.js/Express）和一个充当“agent 应用程序”的单客户端网页（HTML/JS）组成。您可以在WebRTC.ventures GitHub 存储库中找到此演示的完整代码。

请注意，此演示仅展示了集成功能，但并不具备生产级系统所需的功能，例如：

用于管理多个 agent 的连接和状态的信令服务器。
呼叫路由系统，用于将呼入电话定向到正确的 agent 人员或队列。
媒体和 ICE 服务器（STUN/TURN）可确保所有用户网络（如防火墙和移动数据）的可靠音频连接。

以下是接听电话的步骤：

第一步：用户调用

WhatsApp 用户在与您的企业号码聊天时点击了通话图标。

第二步：Meta 发送 Webhook

您的服务器会在 webhook URL 收到一个 POST 请求。该请求包含“ connect ”操作以及call_id 和 WhatsApp Business Calling API。

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "1129445659302036",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "12345678900",
              "phone_number_id": "1234567890123456"
            },
            "contacts": [
              {
                "profile": {
                  "name": "John Doe"
                },
                "wa_id": "15551234567"
              }
            ],
            "calls": [
              {
                "id": "<call-id>",
                "from": "15551234567",
                "to": "12345678900",
                "event": "connect",
                "timestamp": "1762216151",
                "direction": "USER_INITIATED",
                "session": {
                  "sdp": "<the-sdp-offer>",
                  "sdp_type": "offer"
                }
              }
            ]
          },
          "field": "calls"
        }
      ]
    }
  ]
}

第三步：服务器到浏览器

您的服务器通过 WebSocket 连接将 call_id 和 SDP Offer 转发到您 agent 的浏览器。agent 的界面现在会显示“来电”提示。

// app.js
...
if (call.event === 'connect') {
    // Broadcast incoming call to all connected clients
    const callEvent = {
      type: 'incoming_call',
      callId: call.id,
      phoneNumberId: callData.metadata.phone_number_id,
      from: call.from,
      to: call.to,
      sdp: call.session?.sdp,
      timestamp: call.timestamp
    };
  
    wsClients.forEach(client => {
      if (client.readyState === WebSocket.OPEN) {
        client.send(JSON.stringify(callEvent));
      }
    });
} ...

第四步：Agent 点击“Answer”

如何将 WhatsApp Business Calling API 与 WebRTC 集成以启用客户语音通话 — Demo 正在接收来自 Meta 服务器的调用。

第五步：浏览器到服务器

agent 的浏览器建立连接并创建 SDP Answer 以发送回您的服务器。

// index.html
...
async function setupWebRTC(remoteSdp) {
    try {
        // Get user media (audio only)
        localStream = await navigator.mediaDevices.getUserMedia({ 
            audio: true 
        });

        // Create peer connection
        peerConnection = new RTCPeerConnection({
            iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
        });

        // Add local stream
        localStream.getTracks().forEach(track => {
            peerConnection.addTrack(track, localStream);
        });

        // Handle remote stream
        peerConnection.ontrack = (event) => {
            document.getElementById('remoteAudio').srcObject = event.streams[0];
        };
                
        // Handle ICE candidates
        peerConnection.onicecandidate = (event) => {
            if (event.candidate) {
                console.log('ICE candidate:', event.candidate);
            }
        };

        // Set remote description (offer from WhatsApp)
        await peerConnection.setRemoteDescription({
            type: 'offer',
            sdp: remoteSdp
        });

        // Create answer
        const answer = await peerConnection.createAnswer();
        await peerConnection.setLocalDescription(answer);

        ...
        
    } catch (error) {
        console.error('WebRTC setup error:', error);
        status.textContent = 'Error setting up call';
    }
}
...

第六步：WebRTC应用程序“预接受”呼叫

WebRTC 应用程序会提示服务器向 Meta 发送 POST 请求以启动连接过程。这会告知 Meta 您已准备好响应。

第七步：WebRTC 连接

浏览器和 Meta 的服务器现在会在后台建立 RTCPeerConnection。您的应用程序需要监听连接状态的变化，以确认连接是否建立。

第八步：服务器“接受”呼叫

连接建立后，您的应用程序会向 Meta 发送最终 POST 请求：

// index.html
...
// Handle connection state changes
peerConnection.onconnectionstatechange = () => {
    console.log('Connection state:', peerConnection.connectionState);
    if (peerConnection.connectionState === 'connected' 
&& currentCall?.preAcceptSent) {
        sendAccept();
    }
};
...

第九步：呼叫已接通

现在，用户和您的 agent 之间可以即时传输媒体文件。