Voiceflow无法获取HTTP POST请求处理器响应数据原因排查

问题描述 #

我有一个简单的PHP HTTP POST请求处理器（下文简称HANDLER），用自定义PHP请求脚本（下文简称REQUESTOR）调用时，能正常获取HANDLER返回的status、message和data字段（见REQUESTOR OUTPUT）。但通过Voiceflow的API步骤调用该处理器时，请求返回状态码200，但响应里完全没有这些字段（见VOICEFLOW RESPONSE DISPLAY），请问原因是什么？

HANDLER 代码 #

<?php

// 检查请求方法是否为POST
if ($_SERVER["REQUEST_METHOD"] === "POST") {
    // 验证必要参数（示例）
    // 比如检查必填字段是否存在

    // 处理认证（如果需要）
    // 比如验证API密钥或OAuth令牌

    // 处理请求
    $postData = $_POST; // 获取POST数据
    // 执行必要的处理或验证

    // 生成响应
    $response = array(
        "status" => "success!",
        "message" => "Request processed successfully",
        "data" => $postData // 返回需要的数据
    );

    // 发送JSON响应
    header('Content-Type: application/json');
    echo json_encode($response);
} else {
    // 处理其他请求方法（可选）
    http_response_code(405); // 方法不允许
    echo "This endpoint only accepts POST requests.";
}

?>

REQUESTOR 代码 #

<?php
// POST请求处理器的URL
$handlerUrl = 'http://easy-street-2.local/ee/postRequestHandler.php';

// 要发送的POST数据
$postData = array(
    'username' => 'john',
    'password' => 'password123'
);

// 初始化cURL会话
$ch = curl_init();

// 设置POST请求的cURL选项
curl_setopt($ch, CURLOPT_URL, $handlerUrl);         // 设置请求目标URL
curl_setopt($ch, CURLOPT_POST, true);               // 设置请求方法为POST
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);    // 设置要发送的POST数据
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);     // 设置返回响应为字符串而非直接输出

// 执行cURL请求并获取响应
$response = curl_exec($ch);

// 检查错误
if ($response === false) {
    echo 'Error: ' . curl_error($ch); // 请求失败时输出错误信息
} else {
    // 输出响应
    echo 'Response: ' . $response; // 输出处理器返回的响应
}

// 关闭cURL会话
curl_close($ch);
?>

REQUESTOR 输出 #

Response: {"status":"success","message":"Request processed successfully","data":{"username":"john","password":"password123"}}

VOICEFLOW 响应（无status、message及data字段） #

{
 "VF_STATUS_CODE": 200,
 "VF_HEADERS": {
  "connection": "close",
  "content-encoding": "gzip",
  "content-type": "text/html; charset=UTF-8",
  "date": "Fri, 01 Mar 2024 19:28:44 GMT",
  "strict-transport-security": "max-age=15724800; includeSubDomains",
  "transfer-encoding": "chunked",
  "vary": "Accept-Encoding",
  "x-powered-by": "PHP/8.1.23"
 }
}

Voiceflow API步骤配置 #

问题原因及解决办法 #

核心原因 #

从Voiceflow返回的响应头可以看到，content-type为text/html; charset=UTF-8，但HANDLER明明设置了Content-Type: application/json，说明HANDLER的JSON响应逻辑未正常生效，同时Voiceflow未接收到预期的响应体内容，具体可能的触发点：

1. 请求格式不兼容：REQUESTOR发送的是表单格式（application/x-www-form-urlencoded）的POST数据，而Voiceflow配置的是JSON格式的请求体，PHP的$_POST无法直接获取JSON格式的请求数据，虽不会阻断响应，但可能引发后续输出异常。
2. 前置输出导致Header失效：PHP文件开头存在空格、UTF-8 BOM或错误警告输出，使得header('Content-Type: application/json')无法正常发送，PHP自动默认返回text/html类型，Voiceflow因类型不匹配忽略响应体。
3. 服务器压缩或传输异常：HTTPS环境下的服务器开启了gzip压缩，但响应体未被正确传输或Voiceflow未完成解压，导致无法解析响应内容。

解决步骤 #

1. 兼容JSON与表单两种请求格式
   修改HANDLER代码，支持解析JSON格式的请求体：

<?php
// 检查请求方法是否为POST
if ($_SERVER["REQUEST_METHOD"] === "POST") {
    // 兼容表单和JSON格式的POST数据
    $postData = [];
    if (isset($_SERVER['CONTENT_TYPE']) && strpos($_SERVER['CONTENT_TYPE'], 'application/json') !== false) {
        $postData = json_decode(file_get_contents('php://input'), true) ?: [];
    } else {
        $postData = $_POST;
    }

    // 生成响应
    $response = array(
        "status" => "success",
        "message" => "Request processed successfully",
        "data" => $postData
    );

    // 清空输出缓冲区，确保Header正常发送
    ob_clean();
    header('Content-Type: application/json');
    echo json_encode($response);
    exit; // 终止脚本，避免后续意外输出
} else {
    http_response_code(405);
    ob_clean();
    header('Content-Type: application/json');
    echo json_encode(["status" => "error", "message" => "仅接受POST请求"]);
    exit;
}
?>

2. 清除PHP文件的前置输出
   确保<?php标签是文件的第一个字符，删除标签前的空格、换行或UTF-8 BOM；也可在脚本开头添加ob_start()开启输出缓冲，避免意外输出干扰Header。

3. 添加请求日志排查问题
   在HANDLER中添加日志代码，记录Voiceflow发送的请求细节，确认请求是否符合预期：

// 记录请求日志
$logContent = date('Y-m-d H:i:s') . " - 请求方法: " . $_SERVER["REQUEST_METHOD"] . "\n";
$logContent .= "Content-Type: " . ($_SERVER['CONTENT_TYPE'] ?? '未设置') . "\n";
$logContent .= "请求体: " . file_get_contents('php://input') . "\n\n";
file_put_contents('request_log.txt', $logContent, FILE_APPEND);

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