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

# WhatsApp 툴킷

> 에이전트 및 워크플로우에서 WhatsApp Business API를 통해 아웃바운드 메시지, 미디어 및 사전 승인된 템플릿을 보냅니다.

WhatsApp 툴킷은 WhatsApp Business Platform(Cloud API)에 대한 프로그래밍 방식 접근을 제공합니다. Meta Graph API를 통해 텍스트, 미디어, 사전 승인된 템플릿 및 고급 메시지 유형을 포함한 아웃바운드 메시지를 에이전트와 워크플로우가 보낼 수 있게 합니다. 인바운드 WhatsApp 메시지 수신 또는 처리는 지원되지 않습니다.

## 전제 조건

연결을 만들기 전에 Meta에서 다음이 필요합니다:

| 요구 사항                      | 가져오기                                                   |
| -------------------------- | ------------------------------------------------------ |
| WhatsApp Business 계정 (인증됨) | [Meta Business Manager](https://business.facebook.com) |
| 시스템 사용자 액세스 토큰             | Meta Business Manager → 시스템 사용자                        |
| 전화번호 ID                    | WhatsApp Manager → 전화번호                                |
| Business 계정 ID             | 선택 사항 — 고급 Graph API 호출에 필요                            |
| 승인된 메시지 템플릿                | Meta Business Manager → 계정 도구 → 메시지 템플릿                |

## 연결 만들기

WhatsApp 툴킷은 에이전트 빌더와 워크플로우 빌더 모두에서 사용할 수 있습니다.

<Tabs>
  <Tab title="에이전트 툴킷">
    1. **에이전트 빌더**에서 에이전트를 엽니다
    2. 왼쪽 사이드바의 **툴킷** 탭으로 이동합니다
    3. **WhatsApp**을 찾고 **에이전트에 추가**를 클릭합니다
    4. 툴킷 패널에서 **연결 선택** > **연결 만들기**를 클릭합니다
    5. 나타나는 팝업에서 **연결 이름**, **시스템 사용자 액세스 토큰**, **Business 계정 ID**를 입력합니다
    6. **액세스 토큰**, **Business 계정 ID**(선택 사항), 연결의 표시 **이름**을 입력합니다
    7. **저장**을 클릭합니다 — EKB가 저장하기 전에 자격 증명을 확인합니다
  </Tab>

  <Tab title="워크플로우 툴킷">
    1. **워크플로우 빌더**에서 워크플로우를 엽니다
    2. 새 단계를 추가하고 툴킷 목록에서 **WhatsApp**을 선택합니다
    3. **연결 추가**를 클릭합니다
    4. **액세스 토큰**, **전화번호 ID**, **Business 계정 ID**(선택 사항), 연결의 표시 **이름**을 입력합니다
    5. **저장**을 클릭합니다 — EKB가 저장하기 전에 자격 증명을 확인합니다
  </Tab>
</Tabs>

## 사용 가능한 도구

| 도구                  | 설명                                                           |
| ------------------- | ------------------------------------------------------------ |
| **Send Message**    | 24시간 세션 윈도우 내에서 일반 텍스트 메시지(최대 4,096자, UTF-8)를 보냅니다           |
| **Send Media**      | 공개 HTTPS URL을 통해 이미지, 동영상, 오디오 또는 문서를 선택적 캡션 또는 파일명과 함께 보냅니다 |
| **Send Template**   | 사전 승인된 템플릿 메시지를 보냅니다 — 24시간 세션 윈도우 외부의 아웃바운드 메시징에 필요         |
| **Custom API Call** | 고급 사용 사례를 위해 Meta Graph API 엔드포인트에 직접 호출을 합니다                |

## 구성 참고 사항

* **전화번호 형식**: 항상 E.164 국제 형식을 사용하세요 (예: `+1...`, `+52...`). 공백, 대시 또는 누락된 국가 코드는 전달 실패를 초래합니다 (오류 `1006`).
* **세션 윈도우**: 일반 텍스트 및 미디어 메시지는 수신자의 마지막 메시지로부터 24시간 윈도우 내에서만 보낼 수 있습니다. 해당 윈도우 외부에서는 **Send Template**을 대신 사용하세요.
* **미디어 URL**: HTTPS를 통해 공개적으로 접근 가능해야 합니다. 프라이빗, 로컬호스트 또는 만료된 URL은 다운로드 실패를 초래합니다 (오류 `1011`).
* **템플릿**: 사용 전에 Meta Business Manager에서 승인되어야 합니다. 매개변수 수와 순서가 승인된 템플릿과 정확히 일치해야 합니다.
* **속도 제한**: WhatsApp Business API는 전화번호별 및 일일 메시징 제한을 시행합니다.

## 문제 해결

| 오류 코드         | 증상              | 해결                                                |
| ------------- | --------------- | ------------------------------------------------- |
| `401` / `190` | 유효하지 않은 액세스 토큰  | Meta Business Manager에서 시스템 사용자 토큰을 재생성하고 연결 업데이트 |
| `33`          | 유효하지 않은 전화번호 ID | WhatsApp Manager에서 전화번호 ID 확인                     |
| `1006`        | 유효하지 않은 전화번호 형식 | E.164 형식 사용 — `+`와 국가 코드 포함, 공백이나 대시 없음           |
| `131005`      | 템플릿을 찾을 수 없음    | 템플릿 이름과 Meta Business Manager에 존재 여부 확인           |
| `131056`      | 템플릿 일시 중지됨      | Meta Business Manager에서 템플릿 품질 등급 확인              |
| `1011`        | 미디어 다운로드 실패     | 공개 HTTPS URL 사용하고 파일 유형과 MIME 유형이 지원되는지 확인        |