커넥터 개요

TelegramWhatsAppMessengerInstagramDiscordKakaoTalk

커넥터는 외부 메시징 플랫폼에서 이벤트를 받고 텍스트 또는 지원 오디오를 정규화한 뒤 같은 사이트 에이전트를 실행해 채널에 맞는 응답을 반환합니다. 외부 사용자별 채널 대화 기록은 대화 화면에서 확인할 수 있습니다.

새 채널 연결은 Operate 또는 Scale이 필요합니다. Launch에서도 이미 연결된 채널은 계속 동작합니다.

기능 매트릭스#

“음성 수신”은 지원되는 음성/오디오 메시지를 내려받아 전사한다는 의미입니다. “음성 발신”에는 정상 작동하는 음성 제공자와 커넥터의 음성으로 답하기 옵션이 필요합니다. 이미지나 위치처럼 지원하지 않는 첨부 파일은 에이전트 지시로 해석하지 않고 무시합니다.

연결 전 준비#

1. 대시보드에서 대상 사이트 에이전트를 테스트합니다. 공개 링크와 페이지가 작동하도록 게시를 권장하지만 초안 커넥터도 답변할 수 있습니다.
2. 설정 → AI 제공자 키에서 정상 작동하는 모델 키를 설정합니다. 음성을 테스트하기 전 음성 키도 설정하세요. 제공자 키를 참고하세요.
3. 외부 제공자에서 전용 앱, 봇, 번호 또는 채널을 만듭니다. 관련 없는 운영 통합의 자격 증명을 재사용하지 마세요.
4. 배포 환경에 외부에서 접근 가능한 공개 HTTPS 커넥터 기본 URL이 있는지 확인합니다. 안전한 개발 터널 없이는 제공자 웹훅이 localhost로 전달되지 않습니다.
5. 사이트의 커넥터 페이지를 열고 채널을 선택합니다.

저장하면 Make Agent Fast가 제공자를 호출해 입력한 자격 증명을 검증합니다. 연결됨 표시는 자격 증명 검증과 자동 프로비저닝이 완료됐다는 뜻이지만 Meta, Discord, Kakao 콘솔의 수동 단계까지 완료됐음을 보장하지는 않습니다.

자격 증명 처리#

커넥터 폼은 인증된 대시보드 또는 서버 측 Public API에서만 제공자 자격 증명을 받습니다. 비밀 값은 저장 시 암호화되고 커넥터 목록 응답에 평문으로 반환되지 않습니다. 다음 값을 비밀번호처럼 취급하세요.

• Telegram 봇 토큰
• Meta 액세스 토큰과 앱 시크릿
• Discord 봇 토큰
• Kakao REST API 키와 봇 시크릿

브라우저 JavaScript, 스크린샷, 지원 티켓, 소스 제어에 넣지 마세요. 웹훅 URL과 Meta 인증 토큰은 해당 제공자 콘솔에 복사하기 위한 설정 값이며 제공자 자격 증명을 대신하지 않습니다.

API로 연결하기#

connectors:write 범위가 있는 서버 보관 MAF API 키를 사용하세요. 채널별 credentials 객체는 쓰기 전용입니다. 응답에는 평문 비밀 값 대신 수동 제공자 설정에 필요한 웹훅 URL이 포함됩니다.

curl -X POST "https://makeagent.fast/api/v1/sites/$SITE_ID/connectors" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: connector-telegram-v1" \
  -d '{
    "channel": "telegram",
    "credentials": { "bot_token": "'$TELEGRAM_BOT_TOKEN'" },
    "config": { "reply_with_voice": false }
  }'

같은 채널을 저장하면 라우팅 토큰을 유지하면서 자격 증명/설정이 교체됩니다. 운영 통합 규칙은 API 인증, 범위 및 오류, API 레퍼런스를 참고하세요.

테스트 및 관찰#

제공자 테스트 사용자와 에이전트 지식이 필요한 실제 질문을 사용하세요. 다음을 모두 확인합니다.

• 제공자가 웹훅 엔드포인트를 승인하거나 검증합니다.
• 메시지가 에이전트에 도달하고 예상 응답을 받습니다.
• 커넥터 카드의 마지막 메시지가 변경됩니다.
• 올바른 채널로 대화에 스레드가 나타납니다.
• 공개 출시 전 제공자 검토/개발 모드 제한을 이해했습니다.
• 채널이 지원한다면 텍스트와 음성을 각각 테스트합니다.

커넥터 카드에는 마지막 제공자 또는 전달 오류가 표시됩니다. 제공자 대시보드에도 전달 로그가 있으므로 한쪽에만 요청이 보이면 타임스탬프와 이벤트 식별자를 비교하세요.

비활성화, 교체 또는 삭제#

끄기는 커넥터 레코드를 유지하면서 처리를 멈춥니다. Telegram 웹훅은 끌 때 제거되고 켤 때 다시 등록됩니다. 콘솔에서 설정한 제공자 구독은 그대로이므로 필요하면 제공자 측에서도 중지하세요. 삭제는 Make Agent Fast 커넥터를 지우고 가능한 제공자 정리를 시도하지만 외부 앱 삭제, 자격 증명 폐기, 기존 대화 기록 삭제는 수행하지 않습니다.

교체할 때는 새 제공자 토큰을 만들고 커넥터를 업데이트해 테스트한 다음 이전 토큰을 폐기합니다. 자격 증명이 노출됐다면 제공자에서 먼저 폐기하고 해당 기간을 보안 사고로 취급하세요.

일반적인 실패#

정확한 제공자 필드와 콘솔 순서는 각 채널 가이드를 이어서 확인하세요.