Titanmind Whatsapp MCP

🚀 Titanmind WhatsApp MCP

Titanmind WhatsApp MCP 是一款基于 Titanmind 的 WhatsApp 营销与消息服务工具，采用了模型控制协议（MCP）。它能够自动处理自由格式消息（24 小时窗口期）和模板工作流。

🚀 快速开始

本服务借助 Titanmind 提供了所有 WhatsApp 营销和消息功能，包括模板创建、模板注册（涵盖标题、正文、CTA 等所有组件）、向大量电话号码批量广播模板，以及在活跃对话中读取和发送消息。

此 MCP 服务依赖于 Titanmind。使用该 MCP 必须拥有 Titanmind 账户。

Titanmind 提供了强大的功能，如对话管理、日程安排、智能对话、内容生成等，可增强 WhatsApp 的通信能力。

✨ 主要特性

对话管理

获取最近对话

• 检索过去 24 小时内有消息收发的所有对话。
• 返回包含最近活动的对话数据。

获取对话消息

• 从特定对话中获取所有消息。
• 需要参数：conversation_id（字母数字组成的对话标识符）。

发送 WhatsApp 消息

• 向现有的 WhatsApp 对话发送消息。
• 需要参数：conversation_id 和 message 内容。

模板管理

创建消息模板

• 注册新的 WhatsApp 消息模板以获得审批。
• 配置模板名称（只能为单个单词，允许使用下划线）。
• 设置语言（默认：“en”）和类别（营销、实用、认证）。
• 构建消息组件，包括：
  • 正文（必填）：主要文本内容。
  • 标题（可选）：支持文本、视频、图像或文档格式。
  • 页脚（可选）：页脚文本。
  • 按钮（可选）：支持快速回复、URL 或电话号码操作。

获取模板

• 检索所有已创建模板及其审批状态。
• 可根据模板名称进行可选过滤。

批量发送消息

• 使用已批准的模板向多个电话号码发送消息。
• 需要参数：template_id 和联系人列表。
• 联系人格式：国家代码缩写（如“IN”）、国家代码（如“91”）和电话号码。

📦 安装指南

前提条件

• Python 3.10 或更高版本。
• 从 Titanmind 获取的 API 密钥和业务代码。

使用 MCP 客户端

在任何 MCP 客户端（如 Claude 或 Cursor）中，可以通过以下方式添加 Titanmind WhatsApp MCP 配置：

使用 Titanmind WhatsApp MCP Python 包

1. 安装 pipx 以全局安装 Python 包：

# 终端命令

# 首先安装 pipx
brew install pipx  # 在 macOS 上
# 或者
sudo apt install pipx  # 在 Ubuntu/Debian 上

# 然后安装 Titanmind WhatsApp MCP Python 包 
pipx install titanmind-whatsapp-mcp

# 确保 '/[HOME_DIR_OR_USER_PRFILE]/.local/bin' 在您的 PATH 环境变量中。使用 pipx ensurepath 进行设置。
pipx ensurepath 

2. 在 MCP 客户端的 MCP 配置 Json 文件中设置 MCP 配置脚本：

{
  "mcpServers": {
    "TitanMindMCP": {
      "command": "/[HOME_DIR_OR_USER_PRFILE]/.local/bin/titan-mind-mcp",
      "args": [
      ],
      "env": {
        "api-key": "XXXXXXXXXXXXXXXXXXXXXXXX",
        "bus-code": "XXXXXX"
      }
    }
  }
}

使用远程 Titanmind MCP 服务器配置

1. 确保系统中已安装 npx。
2. 添加 MCP 配置：

{
  "mcpServers": {
    "TitanMindMCP": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.titanmind.so/whatsapp/mcp/",
        "--header",
        "api-key:XXXXXXXXXXXXXXXXXXXXXXX",
        "--header",
        "bus-code:XXXXXX"
      ]
    }
  }
}

使用本地 Python 项目配置

1. 首先按照“设置项目”部分的说明设置项目。
2. 添加 MCP 配置：

{
  "mcpServers": {
    "TitanMindMCP": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/[PATH_TO_THE_PROJECT]",
        "python",
        "main.py"
      ],
      "env": {
        "api-key": "XXXXXXXXXXXXXXXXXXXX",
        "bus-code": "XXXXXX"
      }
    }
  }
}

自定义或开发的手动安装

从 PyPI 安装包以供使用

pip install titanmind-whatsapp-mcp

或者使用 uv：

uv pip install titanmind-whatsapp-mcp

设置项目以供开发使用

1. 克隆仓库：

git clone https://github.com/TitanmindAGI/titanmind-whatsapp-mcp
cd titanmind-whatsapp-mcp

2. 安装依赖项：

pip install -e .
# 或者
uv pip install -e .

3. 设置认证密钥：

export api-key="your-titanmind-api-key"
export bus-code="your-titanmind-business-code"

🔧 技术细节

TitanMind 的 WhatsApp 消息系统基于时间和对话状态，采用两种不同的消息模式：

自由格式消息（24 小时窗口期）

• 可用时间：仅在用户在过去 24 小时内发送过消息之后。
• 内容自由度：允许任何内容，无需预先审批。
• 使用场景：正在进行的对话和即时回复。

模板消息（超出 24 小时窗口期）

• 使用时机：用于新对话或 24 小时窗口期已过的情况。
• 内容结构：仅允许使用预先批准的结构化消息模板。
• 使用场景：初始推广和重新互动活动。

消息工作流流程

1. 检查消息窗口期状态
   • 验证接收方电话号码是否处于自由格式消息窗口期内。
   • 若满足以下条件，接收方有资格使用自由格式消息：
     • 与该电话号码的对话已经存在。
     • 接收方在过去 24 小时内发送过消息。
2. 选择消息发送方法
   • 自由格式：若在 24 小时窗口期内，直接发送。
   • 模板：若超出窗口期，注册并使用已批准的模板。
3. 模板审批流程（如有需要）
   • 提交模板以供 WhatsApp 审批。
   • 等待审批确认。
   • 模板获批后可用于批量消息发送。
4. 发送消息
   • 使用适当的方法执行消息发送。
   • 监控发送状态。
5. 验证发送结果
   • 检查对话以确认接收方是否成功收到消息。
   • 跟踪消息状态和参与度。

📚 详细文档

• 所有工具均与 Titanmind 的 WhatsApp 频道消息功能集成。
• 模板在用于批量消息发送之前需要获得批准。
• 如需更多帮助，请通过 https://www.titanmind.so/ 联系我们。

📄 许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。