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

# 管理 WhatsApp 商业账户

> 获取已连接的 WhatsApp 商业账户并了解其运营状态。

## 功能概述

WhatsApp 商业账户（WABA）包含企业使用的电话号码、模板和消息配置。使用这些 API 可以查询连接到您的 YCloud 账户的 WABA，并检查每个账户是否已准备好用于生产消息发送。

## 开始之前

* 在 YCloud 中连接或注册 WABA。
* 安全存储您的 YCloud API 密钥。
* 确认您需要所有已连接账户还是某个特定的 WABA ID。

## 工作原理

1. 列出 WABA 以获取其 ID。
2. 当您需要特定的商业、验证、支付、
   限制或消息限制状态时，获取单个 WABA。
3. 将 WABA ID 与属于它的电话号码和模板一起存储。

该 API 为只读模式。账户入驻和问题修复可能需要在 YCloud 或 Meta 业务管理平台中操作。

## 请求

### 获取 WABA 列表

`GET /whatsapp/businessAccounts`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.ycloud.com/v2/whatsapp/businessAccounts?page=1&limit=20&includeTotal=true" \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

当您需要获取处于特定审核状态的账户时，请使用 `filter.accountReviewStatus`。

### 获取单个 WABA

`GET /whatsapp/businessAccounts/{id}`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.ycloud.com/v2/whatsapp/businessAccounts/WABA_ID \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

## 响应

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "WABA_ID",
  "name": "Example Business",
  "currency": "USD",
  "accountReviewStatus": "APPROVED",
  "businessVerificationStatus": "verified",
  "paymentMethodAttached": true,
  "primaryBusinessLocation": "US",
  "whatsappBusinessManagerMessagingLimit": "TIER_2K"
}
```

| 字段 | 描述 |
| - | - |
| `id` | 电话号码、模板和 Flow API 使用的 WABA ID。 |
| `accountReviewStatus` | 当前 WhatsApp 账户审核状态。 |
| `businessVerificationStatus` | Meta 商家验证状态。 |
| `paymentMethodAttached` | 账户是否已绑定支付方式。 |
| `restrictions` | 有效的限制及其到期时间（如有）。 |
| `whatsappBusinessManagerMessagingLimit` | 当前企业级消息限制。 |

## 电话号码注册限制

列表和单个获取接口不返回 `maxPhoneNumbersPerBusiness` 或 `maxPhoneNumbersPerWaba` 的历史值。请订阅 `whatsapp.business_account.updated` 并处理 `updateEvent=BUSINESS_CAPABILITY_UPDATE`，以接收 Meta 在每次更新中包含的值。

Meta 目前在单独的更新中报告这两个字段。不要将它们视为互斥项：请独立处理每个字段，如果将来的更新中同时包含这两个字段，请一并接收。值为 `0` 是有效的。如果您需要历史记录或最新已知状态，请将这些值存储在您的系统中。

## 账户就绪状态

不要将检索成功视为每个电话号码都能发送消息的凭证。请结合所选电话号码的注册情况、模板状态、产品访问权限以及消息限制来综合检查 WABA 状态。

## 限制与故障排查

* WABA 缺失通常意味着它未连接到当前的 YCloud
  账户，或者 ID 不正确。
* 审核、验证、限制和支付状态由 Meta 控制，
  并且可能会异步变更。
* 可以缓存稳定的标识符，但在诊断入驻或
  发送问题之前，请重新获取状态。

<CardGroup cols={2}>
  <Card title="获取 WABA 列表" icon="list" href="/api-reference/whatsapp-business-accounts/list-wabas">
    查看分页、筛选条件和完整的页面 Schema。
  </Card>

  <Card title="获取单个 WABA" icon="code" href="/api-reference/whatsapp-business-accounts/retrieve-a-waba">
    查看所有账户状态和限制字段。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.