Zalo Bot API 연결하기

새로운 지역의 사용자와 소통하기 위해 새로운 메시징 API를 연동하는 작업은 늘 번거롭죠. 각 플랫폼마다 다른 설정 방식과 토큰 관리 방법을 익히다 보면, 정작 중요한 서비스 로직보다 인프라 설정에 더 많은 시간을 쓰게 되곤 합니다. OpenClaw를 사용해 Zalo를 연동하면 이런 복잡한 과정을 줄일 수 있어요.

현재 Zalo 채널은 실험적(experimental) 단계이며, 1:1 DM만 지원합니다. 그룹 채팅 기능은 Zalo 문서에 따라 추후 지원될 예정이에요.

필요한 것

시작하기 전에 다음 항목들이 준비되었는지 확인해 주세요.

• Zalo Bot Token (bot.zaloplatforms.com에서 발급)
• OpenClaw CLI 또는 소스 체크아웃 환경
• Webhook 모드를 사용할 경우 HTTPS 환경

빠른 시작

5분 안에 Zalo 봇을 실행하는 가장 빠른 방법입니다.

1. Zalo 플러그인 설치 CLI에서 아래 명령어를 실행하거나, 온보딩 과정에서 Zalo를 선택하세요.

   openclaw plugins install @openclaw/zalo

2. 토큰 설정 환경 변수나 설정 파일에 토큰을 입력합니다.

   • 환경 변수: ZALO_BOT_TOKEN=your_token_here
   • 설정 파일 (config.json5):

   {
     channels: {
       zalo: {
         enabled: true,
         botToken: "12345689:abc-xyz",
         dmPolicy: "pairing",
       },
     },
   }

3. Gateway 재시작 설정을 마친 후 Gateway를 다시 시작하세요.

4. DM 액세스 승인 기본적으로 pairing 모드로 작동합니다. 봇에 처음 메시지를 보내면 페어링 코드가 발송되는데, 이를 승인해야 대화가 시작됩니다.

Setup (Fast Path)

1) Zalo Bot Platform에서 토큰 생성

Zalo Bot Platform에 로그인하여 새 봇을 만드세요. 설정이 완료되면 12345689:abc-xyz 형식의 토큰을 복사해 둡니다.

2) Webhook vs Long-polling

• Long-polling (기본값): 공인 URL이 없어도 작동합니다.
• Webhook 모드: channels.zalo.webhookUrl과 channels.zalo.webhookSecret을 설정하세요. Secret은 8~256자여야 하며, 반드시 HTTPS를 사용해야 합니다. 주의: Zalo API 정책상 polling과 webhook은 동시에 사용할 수 없습니다.

3) 주요 제한 사항

• 메시지 길이: Zalo API 제한에 따라 텍스트는 2000자 단위로 잘려서 전송됩니다.
• 미디어: 파일 크기는 기본적으로 5MB(mediaMaxMb)로 제한됩니다.
• 스트리밍: 2000자 제한으로 인해 효율성이 떨어져 기본적으로 차단되어 있습니다.

문제 해결

문제가 발생하면 다음 사항을 확인해 보세요.

봇이 응답하지 않아요:

• 토큰이 유효한지 확인하세요: openclaw channels status --probe
• 발신자가 승인되었는지(pairing 또는 allowFrom) 확인하세요.
• Gateway 로그를 확인하세요: openclaw logs --follow

Webhook이 이벤트를 받지 못해요:

• Webhook URL이 HTTPS인지 확인하세요.
• Secret 토큰이 8~256자 사이인지 확인하세요.
• getUpdates (polling) 방식이 실행 중이지 않은지 확인하세요. 두 방식은 서로 배타적입니다.

---

설정 중에 도움이 필요하신가요? AI Setup Assistant에게 물어보세요!

다음 단계

• Plugins 학습하기
• Pairing 시스템 이해하기
• 전체 Configuration 참조