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"）和類別（MARKETING、UTILITY、AUTHENTICATION）。
• 構建消息組件，包括：
  • 正文（必填）：主要文本內容。
  • 標題（可選）：支持 TEXT、VIDEO、IMAGE 或 DOCUMENT 格式。
  • 頁腳（可選）：頁腳文本。
  • 按鈕（可選）：支持 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 配置腳本：

{
  "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 文件獲取詳細信息。