泰坦思维-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"）和类别（MARKETING, UTILITY, AUTHENTICATION）
• 结构化消息组件包括：
  • BODY（必需）：主要内容
  • HEADER（可选）：TEXT, VIDEO, IMAGE 或 DOCUMENT 格式
  • FOOTER（可选）：页脚文本
  • BUTTONS（可选）：QUICK_REPLY, URL 或 PHONE_NUMBER 动作

获取模板

• 获取所有已创建模板及其审批状态
• 可选按模板名称过滤

批量发送消息

• 使用已批准模板向多个电话号码发送消息
• 需要：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配置Python包脚本。

{
  "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文件