유사 사이트를 조심하세요. 한국에이아이통신(주)의 공식 사이트는 katel.kr · katcloud.kr · zerocall.kr · aicallpay.com 입니다.공식 채널 확인
KAT CloudKOEN로그인

고객이 보낸 사진 문자 받기: MESSAGE_RECEIVED imageList 저장과 답장

고객이 내 번호로 사진 문자(MMS)를 보내면 KAT Cloud는 MESSAGE_RECEIVED 웹훅의 imageList에 이미지 URL을 담아 보냅니다. URL이 만료되기 전에 내 저장소로 복사하고, chatRoomId로 같은 번호에서 답장하는 방법을 Node.js 코드로 정리했습니다.

가이드한국에이아이통신(주) KAT Cloud 팀5분 읽기
고객이 보낸 사진 문자 받기: MESSAGE_RECEIVED imageList 저장과 답장

고객이 KAT Cloud 번호로 사진 문자(MMS)를 보내면, MESSAGE_RECEIVED 웹훅의 data.imageList에 이미지 URL 배열이 담겨 옵니다. 이 URL은 일정 시간이 지나면 만료되므로, 웹훅을 받는 즉시 이미지를 내려받아 내 저장소에 복사해야 합니다. 저장이 끝나면 같은 이벤트의 chatRoomId로 POST /chat을 보내 고객이 문자를 보낸 그 번호에서 접수 답장을 보낼 수 있습니다.

사진 문자가 쓰이는 곳

전화로 설명하기 어려운 것을 고객은 사진으로 보냅니다. 파손된 택배 상자, 고장 난 제품의 오류 화면, 누수 자리, 견적을 받고 싶은 공간 같은 경우입니다. AI 상담원이 통화 중에 "사진을 이 번호로 보내 주세요"라고 안내하고 사진을 받아 접수 건에 붙이면, 담당자는 다시 전화하지 않고도 상황을 파악할 수 있습니다. 문자 수신 웹훅은 KAT Cloud에서 제공 중인 기능입니다(기능 목록).

MESSAGE_RECEIVED에서 볼 필드

필드내용쓰는 곳
chatId메시지 고유 ID(32자)중복 처리 방지, 파일 이름
chatRoomId채팅방 ID(30자)답장 보낼 때
groupId, channelId받은 그룹과 번호어느 서비스 문의인지
phoneNumber받은 내 번호번호별 분류
senderPhoneNumber보낸 고객 번호접수 건 매칭
content, subject본문, 제목(없으면 생략될 수 있음)설명 글
imageList이미지 URL 배열(문자만 오면 빈 배열)복사 대상
receivedAt받은 시각접수 시각

전체 필드는 웹훅 이벤트 문서에 있습니다. 글자만 온 문자의 자동응답은 수신 문자 자동응답 만들기에서 다루므로, 이 글은 이미지가 있는 경우에 집중합니다.

받자마자 내 저장소로 복사하기

웹훅은 10초 안에 2xx로 답해야 하므로, 이미지 내려받기는 응답과 분리하는 편이 안전합니다. 아래 예제는 서명 검증과 eventId 중복 거르기를 통과한 이벤트를 받는다고 가정하고, 영속 큐에 넣은 뒤 작업자에서 복사합니다.

JavaScript
const { S3Client, PutObjectCommand } = require('@aws-sdk/client-s3');
const s3 = new S3Client({ region: 'ap-northeast-2' });
const MAX_BYTES = 10 * 1024 * 1024;
const ALLOWED = ['image/jpeg', 'image/png', 'image/gif'];

// 큐 작업자: MESSAGE_RECEIVED data 하나를 처리
async function saveInboundImages(data) {
  const saved = [];
  for (const [i, url] of (data.imageList || []).entries()) {
    const res = await fetch(url, { signal: AbortSignal.timeout(15000) });
    if (!res.ok) throw new Error(`이미지 내려받기 실패 ${res.status}`); // 큐에서 재시도

    const type = (res.headers.get('content-type') || '').split(';')[0];
    if (!ALLOWED.includes(type)) continue;               // 이미지가 아니면 건너뜀
    const body = Buffer.from(await res.arrayBuffer());
    if (body.length > MAX_BYTES) continue;

    const key = `inbound-mms/${data.groupId}/${data.chatId}-${i}.${type.split('/')[1]}`;
    await s3.send(new PutObjectCommand({ Bucket: process.env.BUCKET, Key: key, Body: body, ContentType: type }));
    saved.push(key);
  }
  await db.inboundMessages.upsert({
    chatId: data.chatId,
    from: data.senderPhoneNumber,
    text: data.content,
    images: saved,           // 만료되는 원래 URL 대신 내 저장소 key를 남깁니다
    receivedAt: data.receivedAt,
  });
  return saved;
}
  • 원래 URL은 저장하지 않습니다. 나중에 열면 만료되어 있습니다. 내 저장소의 key만 남기고, 화면에 보여 줄 때는 내 저장소에서 짧은 수명의 서명 URL을 새로 만듭니다(용어집 Presigned URL).
  • 파일 이름은 `chatId`로 정합니다. 같은 알림이 다시 와도 같은 이름으로 덮어써 사본이 쌓이지 않습니다.
  • 실패하면 다시 시도합니다. 만료 전에 끝내야 하므로 재시도 간격은 짧게 잡습니다.

같은 번호로 접수 답장 보내기

MESSAGE_RECEIVED에는 이미 chatRoomId가 있으므로 채팅방을 새로 만들 필요 없이 POST /chat으로 답장합니다. 답장은 그 채팅방이 연결된 내 번호로 나갑니다.

JavaScript
async function replyReceived(data, savedCount) {
  const res = await fetch('https://studio-gateway.zerocall.kr/chat', {
    method: 'POST',
    headers: { 'x-api-key': process.env.KAT_API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      chatRoomId: data.chatRoomId,
      content: `사진 ${savedCount}장을 받았습니다. 담당자가 확인 후 연락드리겠습니다.`,
    }),
  });
  if (!res.ok) throw new Error(`답장 실패 ${res.status}`);
  return res.json(); // chatId로 SEND_RESULT 웹훅과 맞춰 봅니다
}

짧은 답장은 SMS로 나가며 건당 10원(5천 건까지, 부가세 별도)입니다. 답장에 이미지를 붙이려면 이미지 문자(MMS) 보내기를 참고하세요. 채팅 API는 비즈니스 요금제 그룹 또는 별도 허용된 그룹에서 쓸 수 있습니다. 요금 구간은 요금에 있습니다.

사진에 담긴 개인정보 다루기

고객 사진에는 생각보다 많은 정보가 담깁니다. 송장 사진의 이름·주소·전화번호, 신분증이나 카드를 함께 찍은 사진도 들어올 수 있습니다.

  • 저장소 접근 권한을 담당자로 좁히고, 처리가 끝난 건의 보관 기간을 정해 지웁니다.
  • 신분증·카드처럼 받지 않아야 할 사진이 오면 지우고, 다시 보내지 말라고 안내하는 절차를 둡니다.
  • 사진을 외부 이미지 분석 서비스로 보낸다면 그 경로도 개인정보 처리 흐름에 넣습니다.

원칙은 AI 전화와 개인정보에서 자세히 다룹니다.

KAT Cloud 가입하기로 번호를 받아 사진 문자 수신을 시험해 보거나, 접수 흐름 설계가 필요하다면 도입 상담을 신청하세요.

자주 묻는 질문

고객이 보낸 MMS 이미지 URL은 얼마나 유지되나요?

KAT Cloud MESSAGE_RECEIVED 웹훅의 imageList에 담긴 이미지 URL은 일정 시간이 지나면 만료됩니다. 정확한 시간에 기대지 말고, 웹훅을 받는 즉시 이미지를 내려받아 내 저장소에 복사하는 것이 안전합니다.

문자만 오고 사진이 없으면 imageList는 어떻게 오나요?

KAT Cloud의 MESSAGE_RECEIVED 웹훅에서 이미지가 없는 문자는 imageList가 빈 배열로 옵니다. 배열 길이로 사진 문자인지 판단하고, 빈 배열이면 일반 문자 처리로 넘기면 됩니다.

사진 문자에 답장하면 어느 번호로 나가나요?

KAT Cloud에서 MESSAGE_RECEIVED의 chatRoomId로 POST /chat을 보내면, 답장은 고객이 문자를 보낸 내 번호(그 채팅방이 연결된 채널 번호)로 발송됩니다. 고객은 문자를 보낸 번호에서 답장을 받게 됩니다.

  • #MMS 수신
  • #문자 수신 웹훅
  • #MESSAGE_RECEIVED
  • #이미지 저장
  • #Node.js

Get started

만든 AI에 전화번호 연결

070 번호 발급, SIP 직접 연결, 음성 AI 모델 연결, 문자·웹훅까지 API 하나로. 월 10,000원부터.