如何在Laravel PHP中序列化WhatsApp消息payload提取消息体、phone_number_id及联系人

在Laravel中处理WhatsApp（Meta）的Webhook回调不需要手动做序列化操作，Laravel会自动解析application/json类型的请求体，直接通过请求实例就能读取 payload 数据，按以下步骤提取需要的字段即可：

1. 基础请求过滤 #

首先在控制器方法中先过滤非消息类的回调事件，WhatsApp会推送多种类型的Webhook事件，只有field为messages的是消息通知：

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class WhatsAppWebhookController extends Controller
{
    public function handle(Request $request)
    {
        // 生产环境请先添加Meta签名校验逻辑，过滤伪造请求
        if ($request->input('field') !== 'messages') {
            return response('ok', 200);
        }

        $payload = $request->input('value');
        
        // 后续字段提取都基于$payload处理
    }
}

2. 提取phone_number_id #

该字段固定存放在metadata节点下，是当前接收消息的WhatsApp号码唯一标识：

$phoneNumberId = $payload['metadata']['phone_number_id'];
// 可同步提取对外展示的号码字符串
$displayNumber = $payload['metadata']['display_phone_number'];

3. 提取联系人信息 #

联系人信息存放在contacts数组中，单聊场景下数组仅包含1个元素，对应发送消息的用户：

$contact = null;
if (isset($payload['contacts'][0])) {
    $contactData = $payload['contacts'][0];
    $contact = [
        'wa_id' => $contactData['wa_id'], // 联系人的WhatsApp账号，即对方手机号
        'name' => $contactData['profile']['name'] // 联系人对外展示的昵称
    ];
}

4. 提取消息正文 #

消息内容存放在messages数组中，文本类型的消息正文存放在对应类型节点的body字段下：

$messageBody = '';
$messageId = '';
$from = '';
$timestamp = 0;

if (isset($payload['messages'][0])) {
    $message = $payload['messages'][0];
    $messageId = $message['id'];
    $from = $message['from'];
    $timestamp = (int)$message['timestamp'];
    $messageType = $message['type'];

    // 文本消息正文提取
    if ($messageType === 'text') {
        $messageBody = $message['text']['body'];
    }

    /*
    其他类型消息可对应扩展提取逻辑：
    - 图片消息：附带文本在$message['image']['caption']，媒体ID在$message['image']['id']
    - 语音消息：媒体ID在$message['audio']['id']
    - 位置消息：经纬度在$message['location']['latitude']、$message['location']['longitude']
    */
}

注意事项：如果回调包含多条消息、群聊场景下多联系人的情况，需要遍历contacts和messages数组做匹配处理，不要固定取下标为0的元素；所有字段读取建议先做isset判断，避免异常格式 payload 导致报错。

内容的提问来源于stack exchange，提问作者proflinksgh