> ## Documentation Index
> Fetch the complete documentation index at: https://ikun.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Whatsapp 应用

> 将 Agent 作为 Whatsapp 应用托管。

Whatsapp 应用用于服务通过 WhatsApp 交互的 Agent 或团队，使用 FastAPI 服务器处理 webhook 事件和发送消息。

<Snippet file="setup-whatsapp-app.mdx" />

### 示例用法

创建一个 Agent，用 `WhatsappAPI` 包裹它，然后运行它：

```python theme={null}
from agno.agent import Agent
from agno.app.whatsapp.app import WhatsappAPI
from agno.models.openai import OpenAIChat
from agno.tools.openai import OpenAITools

image_agent = Agent(
    model=OpenAIChat(id="gpt-4o"), # 确保已设置 OPENAI_API_KEY
    tools=[OpenAITools(image_model="gpt-image-1")],
    markdown=True,
    show_tool_calls=True,
    debug_mode=True,
    add_history_to_messages=True,
)

# 默认使用异步路由 (use_async=True)
whatsapp_app = WhatsappAPI(
    agent=image_agent,
    name="Image Generation Tools",
    app_id="image_generation_tools",
    description="A tool that generates images using the OpenAI API.",
)

app = whatsapp_app.get_app()

if __name__ == "__main__":
    whatsapp_app.serve(app="image_generation_tools:app", port=8000, reload=True)
```

**运行方式：**

1. 如果使用 OpenAI 模型，请确保已设置 `OPENAI_API_KEY` 环境变量。
2. API 将会运行（例如，`http://localhost:8000`），但主要通过配置的 webhook 与 WhatsApp 进行交互。
3. API 文档（如果设置中已启用）可能位于 `http://localhost:8000/docs`。

## 核心组件

* `WhatsappAPI`: 通过 FastAPI 将 Agno Agent/Team 封装以实现 WhatsApp 集成。
* `WhatsappAPI.serve`: 使用 Uvicorn 运行 FastAPI 应用，并配置为支持 WhatsApp。

## `WhatsappAPI` 类

Agno WhatsApp 应用的主入口点。

### 初始化参数

| 参数            | 类型                         | 默认值    | 描述                                 |
| ------------- | -------------------------- | ------ | ---------------------------------- |
| `agent`       | `Optional[Agent]`          | `None` | Agno `Agent` 实例。                   |
| `team`        | `Optional[Team]`           | `None` | Agno `Team` 实例。                    |
| `settings`    | `Optional[APIAppSettings]` | `None` | API 配置。如果为 `None` 则使用默认配置。         |
| `api_app`     | `Optional[FastAPI]`        | `None` | 现有的 FastAPI 应用。如果为 `None` 则创建一个新的。 |
| `router`      | `Optional[APIRouter]`      | `None` | 现有的 APIRouter。如果为 `None` 则创建一个新的。  |
| `app_id`      | `Optional[str]`            | `None` | 应用标识符（如果未设置则自动生成）。                 |
| `name`        | `Optional[str]`            | `None` | 应用名称。                              |
| `description` | `Optional[str]`            | `None` | 应用描述。                              |

*请提供 `agent` 或 `team` 中的一个，但不要同时提供。*

### 主要方法

| 方法        | 参数                                               | 返回类型      | 描述                                                     |
| --------- | ------------------------------------------------ | --------- | ------------------------------------------------------ |
| `get_app` | `use_async: bool = True`<br />`prefix: str = ""` | `FastAPI` | 返回已配置的 FastAPI 应用。设置前缀、错误处理器，并包含 WhatsApp 路由。默认使用异步路由。 |

## 端点

端点可在 `prefix`（默认为根级别：`""`）访问。

### 1. `GET /webhook`

* **描述**: 验证 WhatsApp webhook（challenge）。
* **响应**:
  * `200 OK`: 如果令牌匹配，则返回 `hub.challenge`。
  * `403 Forbidden`: 令牌不匹配或模式无效。
  * `500 Internal Server Error`: 未设置 `WHATSAPP_VERIFY_TOKEN`。

### 2. `POST /webhook`

* **描述**: 接收传入的 WhatsApp 消息和事件。
* **处理**:
  * 验证签名（如果 `APP_ENV="production"` 且 `WHATSAPP_APP_SECRET` 已设置）。
  * 通过 `agent.arun()` 或 `team.arun()` 处理消息（文本、图像、视频、音频、文档）。
  * 通过 WhatsApp 发送回复。
* **响应**:
  * `200 OK`: `{"status": "processing"}` 或 `{"status": "ignored"}`。
  * `403 Forbidden`: 签名无效。
  * `500 Internal Server Error`: 其他处理错误。

### 参数

| 参数       | 类型                    | 默认值           | 描述                      |
| -------- | --------------------- | ------------- | ----------------------- |
| `app`    | `Union[str, FastAPI]` | `N/A`         | FastAPI 应用实例或导入字符串（必需）。 |
| `host`   | `str`                 | `"localhost"` | 绑定的主机。                  |
| `port`   | `int`                 | `7777`        | 绑定的端口。                  |
| `reload` | `bool`                | `False`       | 为开发启用自动重载。              |