Zalo는 베트남에서 가장 널리 사용되는 인스턴트 메시징 앱으로, 7천만 명 이상의 사용자를 보유하고 있으며 베트남 시장에서 필수적인 커뮤니케이션 채널입니다. OpenClaw은 플러그인 시스템을 통해 Zalo Official Account(OA) 연동을 지원하여, 베트남 사용자에게 AI 기반의 지능형 고객 서비스와 자동화 서비스를 제공할 수 있습니다.
사전 준비
설정을 시작하기 전에 다음 항목을 준비해야 합니다:
- OpenClaw 인스턴스가 배포되어 정상적으로 실행 중
- Zalo Official Account (Zalo OA 관리 플랫폼에서 등록 필요)
- Zalo OA의 App ID와 Secret Key
- 공용 인터넷에서 접근 가능한 webhook 콜백 주소
Zalo Official Account 생성
아직 Zalo OA가 없다면, 먼저 oa.zalo.me에서 등록하여 생성해야 합니다. Zalo OA는 여러 유형으로 나뉘며, AI 봇 시나리오에서는 일반 OA를 생성하면 됩니다. 등록 시 기업 정보와 연락처를 제공해야 합니다.
생성 완료 후, OA 관리 후면의 "설정" > "개발자" 페이지에서 App ID와 Secret Key를 찾을 수 있습니다. 동시에 이 페이지에서 webhook URL을 설정하고 관련 이벤트를 구독해야 합니다.
Zalo 개발자 설정 구성
Zalo OA의 개발자 설정에서 다음 작업을 완료해야 합니다:
Webhook URL 설정: 콜백 주소를 OpenClaw 인스턴스의 Zalo 엔드포인트로 설정합니다. 형식은 https://your-domain.com/webhooks/zalo입니다.
이벤트 구독: "사용자 메시지 전송" 이벤트 유형을 체크합니다. 이렇게 하면 사용자가 OA에 메시지를 보낼 때, Zalo가 메시지를 webhook 주소로 전달합니다.
OA Access Token 발급: OAuth 흐름을 통해 장기 유효한 Access Token을 발급받습니다. Zalo의 Access Token은 유효기간이 있으며, 정기적으로 Refresh Token을 사용하여 갱신해야 합니다. OpenClaw의 Zalo 플러그인에는 Token 자동 갱신 메커니즘이 내장되어 있습니다.
Zalo 플러그인 설치
OpenClaw 플러그인 시스템을 통해 설치합니다:
openclaw plugin install zalo
인터랙티브 명령으로 설정합니다:
openclaw channels login zalo
안내에 따라 App ID, Secret Key, Access Token을 입력합니다.
openclaw.json 설정
수동 설정 방식:
{
"channels": {
"zalo": {
"enabled": true,
"appId": "your-app-id",
"secretKey": "your-secret-key",
"accessToken": "your-access-token",
"refreshToken": "your-refresh-token"
}
}
}
Refresh Token을 설정하면, OpenClaw이 Access Token 만료 전에 자동으로 Refresh Token을 사용하여 새 토큰을 발급받아 서비스가 중단되지 않도록 합니다.
메시지 유형 처리
Zalo OA는 다양한 메시지 유형을 지원합니다. OpenClaw의 Zalo 플러그인은 다음 유형의 인바운드 메시지를 처리할 수 있습니다:
- 텍스트 메시지: 가장 기본적인 인터랙션 방식으로, 사용자가 텍스트를 보내면 AI가 텍스트로 응답합니다
- 이미지 메시지: 사용자가 보낸 이미지는 설명 텍스트로 변환되거나 멀티모달 AI 모델에 전달되어 처리됩니다
- 스티커와 이모지: 이러한 메시지는 보통 무시되며, AI 응답을 트리거하지 않습니다
아웃바운드 응답의 경우, 플러그인은 주로 텍스트 메시지 형식을 사용합니다. AI의 응답에 이미지 링크가 포함된 경우, 이미지 메시지 형식으로 전송하도록 설정할 수 있습니다.
Zalo OA의 메시지 규칙
Zalo는 OA의 메시지 전송에 대해 몇 가지 중요한 제한 규칙이 있습니다:
OA는 사용자가 능동적으로 메시지를 보낸 후 48시간 이내에만 답장할 수 있습니다. 48시간이 지난 후 사용자에게 능동적으로 연락해야 하는 경우, "능동 푸시" 할당량을 사용해야 합니다(월별 제한이 있음). OpenClaw은 각 사용자의 마지막 메시지 시간을 자동으로 추적하여, 48시간 창 내에서 정상적으로 응답하고 창을 초과하면 경고 로그를 기록합니다.
또한 Zalo는 OA가 보내는 메시지 내용이 플랫폼 정책을 준수하고 규정 위반 내용을 포함하지 않도록 요구합니다.
보안 설정
allowlist를 사용하여 상호작용 가능한 사용자 범위를 제어합니다:
{
"channels": {
"zalo": {
"allowlist": ["user_id_1", "user_id_2"]
}
}
}
Zalo OA 자체가 팔로우 기반 모드이므로(사용자가 먼저 OA를 팔로우해야 메시지를 보낼 수 있음), 이미 자연스러운 필터링 레이어가 있습니다. OpenClaw의 allowlist와 DM 페어링 기능을 결합하면 접근 제어를 더욱 강화할 수 있습니다.
베트남 시장 주의사항
베트남 사용자를 위한 AI 서비스를 배포할 때 다음 사항에 주의해야 합니다. 먼저, AI 모델이 베트남어를 제대로 처리할 수 있어야 하며, 성조 부호가 포함된 문자를 포함합니다. 둘째, 베트남 사용자는 스티커와 이모지팩으로 소통하는 것을 즐기므로, Bot이 이러한 비텍스트 메시지를 우아하게 처리할 수 있어야 합니다. 마지막으로, Zalo의 베트남 사용 피크 시간은 주로 오전과 저녁에 집중되므로, 이 시간대에 서비스의 안정성을 보장하는 것을 권장합니다.
다중 채널 공존
Zalo 채널은 OpenClaw의 모든 다른 채널과 동시에 실행할 수 있습니다. 비즈니스가 동시에 베트남과 국제 시장을 대상으로 한다면, Zalo로 베트남 현지 사용자를 서비스하고, 동시에 WhatsApp, Telegram 등으로 국제 사용자를 서비스할 수 있습니다. 모든 채널은 동일한 AI 모델 백엔드와 지식 베이스 설정을 공유하여, 운영 복잡도를 크게 줄여줍니다.