signal-cli中通过HTTP JSON-RPC添加消息反应的实现指南

signal-cli作为Signal命令行客户端，提供了丰富的功能接口，其中通过HTTP JSON-RPC协议添加消息反应是一个实用但需要特别注意参数格式的功能。本文将详细介绍如何正确实现这一功能。

核心参数解析

在signal-cli中，sendReaction方法需要以下关键参数：

1. 目标标识参数：

   • 对于个人用户：可使用username(仅限用户名)或recipient(支持电话号码/UUID)
   • 对于群组：使用groupId

2. 反应目标参数：

   • targetAuthor：必须指定消息发送者的标识，格式为"u:用户名"或"g:群组ID"
   • targetTimestamp：必须是数值类型(long)，表示目标消息的时间戳

3. 反应内容：

   • emoji：要发送的表情符号

常见错误及解决方案

1. NullPointerException错误：

   • 通常由于参数名称大小写错误导致，如将targetTimestamp写成TargetTimestamp
   • 确保所有参数名称使用正确的小写形式

2. ClassCastException错误：

   • 当targetTimestamp以字符串形式传递而非数值时发生
   • 必须确保时间戳是数值类型，如1732221973526而非"1732221973526"

3. 参数缺失错误：

   • 缺少targetAuthor参数会导致操作失败
   • 必须明确指定消息的原作者

实现示例

以下是Python实现示例，展示了如何正确构造请求：

import requests
import json
import uuid

def send_signal_reaction(target_type, target_id, msg_timestamp, emoji, target_author):
    """
    发送Signal消息反应
    
    参数:
        target_type: "user"或"group"
        target_id: 用户名/电话号码/UUID(用户)或群组ID(群组)
        msg_timestamp: 目标消息时间戳(数值)
        emoji: 要发送的表情
        target_author: 消息原作者标识("u:用户名"或"g:群组ID")
    """
    payload = {
        "jsonrpc": "2.0",
        "method": "sendReaction",
        "params": {
            "emoji": emoji,
            "targetTimestamp": int(msg_timestamp),
            "targetAuthor": target_author
        },
        "id": str(uuid.uuid4().hex)
    }
    
    # 根据目标类型添加不同标识参数
    if target_type == "user":
        payload["params"]["recipient"] = target_id
    elif target_type == "group":
        payload["params"]["groupId"] = target_id
    
    response = requests.post(
        "http://127.0.0.1:8080/api/v1/rpc",
        headers={'Content-Type': 'application/json'},
        data=json.dumps(payload)
    )
    
    return response.json()

# 使用示例
response = send_signal_reaction(
    target_type="user",
    target_id="user.00",
    msg_timestamp=1732221973526,
    emoji="👍",
    target_author="u:user.00"
)
print(response)

最佳实践建议

1. 参数验证：

   • 在使用前验证所有参数类型
   • 特别是确保时间戳为数值类型

2. 错误处理：

   • 捕获并处理可能出现的网络错误
   • 解析返回的JSON错误信息

3. 日志记录：

   • 记录请求和响应数据以便调试
   • 但注意不要记录敏感信息

4. 性能考虑：

   • 复用HTTP连接
   • 考虑异步实现以提高吞吐量

通过遵循这些指南，开发者可以稳定地在signal-cli中实现消息反应功能，丰富基于Signal的自动化交互体验。