Luka's Salesforce Notes

Luka MCA Lab 구축기 | 수신 구분 설계와 국내 광고 규정 반영

Luka.dev — Tue, 20 Oct 2026 17:47:43 +0900

안녕하세요, 루카입니다. 오늘은 Luka MCA Lab의 메일을 수신 구분 두 개로 나누고, 이미 받은 동의를 구분마다 가져와 보겠습니다.

수신 구분(Communication Subscription)은 메일을 '과정 안내', '프로모션'처럼 종류로 나눠, 종류마다 수신 동의를 따로 받는 단위입니다.

홍보 메일은 기본 설정에서 고른 수신 구분에 동의한 사람에게만 나가므로, 메일마다 어느 구분으로 보낼지를 첫 발송 전에 정해 둡니다.

프로젝트 진행 지도

이런 독자에게: 국내 고객의 Marketing Cloud Next(MCN)를 구축하면서 첫 발송 전에 수신 구분과 광고 메일 규정을 정리하려는 Salesforce 관리자와 구축 컨설턴트에게 맞습니다.

Luka MCA Lab은 여러 지점이 있는 학원의 온라인 클래스를 가정한 가상 고객사이고, 신규 문의 환영, 개강 안내, 이탈 수강생 재참여, 기업 위탁교육 리드 육성의 메일 네 개를 보냅니다(PRJ-01).

준비할 것

권한: Consent 탭에서 구분을 만들고 동의를 가져오려면 Marketing Cloud Admin 또는 Marketing Cloud Manager 권한 집합이 필요합니다.
사람 데이터: 이메일이 든 가상 연락처는 PRJ-04에서 넣었고, Data Cloud로는 PRJ-05에서 가져왔습니다.
가져오기 절차: Consent Imports의 단계별 화면과 반영 시간은 007에서 다뤘습니다.

완료 확인: Subscriptions 목록에 새 구분 두 개가 있고, Data Cloud 조회에서 구분별 OPT_IN 건수가 가져온 행 수와 같으면 끝입니다.

규정 대응

광고 메일 규정 가운데 수신 구분이 맡는 것은 사전 동의와 수신 거부이고, 밤 시간 별도 동의는 시행령이 이메일을 예외로 두므로 따로 받지 않습니다.

목적: 영리 목적의 광고를 담은 메일(광고성 정보)은 정보통신망법 제50조를 따라야 합니다. 이 조문의 의무를 MCN의 어느 기능에서 지킬지 먼저 정합니다.

확인한 사실: 제50조와 시행령이 이메일 광고에 요구하는 주요 의무는 다섯 가지입니다.

사전 동의: 받는 사람의 명시적인 사전 동의를 받아야 보낼 수 있습니다.
수신 거부: 수신을 거부하거나 동의를 철회한 사람에게는 보내지 않습니다.
야간 별도 동의: 오후 9시부터 다음 날 오전 8시까지 보내려면 별도의 동의가 필요합니다. 다만 시행령이 이메일(전자우편)을 이 의무에서 뺍니다.
표시 의무: 제목 앞의 "(광고)", 전송자 정보, 수신 거부 방법을 메일에 적습니다.
통지와 2년 확인: 동의·수신 거부·철회를 처리한 결과를 14일 안에 알리고, 동의한 날부터 2년마다 동의 여부를 확인합니다.

MCN은 기본 설정에서 홍보(Promotional) 메일을 고른 수신 구분에 동의한 사람에게만 보내고, Unsubscribe 링크로 해지한 사람은 그 구분의 메일에서 뺍니다.

막힌 것: 법에는 거래관계 예외도 있어, 거래가 끝난 뒤 6개월 안에 같은 종류의 상품을 알리는 메일은 동의 없이 보낼 수 있습니다. 최근 수강생에게 해당할 수 있지만, MCN은 홍보 메일에 동의 기록을 요구합니다. 동의하지 않은 사람을 Opt In으로 넣을 수는 없으므로 이 예외는 기능으로 쓸 수 없습니다.

고른 것: 모두에게 동의를 받고, 수신 구분은 사전 동의와 수신 거부를 맡습니다. 표시 의무는 메일 콘텐츠에서, 통지와 2년 확인은 운영 단계에서 처리합니다. 야간 동의를 받는 구분이나 양식 칸은 만들지 않습니다.

판단 카드: 규정 대응

만 14세 미만 아동의 개인정보에 법정대리인 동의를 받는 일은 수강 등록 업무이고 광고 규정이 아닙니다. 이 프로젝트는 14세 미만 수강생에게 메일을 보내지 않으므로(PRJ-03) 수신 구분에서 다루지 않습니다.

사전 동의: 정보통신망법 제50조 제1항 · 수신 거부: 제2항
야간 별도 동의: 제3항, 시행령 제61조 제2항(전자우편 예외)
표시 의무: 제4항, 시행령 제61조 제3항과 별표 6
통지와 2년 확인: 제7항·제8항, 시행령 제62조의2·제62조의3
거래관계 예외: 제50조 제1항 단서, 시행령 제61조 제1항(거래 종료 뒤 6개월)
아동 개인정보: 개인정보 보호법 제22조의2 제1항

정보통신망법과 시행령은 2026년 10월 2일, 개인정보 보호법은 2026년 9월 11일부터 시행된 조문을 기준으로 했습니다. 어떤 메일이 광고성 정보인지는 메일 내용으로 판단하므로, 실제 구축에서는 고객사의 법무 검토를 함께 받습니다.

수신 구분

Unsubscribe 링크는 그 메일의 수신 구분 하나만 해지하므로, 개강 소식과 재참여 메일을 '과정 안내'와 '프로모션' 두 구분으로 나눕니다.

목적: 고객사는 "개강 소식은 계속 받고, 재참여 권유는 끊을 수 있게" 해 달라고 했습니다. 수신자가 메일 종류마다 받을지를 고를 수 있어야 합니다.

확인한 사실: 도움말에 따르면 메일 꼬리말의 Unsubscribe 링크를 누르면, 그 메일을 보낸 수신 구분 하나에서만 바로 해지됩니다. 지금 org에는 기본으로 만들어진 Marketing 구분 하나뿐입니다.

막힌 것: 구분이 하나면 재참여 메일에서 해지한 사람에게 개강 소식도 가지 않습니다. 메일마다 구분을 만들면 수신자가 선호 페이지(Preference Page)에서 고를 항목이 넷이 되고, 문의 양식에서 받을 동의 칸도 넷으로 늘어납니다.

고른 것: 구분을 두 개로 나눴습니다.

과정 안내: 신규 문의 환영, 개강 안내, 기업 위탁교육 자료
프로모션: 이탈 수강생 재참여

판단 카드: 수신 구분 개수

이 프로젝트는 네 메일을 모두 광고성 정보로 보고, 이메일을 만들 때 Message Purpose를 Promotional로 둡니다. 수강 신청 확인처럼 거래에 따른 메일은 이번 범위에 없습니다.

구분 만들기

수신 구분은 Consent 탭의 Subscriptions에서 이름과 채널만 넣어 만들고, 이름은 나중에 고칠 수 있지만 지우면 그 구분의 동의도 함께 지워집니다.

1. Subscriptions에서 New Subscription을 누릅니다

Marketing 앱의 탭 막대에서 Consent를 열고(탭 막대에 없으면 More 메뉴 안에 있습니다), 왼쪽 메뉴의 Subscriptions를 고릅니다. 목록에는 기본 Marketing 구분 한 줄이 있습니다.

기본 Marketing 하나인 Subscriptions 목록

화면 위의 노란 안내 띠는 SMS 동의를 가져올 때 필요한 Sender Code 안내이며, 이메일 구분과는 상관없습니다.

2. 이름과 채널을 넣고 저장합니다

Subscription Name에 이름을 넣고 Channels에서 Email을 고른 뒤 Save를 누릅니다. 같은 방법으로 프로모션 구분도 만듭니다.

이름과 채널

구분 이름은 수신자가 보는 선호 페이지에 그대로 나오므로, 실제 구축에서는 수신자가 알아볼 이름으로 짓습니다. 이 실습에서는 시험으로 만든 구분을 구별하려고 이름 앞에 LUKA_를 붙였습니다.

구분 세 개가 된 목록

행 끝 메뉴의 Edit 창에서는 이름 칸을 고칠 수 있고, 칸의 도움말은 이름을 바꾸면 선호 페이지의 이름도 함께 바뀐다고 안내합니다. 기본 Marketing 구분은 이 프로젝트의 메일에서 고르지 않고 그대로 둡니다.

주의

Delete로 구분을 지우면 그 구분에 모인 동의 데이터도 함께 지워집니다. 쓰지 않게 된 구분도 지우지 않고 남겨 둡니다.

새 구분은 선호 페이지에 저절로 들어가지 않습니다. 왼쪽 메뉴 Preference Pages에서 Email Preference Page의 편집 화면을 열면 Marketing 하나만 있습니다. 확인만 하고 저장하지 않은 채 Back으로 나옵니다.

기본 이메일 선호 페이지의 편집 화면

동의 가져오기

구분마다 동의한 사람이 다르므로 Consent Imports로 구분마다 한 번씩 가져오고, 동의 날짜에는 실제로 동의를 받은 날을 넣습니다.

이번에 가져오는 사람은 이미 등록한 학부모 8명과 14세 이상 수강생 4명입니다. 막 문의한 사람의 동의는 문의 양식에서 받으므로 여기서 가져오지 않습니다.

과정 안내: 12명 모두 동의했습니다.
프로모션: 학부모 4명과 수강생 4명, 모두 8명이 동의했습니다(가상 데이터의 가정입니다).

CSV는 구분마다 하나씩 만듭니다. 머리글과 날짜 형식은 007과 같고, 두 파일은 행 수만 다릅니다.

EmailAddress,ConsentDate
luka.parent01@example.com,2026-09-01
luka.parent02@example.com,2026-09-01

ConsentDate에는 가져온 날이 아니라 동의를 받은 날을 넣습니다. 2년마다 동의를 확인할 때 이 날짜를 기준으로 삼기 때문입니다. 도움말에 따르면 이미 있는 동의 날짜보다 이전 날짜는 무시되므로, 나중에 더 이른 날짜로 고칠 수 없습니다.

Consent Imports에서 Import를 누릅니다. Channel은 Email, Communication Subscription은 과정 안내 구분을 고르고 Opt In 카드를 누릅니다. 이후 파일을 올리고 가져오는 순서는 007과 같습니다. 프로모션 구분도 같은 방법으로 8행 파일을 가져옵니다.

과정 안내 구분을 고른 첫 단계

두 번 가져온 결과

결과 확인

Query Editor에서 구분별 OPT_IN 건수가 가져온 행 수와 같으면, 동의가 구분마다 들어간 것입니다.

Data Cloud의 Query Editor에서 동의 데이터를 구분 이름별로 셉니다. 이번 시험에서는 두 번 모두 가져온 뒤 2~4분 사이에 조회에 보였습니다.

동의 레코드에는 구분 이름이 없으므로, 구분 채널 DMO를 거쳐 구분 DMO에서 이름을 가져옵니다. consents는 구분과 동의 상태별 동의 레코드 수이고, WHERE 줄의 이름 조건은 자기 구분 이름으로 바꿉니다.

SELECT s.ssot__Name__c,
  c.ssot__ConsentStatus__c,
  COUNT(*) AS consents
FROM
  ssot__CommunicationSubscriptionConsent__dlm c
JOIN
  ssot__CommunicationSubscriptionChannelType__dlm t
  ON c.ssot__CommunicationSubscriptionChannelTypeId__c
   = t.ssot__Id__c
JOIN ssot__CommunicationSubscription__dlm s
  ON t.ssot__CommunicationSubscriptionId__c
   = s.ssot__Id__c
WHERE s.ssot__Name__c LIKE 'LUKA\_%'
GROUP BY s.ssot__Name__c,
  c.ssot__ConsentStatus__c

구분별 동의 건수

과정 안내는 12건, 프로모션은 8건으로 가져온 행 수와 같았습니다. 같은 조회에 동의 날짜 열을 더해 보면 CSV에 넣은 2026-09-01이 그대로 남아 있습니다.

이후 여정에서는 메일을 보낼 때 이 두 구분 가운데 하나를 고릅니다. 선호 페이지와 "(광고)" 표시는 별도 글에서 다룰 예정입니다.

그림으로 쉽게 보는 요약

참고 문서

Luka MCA Lab 구축기 | 동일인 판정 매치 규칙 고르기와 실행

Luka.dev — Tue, 20 Oct 2026 16:32:06 +0900

안녕하세요, 루카입니다. 오늘은 Luka MCA Lab 데이터에 맞는 동일인 판정 매치 규칙을 고르고 실행해 보겠습니다.

동일인 판정(Identity Resolution)은 여러 원천에서 들어온 같은 사람의 레코드를 매치 규칙에 따라 통합 개인(Unified Individual) 하나로 묶는 기능입니다.

규칙이 느슨하면 다른 사람이 한 사람으로 묶이고, 엄격하면 같은 사람이 둘로 남으므로 같은 이메일을 누가 함께 쓰는지 먼저 보고 규칙을 정합니다.

프로젝트 진행 지도

이런 독자에게: 세그먼트를 만들기 전에 동일인 판정을 처음 실행하려는 Salesforce 관리자와 구축 컨설턴트에게 맞습니다.

준비할 것

규칙 집합: Data Cloud가 켜진 Marketing Cloud Next org에 Individual용 규칙 집합(Ruleset)이 하나 있어야 합니다. 이 org에는 이미 만들어진 규칙 집합이 있고, 만드는 법은 003에 있습니다.
구조: 규칙 집합, Individual, 통합 개인의 관계는 004에서 다뤘습니다.
사람 데이터: 가상 데이터는 PRJ-04에서 넣었고, 14세 미만 수강생에게 이메일을 넣지 않는 원칙은 PRJ-03에서 정했습니다.
크레딧: 규칙 집합을 실행할 때마다 Data Cloud 크레딧을 씁니다.

완료 확인: 아래 두 가지가 보이면 끝입니다.

규칙 집합의 Last Job Status가 Succeeded입니다.
Query Editor에서 LUKA Individual 35건이 통합 개인 35명으로 나옵니다.

판정 대상

같은 이메일을 쓰는 Individual에는 학부모 이메일로 들어온 문의 4건뿐 아니라, 시연 데이터에서 공용 메일 주소 하나를 함께 쓰는 11건도 있었습니다.

규칙을 고르기 전에, 같은 이메일을 쓰는 Individual을 SQL로 찾습니다. Individual에는 이메일 필드가 없으므로, 이메일을 담은 Contact Point Email과 조인해 이메일별로 셉니다.

이메일은 소문자로 바꾸고 앞뒤 공백을 없앤 값으로 묶고, 빈 값은 뺍니다. individual_records는 그 이메일을 쓰는 Individual 레코드 수, names는 그중 서로 다른 이름의 수입니다. 두 값이 같으면 그 이메일을 쓰는 레코드의 이름이 모두 다릅니다.

SELECT
  LOWER(TRIM(e.ssot__EmailAddress__c))
    AS email,
  COUNT(DISTINCT i.ssot__Id__c)
    AS individual_records,
  COUNT(DISTINCT CONCAT(
    i.ssot__FirstName__c, ' ',
    i.ssot__LastName__c)) AS names
FROM ssot__Individual__dlm i
JOIN ssot__ContactPointEmail__dlm e
  ON e.ssot__PartyId__c = i.ssot__Id__c
WHERE LENGTH(e.ssot__EmailAddress__c) > 0
GROUP BY LOWER(TRIM(e.ssot__EmailAddress__c))
HAVING COUNT(DISTINCT i.ssot__Id__c) > 1

이 org의 Individual 541건 가운데 35건은 이 프로젝트의 가상 데이터이고, 506건은 SDO(시연용 체험 org)에 처음부터 있던 시연 데이터입니다. 같은 이메일을 쓰는 묶음은 아래와 같고, 묶음마다 이름이 모두 달랐습니다.

묶음	이메일 수	이메일마다 Individual
가상 데이터의 학부모 이메일	4	2건
시연 데이터의 공용 메일 주소	1	11건
시연 데이터의 다른 이메일	2	2건

가상 데이터의 4개는 학부모 Contact와 같은 이메일로 들어온 문의 Prospect입니다. 이미 등록한 학부모가 형제의 다른 과정을 문의하면서 이름 칸에 다른 이름을 적은 경우로 가정했습니다.

수강생 중 14세 이상 4명은 자기 이메일을 쓰고 14세 미만 8명은 이메일이 비어 있어, 같은 이메일을 쓰는 묶음에 들지 않습니다.

이메일	학부모(Contact)	문의(Prospect)
luka.parent01@example.com	민준	서윤
luka.parent02@example.com	서연	도윤
luka.parent03@example.com	지우	지민
luka.parent04@example.com	하준	예준

이 규칙 집합에는 매치 규칙이 네 개 있습니다. 가상 데이터에는 전화, 주소, MC Subscriber Key 값이 없으므로, 가상 데이터를 묶을 수 있는 규칙은 이메일을 보는 Fuzzy Name and Normalized Email 하나뿐입니다. 이 규칙은 이름, 성, 이메일 세 조건이 모두 맞아야 같은 사람으로 봅니다.

Fuzzy Name and Normalized Email의 조건 세 개

그래서 이름이 다른 문의 4건은 이 규칙으로 학부모와 묶이지 않습니다. 가상 데이터는 성에도 레코드 표지(LUKA_학부모01, LUKA_문의01)를 넣었으므로, 성 조건도 맞지 않습니다. 실제 데이터에서는 학부모가 같은 이름과 성으로 다시 문의하면 이 규칙으로 묶일 수 있습니다.

규칙 고르기

이메일만 보는 규칙은 문의 4건을 학부모와 묶지만 공용 메일 주소를 쓰는 11건도 한 사람으로 만들므로, 이 org에서는 기본 매치 규칙을 그대로 둡니다.

목적: 같은 학부모의 문의 레코드와 등록 레코드를 한 사람으로 세고 싶습니다. 그러려면 이메일만 같아도 같은 사람으로 보는 규칙이 필요합니다.

확인한 사실: 이메일만 보는 시험 규칙을 더해 한 번 실행하고, 실제로 무엇이 묶이는지 확인했습니다. 따라 할 단계는 다음 절의 실행입니다.

주의

시험 규칙으로 실행해도 데이터 공간 전체의 통합 개인이 바뀌고 크레딧을 씁니다. 운영 중인 org에서는 게시된 세그먼트가 없을 때 시험하고, 끝나면 규칙을 지운 뒤 다시 실행합니다.

기본 규칙 목록에는 이메일 하나만 보는 규칙이 없어서, Match Rules 카드의 Edit에서 Custom Rule을 골라 이메일 조건 하나만 둔 규칙을 만들었습니다.

이메일 조건 하나만 둔 시험 규칙

규칙 집합 상세에서 Match Rules 카드의 Edit를 누르고, 안내 창 Match Rule Instructions에서 Next를 누릅니다.
Add Match Rules 창에서 Add Match Rule을 누르고, 목록에서 Custom Rule을 골라 Next를 누릅니다.
Configure Match Criteria 창에서 Data Model Object는 Contact Point Email, Field는 Email Address, Match Method는 Exact Normalized를 고릅니다. 조건을 고르면 이름 칸이 Custom Rule로 돌아가므로, 이름은 조건을 다 고른 뒤 넣습니다.
Next를 누르고 Add Match Rules 창에서 Save를 누릅니다. 저장해도 실행은 시작되지 않습니다.
지울 때는 같은 Add Match Rules 창에서 그 규칙 줄의 휴지통 단추를 누르고 Save를 누릅니다.

조건이 하나뿐인 규칙에는 삼각형 경고가 붙고, 마우스를 올리면 "To improve unified profiles, add more match rule criteria."가 보입니다. 저장을 막는 경고는 아닙니다.

시험 규칙을 더해 실행한 결과는 아래와 같습니다. 화면의 Total Unified Profiles는 org 전체 Individual 541건에서 나온 통합 개인 수입니다.

시험 규칙으로 실행한 결과

Individual 541건이 통합 개인 525명이 되었습니다. 통합 개인이 Individual 건수보다 16명 적은 이유는 아래와 같습니다.

문의 4건: 각각 학부모와 묶여 4명이 줄었습니다. LUKA Individual 35건은 통합 개인 31명이 되었습니다.
공용 메일 주소 11건: 이름이 서로 다른 11건이 통합 개인 1명이 되어 10명이 줄었습니다.
시연 데이터의 다른 이메일 2개: 이메일마다 2건이 1명이 되어 2명이 줄었습니다.

막힌 것: 필터가 없는 이 규칙 집합에서는 매치 규칙이 데이터 공간의 모든 Individual에 적용되므로, 시험 실행에서도 시연 데이터가 함께 묶였습니다.

이메일만 보는 규칙: 공용 메일 주소를 함께 쓰는 서로 다른 사람도 묶습니다. Luka MCA Lab도 기업 위탁교육 담당자를 리드로 받으므로, 회사 공용 메일 주소로 들어오는 담당자가 생길 수 있습니다.
성과 이메일을 보는 규칙: 실제 가족은 성과 이메일이 같을 수 있어, 학부모 이메일로 들어온 가족이 함께 묶일 수 있습니다. 이 규칙은 시험하지 않았습니다.

고른 것: 기본 매치 규칙을 그대로 두었습니다. 문의 4건은 학부모와 다른 통합 개인으로 남으므로, 이 중복은 CRM에서 문의를 받을 때 기존 학부모와 잇는 방법으로 막기로 했습니다.

판단 카드: 매치 규칙

실행

기본 규칙으로 실행하면 묶이는 레코드가 없어, 이 org의 Individual 541건이 그대로 통합 개인 541명이 됩니다.

1. Match Rules 카드를 확인합니다

Marketing 앱의 Identity Resolution 탭에서 규칙 집합(Individual Identity Resolution)을 엽니다. Match Rules 카드에 처음부터 있던 매치 규칙 네 개만 있는지 봅니다.

2. Run Ruleset을 누릅니다

머리 줄의 Run Ruleset을 누릅니다. 확인 창 없이 실행이 시작되고, 화면을 새로 고치면 Last Job Status가 In Progress로 보입니다.

실행이 끝난 뒤 화면을 새로 고치면 Last Job Status가 Succeeded가 됩니다. 이번 실행은 약 6분 걸렸습니다.

기본 규칙으로 실행한 결과

실행 중에는 Resolution Summary가 앞선 실행의 수치를 보이므로, Succeeded가 된 뒤에 수치를 읽습니다.

시험 실행에서 묶였던 레코드는 이 실행에서 모두 다시 나뉘었습니다.

두 실행의 통합 개인 수

결과 확인

Query Editor에서 LUKA Individual 35건이 통합 개인 35명으로 나오면, 가상 데이터끼리 묶인 레코드 없이 실행이 끝난 것입니다.

Data Cloud의 Query Editor에서 Individual과 Unified Link Individual을 조인해 셉니다. Unified Link Individual은 원천 Individual과 통합 개인을 잇는 DMO입니다.

individual_records는 통합 개인에 이어진 Individual 레코드 수, unified_people은 그 레코드가 이어진 통합 개인 수입니다. 두 값이 같으면 가상 데이터끼리 묶인 레코드가 없는 것입니다. individual_records가 가상 데이터 건수(35)보다 적으면 실행에서 빠진 레코드가 있는 것입니다.

SELECT
  COUNT(i.ssot__Id__c)
    AS individual_records,
  COUNT(DISTINCT l.UnifiedRecordId__c)
    AS unified_people
FROM ssot__Individual__dlm i
JOIN IndividualIdentityLink__dlm l
  ON l.SourceRecordId__c = i.ssot__Id__c
WHERE i.ssot__LastName__c LIKE 'LUKA%'

LUKA Individual과 통합 개인 수

문의 4건을 CRM에서 기존 학부모와 잇는 방법은 별도 글에서 다룰 예정입니다.

그림으로 쉽게 보는 요약

참고 문서

Luka MCA Lab 구축기 | 커스텀 오브젝트를 Data Cloud로 가져와 DMO에 매핑하는법

Luka.dev — Tue, 20 Oct 2026 10:42:32 +0900

안녕하세요, 루카입니다. 오늘은 Luka MCA Lab의 수강 데이터를 Data Cloud로 가져와 사람 데이터와 이어 보겠습니다.

데이터 스트림(Data Stream)은 Salesforce CRM 같은 원천의 레코드를 Data Cloud로 가져오고, 원천이 바뀌면 그 변경도 이어서 반영하는 기능입니다.

세그먼트는 Data Cloud의 데이터 모델 오브젝트(DMO)를 조건으로 읽으므로, CRM에 만든 커스텀 오브젝트도 가져와 DMO에 매핑해야 합니다.

프로젝트 진행 지도

이런 독자에게: CRM의 커스텀 오브젝트를 세그먼트 조건으로 쓰려는 Salesforce 관리자와 구축 컨설턴트에게 맞습니다.

준비할 것

Data Cloud와 권한: Data Cloud가 켜진 Marketing Cloud Next org와 Data Cloud Architect 권한 집합이 필요합니다.
커넥터 권한: Data Cloud Salesforce Connector 권한 집합에 View All Data가 켜져 있으면 그대로 둡니다. 꺼져 있으면 가져올 오브젝트와 그 오브젝트가 참조하는 Campaign, Contact에 Read와 View All Records를 줍니다.
사람 데이터: Prospect와 Contact가 데이터 키트의 스트림으로 들어와 Individual에 매핑되어 있어야 합니다. 이 org에서는 Marketing Cloud Next를 켤 때 이미 그렇게 만들어졌습니다.
앞 글: 오브젝트와 가상 데이터는 PRJ-04에서, 데이터 모델은 PRJ-03에서 정했습니다.
org 별칭: 명령의 org 별칭은 my-org입니다.

완료 확인: 아래 세 가지가 보이면 끝입니다.

스트림 목록의 Total Records가 6, 20, 14입니다.
DMO 관계 6개가 모두 Active입니다.
세그먼트 빌더의 Individual에서 관심 과정을 거쳐 과정의 속성까지 열립니다.

가져올 범위

이 org의 데이터 키트는 표준 오브젝트만 가져오므로, 과정, 관심 과정, 수강 신청 세 오브젝트의 데이터 스트림은 직접 만듭니다.

데이터 키트는 Marketing Cloud Next를 켤 때 표준 오브젝트의 스트림과 매핑을 한꺼번에 만들어 준 묶음입니다. 키트가 만든 Prospect, Contact의 스트림은 그대로 둡니다.

가져온 필드를 DMO의 필드에 대응시키는 일을 매핑이라고 합니다.

이 글에서 문의자는 Prospect이고, 수강생과 학부모는 Contact입니다. 세 오브젝트에 담긴 데이터는 아래와 같습니다.

오브젝트	레코드	담긴 핵심 필드
과정	6	과정 코드, 개강일, 지점, 캠페인
관심 과정	20	과정, Contact, 고유 키
수강 신청	14	과정, 수강생, 연락 대상, 마지막 수강일

수강 신청은 수강생과 연락 대상(14세 미만이면 학부모)을 Contact 조회 필드로 가리킵니다. 관심 과정은 아직 Contact가 없는 문의자도 가리켜야 하므로, 문의자의 Prospect ID를 담는 텍스트 필드 사람 ID를 더합니다.

스트림을 만든 뒤에 필드를 더하면 스트림과 매핑을 다시 손봐야 하므로, 사람 ID 필드부터 더합니다. 가져올 오브젝트가 Contact 조회 필드로만 사람을 가리킨다면 이 단계는 건너뜁니다.

1. 사람 ID 필드를 더하고 채웁니다

필드를 소스에 더하고, 권한 집합 LUKA_MCA_Lab_Data에 이 필드의 읽기와 쓰기 권한을 더해 함께 배포합니다.

fields/LUKA_PersonId__c.field-meta.xml

<?xml version="1.0" encoding="UTF-8"?>
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>LUKA_PersonId__c</fullName>
    <label>사람 ID</label>
    <externalId>false</externalId>
    <length>18</length>
    <required>false</required>
    <type>Text</type>
    <unique>false</unique>
</CustomField>

권한 집합의 PermissionSet 안에 아래 항목을 더합니다.

<fieldPermissions>
    <editable>true</editable>
    <field>LUKA_CourseInterest__c.LUKA_PersonId__c</field>
    <readable>true</readable>
</fieldPermissions>

이어서 기존 관심 과정 20건의 사람 ID를 채웁니다. 스크립트는 고유 키의 이메일로 Prospect를 찾아 그 ID를 씁니다. 맞는 Prospect가 없거나 둘 이상이면 아무것도 쓰지 않고 멈춥니다.

먼저 옵션 없이 실행해 계획만 확인합니다. 찾은 것이 20건이면 --apply를 붙여 다시 실행합니다.

python fill_person_id.py --org my-org
python fill_person_id.py --org my-org \
  --apply

마지막 줄에는 사람 ID가 채워진 관심 과정 수가 나옵니다. 이 값이 20이면 끝입니다.

import argparse
import json
import shutil
import subprocess
import sys

parser = argparse.ArgumentParser()
parser.add_argument(
    '--org', default='my-org',
    help='sf CLI 의 org 별칭')
parser.add_argument(
    '--name-prefix',
    default='LUKA\\_문의',
    help="Prospect LastName LIKE "
         "에 쓸 앞부분(밑줄은 "
         "\\_ 로 이스케이프)")
parser.add_argument(
    '--apply', action='store_true',
    help='실제로 쓴다. '
         '없으면 계획만 찍는다')
args = parser.parse_args()

SF = shutil.which('sf')


def sf(*argv):
    out = subprocess.run(
        [SF, *argv, '-o', args.org,
         '--json',
         '--api-version', '67.0'],
        capture_output=True,
        text=True, encoding='utf-8')
    text = out.stdout
    # CLI 가 JSON 앞에 안내 줄을
    # 붙일 때가 있다
    data = json.loads(
        text[text.index('{'):])
    if data.get('status') != 0:
        sys.exit(
            'sf 오류: '
            + str(
                data.get('message')))
    return data['result']


def query(soql):
    return sf(
        'data', 'query', '-q', soql
    )['records']


interests = query(
    'SELECT Id, LUKA_UniqueKey__c '
    'FROM LUKA_CourseInterest__c '
    'ORDER BY LUKA_UniqueKey__c')
prospects = query(
    "SELECT Id, Email FROM Prospect "
    "WHERE LastName LIKE "
    f"'{args.name_prefix}%'")

by_email = {}
for p in prospects:
    by_email.setdefault(
        (p['Email'] or '').lower(),
        []).append(p['Id'])

plan, problems = [], []
for r in interests:
    key = r['LUKA_UniqueKey__c'] or ''
    email = key.split('|')[0].lower()
    ids = by_email.get(email, [])
    if len(ids) == 1:
        plan.append((r['Id'], ids[0]))
    else:
        problems.append(
            (key, len(ids)))

print(
    f'관심 과정 {len(interests)}건, '
    f'Prospect {len(prospects)}건, '
    f'찾은 것 {len(plan)}건')
if problems:
    for key, n in problems:
        print(
            f'멈춤: 고유 키 {key} 의 '
            '이메일과 맞는 '
            f'Prospect 가 {n}건')
    sys.exit(1)

if not args.apply:
    print('계획만 찍었다. '
          '쓰려면 --apply 를 준다')
    sys.exit(0)

for interest_id, prospect_id in plan:
    sf('data', 'update', 'record',
       '-s', 'LUKA_CourseInterest__c',
       '-i', interest_id,
       '-v',
       'LUKA_PersonId__c='
       f'{prospect_id}')

print(
    '채운 뒤 사람 ID 가 있는 '
    '관심 과정:',
    sf('data', 'query', '-q',
       'SELECT COUNT() '
       'FROM LUKA_CourseInterest__c '
       'WHERE LUKA_PersonId__c '
       '!= null')['totalSize'])

데이터 스트림

세 오브젝트는 계속 고쳐지는 레코드이므로, 데이터 스트림의 카테고리를 Other로 두고 가져옵니다.

스트림은 오브젝트마다 하나씩 만들어집니다. 카테고리(Category)는 스트림이 가져온 데이터를 Profile, Engagement, Other 가운데 어느 종류로 다룰지 정하는 값입니다.

1. 원천으로 Salesforce CRM을 고릅니다

Data Cloud 앱의 Data Streams 탭에서 New를 누르고, Salesforce CRM 카드를 골라 Next를 누릅니다.

원천으로 고른 Salesforce CRM

2. 가져올 오브젝트를 고릅니다

Salesforce Org 단계에서 기본으로 열리는 View Bundles 대신 View Objects를 누르고 검색 칸에 LUKA를 넣습니다. Is Custom Object 열에 표시가 있는 과정, 관심 과정, 수강 신청 세 줄을 체크하고 Next를 누릅니다.

Owner Rule로 시작하는 세 줄은 소유자 기준 공유 규칙을 담는 항목이라 고르지 않습니다.

스트림 이름은 기본값을 그대로 씁니다. 기본값은 LUKA_Course__c_Home처럼 오브젝트 API 이름 뒤에 _Home이 붙습니다.

체크한 커스텀 오브젝트 3개

목록 위 안내줄은 앞으로 만들 필드와 오브젝트도 가져오도록, 커넥터 권한 집합에 View All Fields (Global)를 주라고 권합니다. 이 글의 세 오브젝트는 이미 목록에 보이므로 그대로 진행합니다.

3. 카테고리를 정하고 필드를 확인합니다

다음 화면에서 오브젝트마다 카테고리를 고릅니다. 화면에 "After saving the data stream, you can't change the category."라는 안내가 있으므로, 저장하기 전에 정합니다. 이 글은 아래 판단 카드의 기준으로 세 오브젝트 모두 Other를 골랐습니다.

판단 카드: 카테고리

카테고리는 처음에 비어 있으므로, 왼쪽 목록에서 세 오브젝트를 하나씩 열어 아래 두 가지를 합니다. Primary Key는 Record ID로 정해져 있어 바꿀 수 없습니다.

Object Category에서 Other를 고릅니다.
필드는 모두 체크된 그대로 둡니다. 관심 과정에서는 사람 ID도 체크되어 있는지 확인합니다.

Object Category를 Other로 고른 화면

4. Deploy하고 목록에서 건수를 확인합니다

Next를 누르면 Data Space와 카테고리를 확인하는 화면이 나옵니다. Data Space가 default이고 Category 열의 세 줄이 모두 Other면 Deploy를 누릅니다.

Deploy하면 스트림마다 가져온 원본 테이블(Data Lake Object, DLO)이 만들어집니다. 이어서 Data Streams 목록에서 LUKA로 검색합니다. Last Run Status가 Success이고 Total Records가 6, 20, 14면 가져오기가 끝난 것입니다.

이번 시험에서 목록은 약 5분 뒤에 Success가 되었지만, SQL로 DLO를 조회하면 약 10분 뒤부터 보였습니다.

가져오기가 끝난 스트림 목록

DMO 매핑

세 오브젝트에 맞는 표준 DMO를 찾지 못해, 모두 커스텀 DMO를 만들어 매핑합니다.

수강 신청의 후보로 본 표준 DMO는 주문을 담는 Sales Order였지만, 과정을 둘 필드가 없었습니다. 과정과 관심 과정도 맞는 표준 DMO를 찾지 못했습니다.

판단 카드: 어느 DMO에 매핑할지

1. 커스텀 DMO를 만듭니다

수강 신청 스트림의 상세 화면에서 오른쪽 Data Mapping 구역의 Start를 누릅니다. 매핑 화면에서 Select Objects를 열고 Custom Data Model 탭의 New Custom Object를 누릅니다.

Object Label에 LUKA_Enrollment를 쓰면 Object API Name이 따라 바뀝니다. Object Category는 스트림과 같은 Other로 채워집니다. 필드 목록에는 스트림의 필드가 모두 체크되어 있습니다.

새 커스텀 DMO의 이름

만들어진 DMO의 API 이름은 끝에 __dlm이 붙은 LUKA_Enrollment__dlm입니다.

2. 필드 매핑을 확인합니다

Save를 누르면 DMO가 만들어지고, DLO의 필드가 새 DMO의 필드에 자동으로 매핑됩니다. 화면 아래의 Unmapped가 0이면 매핑이 끝난 것입니다.

필드 매핑이 끝난 화면

과정과 관심 과정도 같은 순서로 매핑합니다. DMO 이름은 LUKA_Course와 LUKA_CourseInterest입니다.

사람과 잇기

Individual의 ID는 원천 레코드의 ID와 같으므로, 관심 과정에 담아 둔 Prospect ID로 문의자와 관계를 걸 수 있습니다.

관계(Relationship)는 DMO의 필드 하나를 다른 DMO의 키와 잇는 설정입니다.

목적: 세그먼트는 Individual에서 출발해 조건을 겁니다. "이 과정에 관심을 표시한 사람"을 고르려면, 관심 과정 레코드가 어느 Individual의 것인지 Data Cloud가 알아야 합니다. 그러려면 관심 과정에 Individual의 ID와 같은 값을 가진 필드가 있어야 합니다.

확인한 사실: Individual은 Data Cloud에서 사람 한 명을 나타내는 표준 DMO입니다. Individual의 ID는 원천 레코드의 ID를 그대로 씁니다.

사람	원천	Individual의 ID
문의자	Prospect	Prospect ID
수강생, 학부모	Contact	Contact ID

기존 필드로 안 되는 이유: 관심 과정에서 사람을 가리키는 방법은 셋이었지만 모두 막혔습니다.

Contact 조회 필드: 수강생이 된 뒤에야 값이 들어갑니다. 관심 과정의 주인은 대부분 아직 Contact가 없는 문의자입니다.
이메일이 든 고유 키: Individual에는 이메일 필드가 없습니다. 또 문의자 4명은 학부모와 이메일이 같아 한 사람으로 정해지지 않습니다.
Prospect 조회 필드: 다른 오브젝트에서 Prospect를 조회 필드로 가리킬 수 없어 배포 단계에서 거절됩니다.

고른 것: 그래서 Prospect ID를 텍스트로 담는 사람 ID를 더했습니다. 값이 Individual의 ID와 같으므로, 조회 필드가 아니어도 관계를 걸 수 있습니다.

판단 카드: 사람과 잇는 키

관계는 모두 여섯 개를 겁니다. 관심 과정과 수강 신청은 각각 과정에 관계를 겁니다. Individual과는 사람 ID, Contact, 수강생, 연락 대상 네 필드로 잇습니다.

DMO 사이의 관계 6개

관심 과정의 Contact 필드는 이번 데이터에 값이 없지만, 문의자가 수강생이 된 뒤에 쓰도록 관계를 함께 겁니다.

관계를 걸고 상태를 확인합니다

Data Model 탭에서 관심 과정 DMO(LUKA_CourseInterest)를 열고 Relationships 탭을 엽니다. 관계가 없으면 New를, 있으면 같은 자리의 Edit를 눌러 Edit Relationships 창을 엽니다.

New Relationship을 눌러 아래 값을 고르고 Save & Close를 누릅니다. Cardinality는 모든 관계에서 N:1입니다.

Field	Related Object	Related Field
사람 ID	Individual	Individual Id
과정	LUKA_Course	Record ID
Contact	Individual	Individual Id

수강 신청 DMO에도 같은 방법으로 과정, 수강생, 연락 대상 세 관계를 겁니다. 과정은 LUKA_Course의 Record ID에, 수강생과 연락 대상은 Individual의 Individual Id에 잇습니다. 관심 과정에 세 관계를 걸면 Relationships 탭 표에 세 줄이 보입니다.

관계 세 개를 건 뒤의 Relationships 탭

표에는 상태 열이 없으므로, 활성 여부는 Edit로 여는 Edit Relationships 창의 Active 스위치로 확인합니다.

Active가 켜진 관계 세 개

세그먼트에서 확인

세그먼트 빌더의 Individual 아래에서 관심 과정을 거쳐 과정의 속성까지 고를 수 있으면, 세그먼트 조건으로 쓸 준비가 끝난 것입니다.

세그먼트 빌더를 열려면 먼저 세그먼트를 하나 저장합니다.

Segments 탭에서 New를 누르고 Visual, Standard를 고른 뒤 Next를 누릅니다.
Segment On에 Individual을 고르고 이름을 넣은 뒤 Next를 누릅니다.
Run Mode를 Do Not Schedule로 두고 Save를 누릅니다.

주의

확인용 세그먼트는 게시하지 않고, 확인한 뒤 지웁니다. 저장 뒤 Segment Status가 Active, Publish Schedule이 Don't refresh로 보여도 게시된 것은 아닙니다.

빌더 왼쪽 Attributes 탭에서 Attributes 단추를 누르고 Resources의 Individual을 엽니다. 목록 위쪽에는 Individual 자체의 속성이 나옵니다.

Resources의 Individual

속성 목록을 내리면 관련 속성 묶음이 이어집니다. 묶음 이름은 "DMO - 관계를 건 필드 라벨" 형식이며, Individual과 건 관계마다 한 줄씩 모두 네 줄이 나옵니다.

Individual 아래의 관련 속성

과정은 Individual과 직접 관계가 없으므로 이 목록에 없습니다. LUKA_CourseInterest - 사람 ID를 누르면 관심 과정의 속성이 나옵니다. 그 아래 LUKA_Course를 누르면 과정의 속성이 나옵니다.

관심 과정을 거쳐 연 과정의 속성

과정 이름을 캔버스로 끌면 관심 과정에서 과정으로 이어진 경로와 함께 조건 칸이 열립니다.

과정 이름으로 거는 조건

값이 실제로 이어졌는지는 Query Editor에서 DMO를 조인해 사람 이름과 과정 이름으로 확인합니다. 이번 시험에서는 관심 과정 20건과 수강 신청 14건 모두 두 이름이 나왔습니다.

DMO에서는 CRM 필드 이름의 끝이 _c__c로 바뀝니다.

아래 쿼리는 JOIN으로 사람과 과정을 붙이므로 이어지지 않은 관심 과정은 결과에서 빠집니다. 20행이 모두 나오면 20건이 다 이어진 것입니다.

SELECT p.ssot__LastName__c AS person,
  c.Name__c AS course
FROM LUKA_CourseInterest__dlm i
JOIN ssot__Individual__dlm p
  ON i.LUKA_PersonId_c__c
   = p.ssot__Id__c
JOIN LUKA_Course__dlm c
  ON i.LUKA_Course_c__c = c.Id__c
ORDER BY person

수강 신청 쿼리는 수강생과 연락 대상을 각각 Individual에 조인합니다. 수강 신청 한 건이 한 행이라 14행이 나옵니다. 14세 미만 수강생 8건은 연락 대상이 학부모라서 두 이름이 다릅니다.

SELECT s.ssot__LastName__c AS student,
  t.ssot__LastName__c
    AS contact_person,
  c.Name__c AS course
FROM LUKA_Enrollment__dlm e
JOIN ssot__Individual__dlm s
  ON e.LUKA_Student_c__c
   = s.ssot__Id__c
JOIN ssot__Individual__dlm t
  ON e.LUKA_ContactPerson_c__c
   = t.ssot__Id__c
JOIN LUKA_Course__dlm c
  ON e.LUKA_Course_c__c = c.Id__c
ORDER BY student

여러 원천의 같은 사람을 하나로 묶는 동일인 판정(Identity Resolution)은 별도 글에서 다룰 예정입니다.

그림으로 쉽게 보는 요약

참고 문서

Agentforce | 블로그에 Agentforce 채팅 위젯 설치하기

Luka.dev — Mon, 19 Oct 2026 15:40:40 +0900

안녕하세요, 루카입니다. 오늘은 티스토리 블로그에 Agentforce 에이전트와 대화하는 채팅 창을 달아 보겠습니다.

Vercel Functions(Vercel 함수)는 요청이 올 때만 실행되는 서버 코드를 서버 관리 없이 배포하는 기능입니다.

Agent API의 Consumer Secret을 블로그 페이지에 넣으면 누구나 볼 수 있으므로, Secret을 보관하고 Agent API를 대신 불러 줄 Vercel 함수가 필요합니다.

준비할 것

에이전트와 앱: Agent API로 Salesforce 밖에서 에이전트와 대화하기에서 만든 활성 에이전트와 External Client App이 필요합니다. 그 글에서 확인한 Consumer Key·Secret, My Domain 주소, Agent ID를 환경변수로 씁니다.
개발 도구: Node.js 20 이상과 Vercel 계정이 필요합니다.
Vercel 플랜: 이번에는 무료 Hobby 플랜을 썼습니다. Hobby 플랜은 비상업적인 개인 용도로만 쓸 수 있어서, 회사 사이트에는 Pro 플랜이 필요합니다.
블로그 권한: 티스토리 블로그의 관리자 권한(스킨 편집)이 필요합니다.

완료 확인: 블로그 아무 페이지에서 오른쪽 아래 에이전트에게 묻기를 눌러 질문했을 때, 에이전트의 한국어 답이 창에 뜨면 끝입니다.

구성

브라우저는 Vercel 함수만 부르고, Consumer Secret과 토큰은 그 함수 안에서만 씁니다.

완성하면 아래 창에서 에이전트와 대화합니다.

완성한 위젯

블로그 페이지에는 위젯 스크립트(widget.js)만 들어갑니다. 위젯이 Vercel 함수에 질문을 보내면, Vercel 함수가 토큰을 받아 Agent API를 부르고 답을 돌려줍니다.

구성과 Secret의 자리

프로젝트 폴더는 아래처럼 나눕니다. 이번 배포에서는 api 폴더의 파일이 Vercel 함수로, 빌드할 때 만들어지는 public 폴더의 파일이 정적 파일로 올라갔습니다.

luka-agent-widget/
├─ api/
│  ├─ session.js
│  └─ message.js
├─ lib/
│  ├─ agent.js
│  └─ http.js
├─ widget/
│  ├─ main.jsx
│  ├─ Chat.jsx
│  └─ style.css
├─ vite.config.js
├─ vercel.json
└─ package.json

Salesforce가 제공하는 웹 채팅(Enhanced Chat)은 메시징 채널, 큐, 라우팅이나 에스컬레이션 Flow를 먼저 설정해야 합니다. 이 글은 그 준비 없이 Agent API와 Vercel 함수만으로 위젯을 띄우는 대신, 상담원에게 대화를 넘기는 기능은 없습니다.

주의

이 글의 Vercel 함수에는 호출 횟수 제한이 없어서, 누구나 함수를 직접 불러 Agent API 사용량(크레딧)을 쓸 수 있습니다. 공개하기 전에 에이전트에 붙은 액션과 에이전트 사용자의 권한을 확인합니다.

Vercel 함수

Vercel 함수는 토큰을 받아 재사용하고, 다른 사이트가 위젯을 그대로 붙여 쓰지 못하게 블로그 주소에서 온 브라우저 요청만 받습니다.

1. Agent API 호출을 모듈 하나에 모읍니다

lib/agent.js는 토큰 발급, 세션 시작, 메시지 전송, 세션 종료를 맡습니다. 받은 토큰은 함수 메모리에 두고 만료 1분 전까지 다시 씁니다.

if (
  cached &&
  cached.expiresAt >
    Date.now() + 60_000
)
  return cached.token;

Agent API가 401을 돌려주면 토큰을 새로 받아 한 번만 다시 보냅니다. 세션을 열 때는 앞 글과 같이 endpoint에 My Domain 주소를 넣고, bypassUser를 true로 둡니다. 메시지 응답에서는 type이 Inform인 메시지만 답으로 돌려줍니다.

const API =
  'https://api.salesforce.com/einstein/ai-agent/v1';

export class AgentError
  extends Error {
  constructor(
    step,
    status,
    detail = '',
  ) {
    super(
      `${step} ${status} ${detail}`
        .trim(),
    );
    this.step = step;
    this.status = status;
  }
}

// { token, expiresAt }
let cached = null;

export function clearTokenCache() {
  cached = null;
}

export async function getToken(
  env = process.env,
) {
  if (
    cached &&
    cached.expiresAt >
      Date.now() + 60_000
  )
    return cached.token;
  const res = await fetch(
    env.SF_MY_DOMAIN_URL +
      '/services/oauth2/token',
    {
      method: 'POST',
      headers: {
        'Content-Type':
          'application/x-www-form-urlencoded',
      },
      body: new URLSearchParams({
        grant_type:
          'client_credentials',
        client_id: env.SF_CLIENT_ID,
        client_secret:
          env.SF_CLIENT_SECRET,
      }),
      // My Domain 이 아니면 302
      redirect: 'manual',
    },
  );
  if (res.status !== 200)
    throw new AgentError(
      'token',
      res.status,
    );
  const body = await res.json();
  cached = {
    token: body.access_token,
    expiresAt:
      Date.now() +
      (body.expires_in ?? 1800) *
        1000,
  };
  return cached.token;
}

// 401 이면 토큰을 새로 받아
// 한 번만 다시 보낸다
async function call(
  step,
  path,
  init,
  env,
) {
  for (
    let attempt = 0;
    attempt < 2;
    attempt++
  ) {
    const token = await getToken(env);
    const res = await fetch(
      `${API}${path}`,
      {
        ...init,
        headers: {
          Authorization:
            `Bearer ${token}`,
          Accept: 'application/json',
          ...init.headers,
        },
      },
    );
    if (
      res.status === 401 &&
      attempt === 0
    ) {
      clearTokenCache();
      continue;
    }
    const text = await res.text();
    if (!res.ok)
      throw new AgentError(
        step,
        res.status,
        text.slice(0, 300),
      );
    return text
      ? JSON.parse(text)
      : {};
  }
}

export async function startSession(
  env = process.env,
) {
  const body = await call(
    'session',
    '/agents/' +
      env.SF_AGENT_ID +
      '/sessions',
    {
      method: 'POST',
      headers: {
        'Content-Type':
          'application/json',
      },
      body: JSON.stringify({
        externalSessionKey:
          crypto.randomUUID(),
        instanceConfig: {
          endpoint:
            env.SF_MY_DOMAIN_URL,
        },
        streamingCapabilities: {
          chunkTypes: ['Text'],
        },
        bypassUser: true,
      }),
    },
    env,
  );
  return {
    sessionId: body.sessionId,
  };
}

export async function sendMessage(
  sessionId,
  sequenceId,
  text,
  env = process.env,
) {
  const body = await call(
    'message',
    `/sessions/${sessionId}/messages`,
    {
      method: 'POST',
      headers: {
        'Content-Type':
          'application/json',
      },
      body: JSON.stringify({
        message: {
          sequenceId,
          type: 'Text',
          text,
        },
      }),
    },
    env,
  );
  const replies = (
    body.messages ?? []
  )
    .filter(
      (m) => m.type === 'Inform',
    )
    .map((m) => m.message);
  return { replies };
}

export async function endSession(
  sessionId,
  env = process.env,
) {
  await call(
    'end',
    `/sessions/${sessionId}`,
    {
      method: 'DELETE',
      headers: {
        'x-session-end-reason':
          'UserRequest',
      },
    },
    env,
  );
}

2. 허용 주소와 CORS 헤더를 확인합니다

블로그와 Vercel 함수는 주소가 달라서, 응답에 이 블로그를 허용한다는 헤더(CORS 헤더)가 있어야 브라우저가 답을 읽습니다. lib/http.js의 preflight 함수는 요청의 Origin(요청을 보낸 페이지의 주소)이 허용 목록에 있을 때만 이 헤더를 붙입니다. 목록에 없으면 403을 돌려줍니다.

const origin = req.headers.origin;
if (!allowed.includes(origin)) {
  res
    .status(403)
    .json({
      error:
        '허용되지 않은 사이트입니다.',
    });
  return false;
}
res.setHeader(
  'Access-Control-Allow-Origin',
  origin,
);

Content-Type이 application/json인 POST와 DELETE 앞에는 브라우저가 OPTIONS 요청을 먼저 보내므로, preflight 함수는 OPTIONS에 204로 답합니다.

Agent API의 오류는 화면에 보일 응답으로 바꿉니다. 끝난 세션(404)은 410, 겹친 요청(423)은 409, 그 밖의 오류는 502입니다.

Origin은 curl로 꾸밀 수 있으므로, 이 검사는 접근 통제가 아닙니다.

import {
  AgentError,
} from './agent.js';

const UUID =
  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
export const MAX_TEXT = 500;

// true: 핸들러가 계속 처리한다
// false: 이미 응답을 보냈다
export function preflight(
  req,
  res,
  methods,
  env = process.env,
) {
  const allowed = (
    env.ALLOWED_ORIGINS ?? ''
  )
    .split(',')
    .map((s) => s.trim())
    .filter(Boolean);
  const origin = req.headers.origin;
  if (!allowed.includes(origin)) {
    res
      .status(403)
      .json({
        error:
          '허용되지 않은 사이트입니다.',
      });
    return false;
  }
  res.setHeader(
    'Access-Control-Allow-Origin',
    origin,
  );
  res.setHeader('Vary', 'Origin');
  res.setHeader(
    'Access-Control-Allow-Methods',
    `${methods.join(', ')}, OPTIONS`,
  );
  res.setHeader(
    'Access-Control-Allow-Headers',
    'Content-Type',
  );
  if (req.method === 'OPTIONS') {
    res.status(204).end();
    return false;
  }
  if (!methods.includes(req.method)) {
    res
      .status(405)
      .json({
        error:
          '지원하지 않는 요청입니다.',
      });
    return false;
  }
  return true;
}

export function isSessionId(v) {
  return (
    typeof v === 'string' &&
    UUID.test(v)
  );
}

export function sendError(res, err) {
  console.error(err);
  if (err instanceof AgentError) {
    if (
      err.status === 404 ||
      err.status === 410
    )
      return res
        .status(410)
        .json({
          error: 'session_expired',
        });
    if (err.status === 423)
      return res
        .status(409)
        .json({
          error:
            '앞의 답을 기다리는 중입니다.',
        });
  }
  return res
    .status(502)
    .json({
      error:
        '에이전트에 연결하지 못했습니다. 잠시 뒤 다시 시도해 주세요.',
    });
}

3. 세션 함수와 메시지 함수를 만듭니다

api/session.js는 POST로 세션을 열어 sessionId를 돌려주고, DELETE로 세션을 닫습니다. api/message.js는 세션 ID 형식, 순번, 메시지 길이(500자 이하)를 검사한 뒤 에이전트의 답만 돌려줍니다.

if (
  typeof text !== 'string' ||
  !text.trim() ||
  text.length > MAX_TEXT
) {
  return res
    .status(400)

import {
  startSession,
  endSession,
} from '../lib/agent.js';
import {
  preflight,
  isSessionId,
  sendError,
} from '../lib/http.js';

export default async function handler(
  req,
  res,
) {
  if (
    !preflight(req, res, [
      'POST',
      'DELETE',
    ])
  )
    return;
  try {
    if (req.method === 'POST')
      return res
        .status(200)
        .json(await startSession());
    const { sessionId } =
      req.body ?? {};
    if (!isSessionId(sessionId))
      return res
        .status(400)
        .json({
          error:
            '세션 정보가 올바르지 않습니다.',
        });
    await endSession(sessionId);
    return res.status(204).end();
  } catch (err) {
    return sendError(res, err);
  }
}

import {
  sendMessage,
} from '../lib/agent.js';
import {
  preflight,
  isSessionId,
  sendError,
  MAX_TEXT,
} from '../lib/http.js';

export default async function handler(
  req,
  res,
) {
  if (!preflight(req, res, ['POST']))
    return;
  const {
    sessionId,
    sequenceId,
    text,
  } = req.body ?? {};
  if (
    !isSessionId(sessionId) ||
    !Number.isInteger(sequenceId) ||
    sequenceId < 1
  ) {
    return res
      .status(400)
      .json({
        error:
          '세션 정보가 올바르지 않습니다.',
      });
  }
  if (
    typeof text !== 'string' ||
    !text.trim() ||
    text.length > MAX_TEXT
  ) {
    return res
      .status(400)
      .json({
        error: `메시지는 1~${MAX_TEXT}자로 보내 주세요.`,
      });
  }
  try {
    return res
      .status(200)
      .json(
        await sendMessage(
          sessionId,
          sequenceId,
          text.trim(),
        ),
      );
  } catch (err) {
    return sendError(res, err);
  }
}

채팅 위젯

위젯은 세션 ID와 순번을 sessionStorage에 두어, 같은 탭에서 페이지를 옮겨도 대화를 이어 갑니다.

1. Shadow DOM 안에 위젯을 그립니다

widget/main.jsx는 body 끝에 div 하나를 붙이고, 그 안에 Shadow DOM(페이지와 분리된 별도 DOM 영역)을 만들어 위젯을 그립니다. 그래서 블로그 스킨의 CSS와 위젯의 CSS가 서로 섞이지 않습니다.

const shadow = host.attachShadow({
  mode: 'open',
});
const style =
  document.createElement('style');
style.textContent = css;
shadow.appendChild(style);

Vercel 함수의 주소는 스크립트 자신의 주소에서 읽습니다. 그래서 스킨에는 스크립트 한 줄만 넣으면 됩니다.

import {
  createRoot,
} from 'react-dom/client';
import Chat from './Chat.jsx';
import css from './style.css?inline';

const apiBase = new URL(
  document.currentScript.src,
).origin;

function mount() {
  const host =
    document.createElement('div');
  host.id = 'luka-agent-widget';
  document.body.appendChild(host);
  const shadow = host.attachShadow({
    mode: 'open',
  });
  const style =
    document.createElement('style');
  style.textContent = css;
  shadow.appendChild(style);
  const root =
    document.createElement('div');
  shadow.appendChild(root);
  createRoot(root).render(
    <Chat apiBase={apiBase} />,
  );
}

if (document.readyState === 'loading')
  document.addEventListener(
    'DOMContentLoaded',
    mount,
  );
else mount();

:host {
  all: initial;
}
* {
  box-sizing: border-box;
  font-family:
    system-ui,
    -apple-system,
    "Apple SD Gothic Neo",
    "Malgun Gothic",
    sans-serif;
}

.launcher {
  position: fixed;
  right: 20px;
  bottom: 20px;
  z-index: 2147483000;
  padding: 12px 18px;
  border: 0;
  border-radius: 999px;
  background: #0b5cab;
  color: #fff;
  font-size: 15px;
  font-weight: 600;
  box-shadow: 0 4px 14px
    rgba(0, 0, 0, 0.2);
  cursor: pointer;
}

.panel {
  position: fixed;
  right: 20px;
  bottom: 76px;
  z-index: 2147483000;
  display: flex;
  flex-direction: column;
  width: 360px;
  height: 520px;
  max-height: calc(100vh - 100px);
  background: #fff;
  color: #181818;
  border: 1px solid #d8dde6;
  border-radius: 12px;
  box-shadow: 0 8px 28px
    rgba(0, 0, 0, 0.18);
  overflow: hidden;
}

header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 12px 14px;
  background: #0b5cab;
  color: #fff;
  font-size: 15px;
}
header button {
  margin-left: 6px;
  padding: 4px 8px;
  border: 1px solid
    rgba(255, 255, 255, 0.6);
  border-radius: 6px;
  background: transparent;
  color: #fff;
  font-size: 13px;
  cursor: pointer;
}

.list {
  flex: 1;
  margin: 0;
  padding: 14px;
  list-style: none;
  overflow-y: auto;
  background: #f4f6f9;
}
.list li {
  max-width: 85%;
  margin: 0 0 10px;
  padding: 9px 12px;
  border-radius: 10px;
  font-size: 14px;
  line-height: 1.55;
  white-space: pre-wrap;
  word-break: break-word;
}
.list .agent {
  background: #fff;
  border: 1px solid #e1e5ec;
}
.list .user {
  margin-left: auto;
  background: #0b5cab;
  color: #fff;
}
.list .typing {
  color: #5c6470;
}

form {
  display: flex;
  gap: 8px;
  padding: 10px;
  border-top: 1px solid #e1e5ec;
}
input {
  flex: 1;
  min-width: 0;
  padding: 9px 10px;
  border: 1px solid #c9ced6;
  border-radius: 8px;
  font-size: 14px;
}
form button {
  padding: 0 14px;
  border: 0;
  border-radius: 8px;
  background: #0b5cab;
  color: #fff;
  font-size: 14px;
  cursor: pointer;
}
button:disabled {
  opacity: 0.5;
  cursor: default;
}

.note {
  margin: 0;
  padding: 0 12px 10px;
  color: #5c6470;
  font-size: 12px;
}

/* 이 폭 이하에서는 스킨의
   목차 단추가 뜨므로 그 위로 올린다 */
@media (max-width: 1359px) {
  .launcher {
    bottom: 68px;
  }
  .panel {
    bottom: 124px;
    max-height: calc(100vh - 148px);
  }
}

@media (max-width: 480px) {
  .panel {
    right: 8px;
    left: 8px;
    bottom: 120px;
    width: auto;
    height: calc(100vh - 140px);
  }
  .launcher {
    right: 12px;
    bottom: 64px;
  }
}

2. 세션과 순번을 저장합니다

widget/Chat.jsx는 첫 질문을 보낼 때 세션을 열고, 메시지마다 순번(sequenceId)을 1씩 올립니다. 순번은 요청을 보내기 전에 sessionStorage에 저장하므로, 답을 기다리다 다른 글로 옮겨도 같은 순번을 다시 보내지 않습니다.

세션과 순번

세션이 끝나 Vercel 함수가 410을 돌려주면, 위젯은 새 세션을 열어 같은 질문을 순번 1로 다시 보냅니다.

if (
  status === 410 &&
  attempt === 0
) {
  // 세션이 끝났으면 새로 열어
  // 한 번 더 보낸다
  sessionId = null;
  continue;
}

이 에이전트의 첫인사는 영어로 오므로, 위젯은 세션 응답의 인사 대신 한국어 인사를 직접 보여 줍니다. 질문은 화면에서 대화 하나에 20회까지 받고, 새 대화를 누르면 다시 셉니다.

닫힌 세션에 메시지를 보내면 Agent API는 404(NotFoundException)를 돌려줬습니다. 문서는 404를 토큰이나 주소가 틀렸을 때의 응답으로만 안내합니다.

import {
  useEffect,
  useRef,
  useState,
} from 'react';

const KEY = 'luka-agent-widget';
// 화면용 제한(서버는 세지 않음)
const MAX_TURNS = 20;
const GREETING =
  '안녕하세요. Agentforce 에이전트입니다. 궁금한 것을 물어보세요.';

function load() {
  try {
    return (
      JSON.parse(
        sessionStorage.getItem(KEY),
      ) ?? null
    );
  } catch {
    return null;
  }
}

function save(state) {
  try {
    sessionStorage.setItem(
      KEY,
      JSON.stringify(state),
    );
  } catch {
    // 저장하지 못해도 이 페이지 안에서는 대화가 이어진다
  }
}

const fresh = () => ({
  sessionId: null,
  seq: 0,
  messages: [
    { role: 'agent', text: GREETING },
  ],
});

export default function Chat({
  apiBase,
}) {
  const [open, setOpen] =
    useState(false);
  const [state, setState] = useState(
    () => load() ?? fresh(),
  );
  const [input, setInput] =
    useState('');
  const [busy, setBusy] =
    useState(false);
  const listRef = useRef(null);

  useEffect(
    () => save(state),
    [state],
  );
  useEffect(() => {
    listRef.current?.scrollTo({
      top: listRef.current
        .scrollHeight,
    });
  }, [state.messages, open, busy]);

  const post = async (
    path,
    body,
    method = 'POST',
  ) => {
    const res = await fetch(
      `${apiBase}${path}`,
      {
        method,
        headers: {
          'Content-Type':
            'application/json',
        },
        body: body
          ? JSON.stringify(body)
          : undefined,
      },
    );
    const data =
      res.status === 204
        ? {}
        : await res.json();
    return {
      status: res.status,
      data,
    };
  };

  const startSession = async () => {
    const { status, data } =
      await post('/api/session');
    if (status !== 200)
      throw new Error(data.error);
    return data.sessionId;
  };

  const turns = state.messages.filter(
    (m) => m.role === 'user',
  ).length;

  const send = async (e) => {
    e.preventDefault();
    const text = input.trim();
    if (
      !text ||
      busy ||
      turns >= MAX_TURNS
    )
      return;
    setInput('');
    setBusy(true);
    let { sessionId, seq } = state;
    const messages = [
      ...state.messages,
      { role: 'user', text },
    ];
    setState({
      sessionId,
      seq,
      messages,
    });
    try {
      for (
        let attempt = 0;
        attempt < 2;
        attempt++
      ) {
        if (!sessionId) {
          sessionId =
            await startSession();
          seq = 0;
        }
        seq += 1;
        // 보내기 전에 순번을 저장한다
        // (답을 기다리다 페이지를
        // 옮겨도 같은 순번을 안 보냄)
        save({
          sessionId,
          seq,
          messages,
        });
        setState({
          sessionId,
          seq,
          messages,
        });
        const { status, data } =
          await post('/api/message', {
            sessionId,
            sequenceId: seq,
            text,
          });
        if (
          status === 410 &&
          attempt === 0
        ) {
          // 세션이 끝났으면 새로 열어
          // 한 번 더 보낸다
          sessionId = null;
          continue;
        }
        const replies =
          status === 200
            ? data.replies
            : [
                status === 410
                  ? '대화가 끝났습니다. 새 대화를 눌러 다시 시작하세요.'
                  : data.error,
              ];
        const answer = replies.length
          ? replies
          : ['답을 받지 못했습니다.'];
        setState({
          sessionId,
          seq,
          messages: [
            ...messages,
            ...answer.map((t) => ({
              role: 'agent',
              text: t,
            })),
          ],
        });
        break;
      }
    } catch {
      setState({
        sessionId,
        seq,
        messages: [
          ...messages,
          {
            role: 'agent',
            text: '에이전트에 연결하지 못했습니다. 잠시 뒤 다시 시도해 주세요.',
          },
        ],
      });
    } finally {
      setBusy(false);
    }
  };

  const reset = () => {
    if (state.sessionId)
      post(
        '/api/session',
        {
          sessionId: state.sessionId,
        },
        'DELETE',
      ).catch(() => {});
    setState(fresh());
  };

  return (
    <>
      {open && (
        <section
          className="panel"
          role="dialog"
          aria-label="Agentforce 채팅"
        >
          <header>
            <strong>
              Agentforce 에이전트
            </strong>
            <div>
              <button
                type="button"
                onClick={reset}
                disabled={busy}
              >
                새 대화
              </button>
              <button
                type="button"
                onClick={() =>
                  setOpen(false)
                }
                aria-label="닫기"
              >
                ✕
              </button>
            </div>
          </header>
          <ol
            className="list"
            ref={listRef}
          >
            {state.messages.map(
              (m, i) => (
                <li
                  key={i}
                  className={m.role}
                >
                  {m.text}
                </li>
              ),
            )}
            {busy && (
              <li className="agent typing">
                답을 기다리는 중…
              </li>
            )}
          </ol>
          <form onSubmit={send}>
            <input
              value={input}
              onChange={(e) =>
                setInput(
                  e.target.value,
                )
              }
              maxLength={500}
              placeholder={
                turns >= MAX_TURNS
                  ? '새 대화를 눌러 다시 시작하세요'
                  : '메시지를 입력하세요'
              }
              disabled={
                turns >= MAX_TURNS
              }
              aria-label="메시지"
            />
            <button
              type="submit"
              disabled={
                busy ||
                !input.trim() ||
                turns >= MAX_TURNS
              }
            >
              보내기
            </button>
          </form>
          <p className="note">
            답은 Salesforce
            Agentforce가 만듭니다.
            개인 정보는 입력하지
            마세요.
          </p>
        </section>
      )}
      <button
        type="button"
        className="launcher"
        onClick={() => setOpen(!open)}
        aria-expanded={open}
      >
        {open
          ? '닫기'
          : '에이전트에게 묻기'}
      </button>
    </>
  );
}

3. widget.js 하나로 빌드합니다

Vite의 라이브러리 모드로 위젯을 widget.js 파일 하나로 묶고, 출력 폴더를 public으로 둡니다.

npm install
npm run build

이번에 만든 widget.js는 약 148KB(gzip으로 약 48KB)였습니다.

vite.config.js의 define은 React가 브라우저에서 찾는 process.env.NODE_ENV 값을 채웁니다. publicDir를 false로 둔 것은 출력 폴더와 이름이 같은 public 폴더를 다시 복사하지 않게 하려는 것입니다.

import { defineConfig } from 'vite';
import react from
  '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  define: {
    'process.env.NODE_ENV':
      '"production"',
  },
  publicDir: false,
  build: {
    outDir: 'public',
    emptyOutDir: true,
    lib: {
      entry: 'widget/main.jsx',
      formats: ['iife'],
      name: 'LukaAgentWidget',
      fileName: () => 'widget.js',
    },
  },
});

{
  "name": "luka-agent-widget",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "vite build"
  },
  "dependencies": {
    "react": "18.3.1",
    "react-dom": "18.3.1"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "4.3.4",
    "vite": "6.0.7"
  }
}

배포

환경변수 다섯 개를 넣고 배포한 뒤, 스킨을 고치기 전에 curl로 함수의 응답을 먼저 확인합니다.

1. 프로젝트를 연결하고 환경변수를 넣습니다

프로젝트 폴더에서 Vercel CLI를 설치해 로그인하고, Vercel 프로젝트를 만들어 연결합니다. 환경변수는 아래 다섯 이름으로 vercel env add를 한 번씩 실행해 넣고, 값은 명령이 물을 때 입력합니다. SF_로 시작하는 네 값에는 --sensitive를 붙입니다.

npm i -g vercel
vercel login
vercel link --yes \
  --project luka-agent-widget
vercel env add SF_CLIENT_ID \
  production --sensitive

SF_CLIENT_ID: External Client App의 Consumer Key
SF_CLIENT_SECRET: External Client App의 Consumer Secret
SF_MY_DOMAIN_URL: https로 시작하는 My Domain 주소
SF_AGENT_ID: 0Xx로 시작하는 Agent ID
ALLOWED_ORIGINS: 위젯을 띄울 블로그 주소입니다. https://로 시작하고 끝에 슬래시를 붙이지 않으며, 주소가 여럿이면 쉼표로 잇습니다

2. 운영 환경으로 배포합니다

vercel.json은 빌드 명령과 출력 폴더, 함수의 실행 시간 상한, widget.js의 캐시 시간을 정합니다. 실행 시간 상한(maxDuration)은 60초로 직접 정했고, 답이 그 안에 오지 않으면 위젯에 연결 오류가 뜹니다. Agent API의 시간 제한은 120초이므로, 더 기다리려면 Hobby 플랜의 한도(300초) 안에서 값을 올립니다.

{
  "buildCommand": "npm run build",
  "outputDirectory": "public",
  "functions": {
    "api/*.js": { "maxDuration": 60 }
  },
  "headers": [
    {
      "source": "/widget.js",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=300"
        }
      ]
    }
  ]
}

vercel deploy --prod --yes

배포가 끝나면 출력의 Aliased 줄에 운영 주소가 나옵니다.

widget.js는 5분 동안 캐시되므로, 위젯을 고쳐 다시 배포하면 블로그에는 최대 5분 늦게 반영될 수 있습니다.

3. curl로 응답을 확인합니다

함수 주소로 직접 요청을 보냅니다. Origin 헤더에 블로그 주소를 넣어야 함수가 요청을 받습니다.

B=https://luka-agent-widget.vercel.app
O="Origin: https://jt98.tistory.com"
curl -X POST -H "$O" $B/api/session

세션 시작 응답의 sessionId를 msg.json에 넣고 메시지를 보냅니다.

{
  "sessionId": "<세션 ID>",
  "sequenceId": 1,
  "text": "무엇을 도와줄 수 있나요?"
}

CT="Content-Type: application/json"
curl -X POST -H "$O" -H "$CT" \
  --data-binary @msg.json \
  $B/api/message

나머지 세 요청은 아래처럼 보냅니다.

Origin 확인: 세션 시작 명령에서 -H "$O"를 빼고 보냅니다.
빈 메시지: msg.json의 text를 빈 문자열로 바꿔 보냅니다.
닫은 세션: 아래 명령으로 세션을 닫고(204) 같은 메시지를 다시 보냅니다.

curl -X DELETE -H "$O" -H "$CT" \
  -d '{"sessionId":"<세션 ID>"}' \
  $B/api/session

다섯 요청이 표와 같이 답하면 다음 단계로 넘어갑니다. 403과 400은 함수가 의도대로 막은 결과입니다.

요청	기대 응답	다르면 볼 곳
세션 시작	200, sessionId	403이면 ALLOWED_ORIGINS, 502면 vercel logs
메시지	200, replies	400이면 세션 ID와 순번
Origin이 없거나 다름	403	200이면 ALLOWED_ORIGINS
빈 메시지	400	메시지 함수의 검사
닫은 세션에 메시지	410	lib/http.js의 오류 변환

블로그 연결

스킨 HTML의 </body> 앞에 스크립트 한 줄을 넣으면 모든 페이지에 위젯이 뜹니다.

1. 스킨 HTML 편집기를 엽니다

블로그 관리의 꾸미기 > 스킨 편집에서 오른쪽 패널의 html 편집을 누릅니다. "html 및 CSS 편집으로 인해 발생하는 문제는 직접 수정하셔야 합니다." 확인 창이 뜨면 확인을 누릅니다.

html 편집 단추

2. body 닫는 태그 앞에 스크립트를 넣고 적용합니다

HTML 탭의 맨 아래로 내려가 </body> 바로 위에 아래 한 줄을 넣고, 오른쪽 위 적용을 누릅니다. 주소는 배포 출력의 Aliased 줄에 나온 자신의 운영 주소로 바꿉니다.

<script
  src="https://luka-agent-widget.vercel.app/widget.js"
  defer></script>

body 닫는 태그 앞의 위젯 스크립트

3. 블로그에서 대화해 봅니다

블로그 아무 페이지나 열면 오른쪽 아래에 에이전트에게 묻기 단추가 보입니다. 단추가 스킨의 고정 단추와 겹치면 widget/style.css의 right와 bottom 값을 바꿉니다.

오른쪽 아래의 위젯 단추

단추를 누르고 질문을 보내면 구성 절의 그림처럼 답이 뜹니다. 이번에는 세션을 여는 시간까지 더해 약 5~6초 뒤에 답이 왔습니다. 답의 내용은 에이전트에 연결한 지식과 액션에 따라 달라집니다.

좁은 화면에서는 대화 창이 화면 대부분을 덮습니다.

모바일 대화 창

현재는 UI/UX 개선이 진행되어 다음과 같은 귀여운 에이전트 포스 봇을 만날 수 있습니다 !

그림으로 쉽게 보는 요약

참고 문서

Agentforce | Draft with Agentforce로 이메일 제목과 본문 초안 생성

Luka.dev — Mon, 19 Oct 2026 14:40:55 +0900

안녕하세요, 루카입니다. 오늘은 Draft with Agentforce로 메일 제목과 본문 초안을 한국어로 받아서 이메일에 넣어 보겠습니다.

Draft with Agentforce는 Email Builder에서 메일 제목이나 문단에 넣을 초안을 AI에게 받는 기능입니다.

받은 초안을 고쳐 쓰면 되므로 메일 제목과 첫 문단을 빨리 채울 수 있습니다.

준비할 것

켜 둘 기능: Marketing Cloud Next(MCN) org에 Agentforce와 Einstein 생성형 AI가 켜져 있어야 합니다. 관리자가 마케팅 에이전트도 설정해 두어야 합니다(AF-03 준비와 과금).
권한: 마케팅 에이전트를 쓰는 Marketing Team Agent Access 권한과, 마케팅 워크스페이스에서 이메일을 만들 수 있는 권한이 있어야 합니다.
Email Builder: 컴포넌트를 캔버스에 놓고 Settings 패널을 여는 방법은 008 Email Builder에서 다뤘습니다.
언어: 도움말은 초안 생성의 지원 언어를 영어(en_US) 하나로 적습니다. 이 글의 한국어 초안은 2026년 10월에 요청에 "한국어로"를 적어 받은 결과입니다.
사용량: 초안을 받을 때 생성형 AI 사용량(Einstein Requests 또는 Flex Credits)을 씁니다.

완료 확인: 저장한 이메일을 다시 열었을 때 메일 제목과 문단에 한국어 초안이 들어 있으면 끝입니다.

브랜드 준비

이메일에 브랜드를 지정하면, 브랜드에 적어 둔 브랜드 소개와 톤이 초안 요청에 함께 들어갑니다.

브랜드 지정은 필수가 아닙니다.

1. 브랜드에 브랜드 소개와 톤을 적습니다

마케팅 워크스페이스에서 Add > Content를 누르고 Brand를 골라 Create를 누릅니다. Title에 브랜드 이름을, Brand Identity에 브랜드 소개를 두 문장 정도 적습니다.

Continue with Existing Builder와 Try Brand Center를 고르는 창이 뜨면 Continue with Existing Builder를 고릅니다. Brand Center는 관리자가 따로 켜야 합니다.

Brand Tone에서 쓸 톤 카드의 메뉴를 열어 Set as Default를 고르고 Save를 누릅니다.

Brand Identity와 기본 톤

이번 화면의 톤은 다섯 가지였습니다. 처음 기본값은 Professional이었고, 체험수업 안내에 맞춰 Casual로 바꿨습니다.

2. 이메일에 브랜드를 지정합니다

새 이메일을 Use Components로 만들고 이름을 정합니다. 캔버스에 Paragraph를 하나 놓으면 오른쪽 Settings 패널이 Paragraph 설정으로 바뀌므로, 뒤로 가기를 눌러 이메일 Settings 패널로 돌아옵니다.

Brand의 Select Brand에서 방금 만든 브랜드를 고르고 Add를 누릅니다.

이메일에 지정한 브랜드

제목 초안

메일 제목은 기본 확인 카드를 두고 요청을 새로 적어 보낸 뒤, 그 요청으로 뜬 확인 카드에서 Confirm을 눌러 초안을 받습니다.

1. 메일 제목 칸의 반짝이 단추를 누릅니다

이메일 Settings 패널을 아래로 내리면 메일 제목을 넣는 Subject Line 칸이 있습니다. 칸 오른쪽의 반짝이 모양 단추가 Draft with Agentforce 단추입니다.

메일 제목 칸 옆의 반짝이 단추

패널 위쪽의 data graph 경고는 Dynamic Content에 관한 것이라 초안 받기와는 상관없습니다.

2. 요청을 새로 적어 보냅니다

단추를 누르면 화면 위에 Agentforce 창이 뜨고, 기본 확인 카드가 먼저 나옵니다. 이 카드의 User Input에는 "Can you draft a new subject line for my email?" 같은 영어 기본 요청이 들어 있습니다.

메일 제목에서는 이 카드의 Confirm을 누르지 않습니다. 창 아래 입력 칸에 "체험수업 신청을 권하는 메일 제목을 한국어로 써 줘"처럼 요청을 적어 보내면, 적은 요청으로 새 확인 카드가 뜹니다.

적은 요청으로 뜬 새 확인 카드

새 확인 카드의 User Input에는 적은 요청이 들어갑니다. Key Message에는 에이전트가 요약한 핵심 메시지가, Tone과 Brand Identity에는 브랜드의 값이 들어 있습니다.

주의

요청을 보냈는데 새 확인 카드 없이 영어 초안이 바로 나올 수 있습니다. 이 초안은 Apply하지 않고 같은 요청을 한 번 더 보냅니다. 이번 시험에서는 두 번째에 새 확인 카드가 떴습니다.

3. Confirm을 누르고 초안을 Apply합니다

새 확인 카드의 Confirm을 누르면 결과 카드에 메일 제목 초안이 나옵니다. Apply를 누르면 Subject Line 칸과 캔버스 위 메일 제목에 초안이 들어갑니다. 초안이 마음에 들지 않으면 Try Again으로 다시 받습니다.

한국어로 받은 메일 제목 초안

메일 제목에 넣은 초안

메일 제목이 들어가면 Save를 누릅니다. 새 이메일은 메일 제목이 있어야 저장됩니다.

본문 초안

문단은 기본 확인 카드에서 바로 Confirm을 누릅니다. 먼저 나온 영어 초안을 "한국어로 다시 써 줘"로 다시 받은 뒤 Apply합니다.

1. 문단 툴바의 반짝이 단추를 누릅니다

캔버스의 Paragraph를 두 번 누르면 서식 툴바가 뜹니다. 툴바 위쪽 줄에 반짝이 단추가 있고, 한 번만 누르면 이 단추가 보이지 않습니다.

문단 툴바의 반짝이 단추

2. 영어 초안을 받은 뒤 한국어로 다시 받습니다

문단은 메일 제목과 순서가 다릅니다. 처음부터 "한국어로"를 넣어 보내면 영어 초안이 나오거나, Apply해도 문단에 글자가 들어가지 않은 적이 있었습니다.

기본 확인 카드에서 바로 Confirm을 눌러 영어 초안을 받습니다.
영어 초안은 Apply하지 않고, 창 아래 입력 칸에 "한국어로 다시 써 줘"를 보냅니다.
새 확인 카드에서 Confirm을 누르면 한국어 초안이 나옵니다.

3. Apply한 뒤 문단을 확인하고 저장합니다

받은 초안에는 브랜드 소개에 없는 내용이 섞일 수 있으므로, 넣기 전에 직접 읽고 사실과 다른 곳을 고칩니다.

한국어 초안의 Apply를 누르고, 캔버스 문단에 글자가 들어갔는지 확인한 뒤 Save를 누릅니다. 문단이 빈 채로 남으면 저장하지 않고 반짝이 단추부터 다시 누릅니다.

저장한 뒤 다시 연 이메일

결과 카드의 Try Again 옆 ▼ 메뉴에는 톤 바꾸기 다섯 가지, 길이 늘리기·줄이기, 핵심 메시지와 대상 고객으로 다시 쓰기가 있습니다.

결과 카드의 메뉴

길이 늘리기: 한국어 초안에서 고르면 한국어로 늘어났습니다. 그러나 늘어난 초안은 Apply해도 문단에 들어가지 않았고, 브랜드 소개에 없는 "전문 강사진"도 생겼습니다.
글이 있는 문단: 이미 글이 들어간 문단에서 받은 새 초안은 영어였습니다. 여기에 "한국어로 다시 써 줘"를 보내면 지원하지 않는다는 답이 나왔습니다.
그래서 이 글에서는: 메뉴를 거치지 않은 한국어 초안을 Apply했습니다.

결과 언어

요청을 한국어로 써도 초안은 영어로 나올 수 있습니다. "한국어로 써 줘"처럼 결과 언어를 요청에 적습니다.

같은 요청에서 "한국어로"만 빼고 보냈습니다. 창의 안내 문장은 한국어였지만 메일 제목 초안은 영어였습니다.

"한국어로"를 빼고 요청한 결과

요청 문장과 결과 언어

두 요청은 캔버스가 빈 이메일에서 한 번씩 보냈습니다.

그림으로 쉽게 보는 요약

참고 문서

Agentforce | Agent API로 Salesforce 외부에서 에이전트와 메시지 주고받는법

Luka.dev — Mon, 19 Oct 2026 13:49:22 +0900

안녕하세요, 루카입니다. 오늘은 External Client App을 만들고 curl로 Agent API를 호출해, Salesforce 밖에서 Agentforce 에이전트와 메시지를 주고받아 보겠습니다.

Agent API는 Salesforce 밖의 프로그램이 Agentforce 에이전트에게 메시지를 보내고 답을 받게 해 주는 기능입니다.

홈페이지나 사내 시스템이 자기 화면에 에이전트의 답을 보여 주려면, 그 시스템이 이 API를 호출해야 합니다.

준비할 것

org와 권한: Agentforce가 켜진 org와 시스템 관리자 권한이 필요합니다.
터미널: curl을 쓸 수 있는 bash 계열 터미널(macOS, Linux, Windows는 Git Bash)을 준비합니다.
사용자 라이선스: 이번에는 연동 사용자에게 Salesforce Integration 라이선스를 썼습니다. 남은 수는 Setup의 Company Information에서 확인합니다.

완료 확인: 메시지를 보내면 에이전트의 답(type Inform)이 오고, 세션을 닫았을 때 SessionEnded가 오면 끝입니다.

에이전트 준비

Agent API로 부를 에이전트를 만들어 활성화한 뒤, Agent ID는 빌더 주소가 아니라 조회로 얻습니다.

1. Service 에이전트를 만듭니다

Setup의 Agentforce Agents에서 New Agent를 누르고, 새 빌더 안내 창의 Create Agent를 누릅니다. 새 탭의 템플릿 목록에서 Agentforce Service Agent의 Select를 누릅니다.

Agent API 문서에 따르면 Agentforce (Default) 유형은 Agent API로 부를 수 없습니다.

Agentforce Service Agent 템플릿

Name your agent 창에서 이름과 Developer Name을 넣고, New User를 고른 뒤 Let's Go를 누릅니다. New User를 고르면 이 에이전트가 동작할 때 쓰는 에이전트 사용자(Agent User)가 함께 만들어집니다.

이름과 에이전트 사용자 지정

2. 허용 언어에 Korean을 추가합니다

빌더의 Language Settings에서 Allowed Languages에 Korean을 더하고 저장합니다. 이렇게 둔 뒤 에이전트는 한국어 질문에 한국어로 답했고, 첫인사는 기본 언어인 영어로 보냈습니다.

3. 버전을 커밋하고 활성화합니다

빌더에서 Commit Version을 누르고 확인 창의 Commit을 누릅니다. 커밋하기 전의 Draft 버전에는 Activate 단추가 보이지 않습니다.

버전 커밋 확인 창

커밋이 끝나면 Activate를 누르고, Ready to activate your agent? 창에서 다시 Activate를 누릅니다.

활성화 확인 창

활성화된 에이전트

4. Agent ID를 조회합니다

새 빌더의 주소에 보이는 ID는 빌더 프로젝트와 버전의 ID(각각 1bY, 1bZ로 시작)라서 Agent ID가 아닙니다. Agent ID는 Developer Console의 Query Editor에서 아래처럼 조회합니다. 결과의 Id가 0Xx로 시작하면 맞게 찾은 것입니다.

SELECT Id FROM BotDefinition
WHERE DeveloperName =
  'LUKA_031_Class_Guide'

BotDefinition으로 찾은 Agent ID

DeveloperName에는 만든 에이전트의 Developer Name을 넣습니다.

이번에 시험한 Developer Edition org 하나에서는 커밋과 활성화가 계속 실패했고, 내부 응답은 "Changes for this Bot Version are not allowed at the moment"였습니다. 다른 org에서는 같은 순서로 활성화됐습니다.

앱 만들기

External Client App에서 Client Credentials Flow를 켜고, API만 쓸 수 있는 연동 사용자를 Run As로 지정합니다.

External Client App은 외부 시스템이 Salesforce API에 접속할 때 쓰는 앱 설정입니다. Agent API 문서는 Connected App이 아니라 이 앱을 만들라고 안내합니다.

1. 연동 사용자를 만듭니다

Setup의 Users에서 New User를 엽니다. User License는 Salesforce Integration, Profile은 Minimum Access - API Only Integrations를 고릅니다.

이번에는 이 사용자에게 권한 집합을 따로 할당하지 않았고, 이 상태로 토큰 발급과 대화가 모두 됐습니다.

연동 사용자의 라이선스와 프로필

2. External Client App을 만듭니다

Setup의 External Client App Manager에서 New External Client App을 누르고 이름과 연락 이메일을 넣습니다.

Enable OAuth를 체크하고 Callback URL에 값을 하나 넣습니다. api, refresh_token offline_access, chatbot_api, sfap_api 네 스코프를 Selected OAuth Scopes로 옮깁니다. 화면에서는 Manage user data via APIs (api)처럼 설명과 함께 보입니다.

선택한 OAuth 스코프 네 개

Callback URL은 이 방식에서 쓰지 않지만 필수 칸이라, 이번에는 https://localhost/callback을 넣었습니다.

같은 화면 아래쪽의 체크박스 다섯 개를 다음처럼 맞추고 Create를 누릅니다. Agent API 문서가 안내하는 설정이고, 해제하는 두 항목은 이 앱이 쓰지 않는 다른 흐름(Web Server, Refresh Token)의 설정입니다.

Enable Client Credentials Flow를 체크합니다. 확인 창이 뜨면 OK를 누릅니다
Require secret for Web Server Flow가 체크되어 있으면 해제합니다
Require secret for Refresh Token Flow가 체크되어 있으면 해제합니다
Require Proof Key for Code Exchange (PKCE) 항목은 체크된 채 바꿀 수 없으면 그대로 둡니다
Issue JSON Web Token (JWT)-based access tokens for named users를 체크합니다

Client Credentials와 보안 체크박스

3. 연동 사용자를 Run As로 지정합니다

만든 앱의 Policies 탭에서 Edit를 누릅니다. OAuth Flows and External Client App Enhancements에서 Enable Client Credentials Flow를 다시 체크합니다.

문서도 앱 설정과 정책 두 곳에서 모두 켜도록 안내하고, Run As는 정책 쪽에만 있습니다.

Run As (Username) 칸에 연동 사용자의 Username을 넣고 저장합니다.

Run As에 지정한 연동 사용자

4. Consumer Key와 Secret을 확인합니다

앱의 Settings 탭에서 OAuth Settings를 펼치고 Consumer Key and Secret을 누릅니다. 본인 확인 코드를 넣으면 새 탭에 Key와 Secret이 보입니다.

Key와 Secret을 여는 단추

주의

Consumer Secret은 브라우저 코드나 공개 저장소에 두지 않습니다. 이 값이 있으면 누구나 연동 사용자로 토큰을 받을 수 있습니다.

API 호출

토큰은 My Domain 주소로 받고, 세션과 메시지는 api.salesforce.com으로 보냅니다.

호출 순서와 주소

1. My Domain 주소를 확인합니다

Setup의 My Domain에서 Current My Domain URL을 확인합니다. 이 주소는 my.salesforce.com으로 끝납니다. 브라우저 주소창에 보이는 lightning.force.com 주소가 아닙니다.

Current My Domain URL

2. 변수를 정하고 토큰을 받습니다

명령마다 같은 값을 다시 쓰지 않도록, 아래 변수에 자기 org의 값을 넣어 둡니다.

DOMAIN=<이름>.my.salesforce.com
KEY=<Consumer Key>
SECRET=<Consumer Secret>
AGENT_ID=<0Xx로 시작하는 ID>
API=https://api.salesforce.com
API+=/einstein/ai-agent/v1
CT="Content-Type: application/json"

URL="https://$DOMAIN"
URL+="/services/oauth2/token"
curl -s -X POST "$URL" \
  -d grant_type=client_credentials \
  -d client_id="$KEY" \
  -d client_secret="$SECRET"

응답의 access_token 값을 TOKEN에 넣습니다. scope에 sfap_api chatbot_api api가 보이면 앱 설정이 맞은 것입니다. 이번 응답의 expires_in은 7200초(약 2시간)였습니다.

TOKEN=<응답의 access_token>
AUTH="Authorization: Bearer $TOKEN"

3. 세션을 엽니다

세션을 여는 요청 본문은 아래 내용을 start.json으로 저장해 보냅니다. externalSessionKey에는 UUID 생성기로 만든 아무 값이나 넣고, endpoint에는 My Domain 주소를 넣습니다.

{
  "externalSessionKey": "<UUID>",
  "instanceConfig": {
    "endpoint": "https://<My Domain>"
  },
  "streamingCapabilities": {
    "chunkTypes": ["Text"]
  },
  "bypassUser": true
}

curl -s -X POST \
  "$API/agents/$AGENT_ID/sessions" \
  -H "$AUTH" -H "$CT" \
  --data-binary @start.json

응답의 sessionId를 SID에 넣습니다. 응답에는 에이전트의 첫인사 메시지도 함께 옵니다.

SID=<응답의 sessionId>

4. 메시지를 보냅니다

메시지 요청 본문은 아래 내용을 msg.json으로 저장합니다. sequenceId는 세션 안에서 메시지마다 1씩 올립니다.

{
  "message": {
    "sequenceId": 1,
    "type": "Text",
    "text": "주말 반 수강 신청은 어떻게 하나요?"
  }
}

curl -s -X POST \
  "$API/sessions/$SID/messages" \
  -H "$AUTH" -H "$CT" \
  -H "Accept: application/json" \
  --data-binary @msg.json

이번에는 약 9초 뒤 type이 Inform인 응답으로 한국어 답이 왔습니다. 답은 정보를 찾지 못했다며 상담원 연결을 권했습니다. 답의 내용은 에이전트에 연결한 지식과 액션에 따라 달라지므로, 여기서는 Inform 응답이 온 것으로 연결을 확인합니다.

{
  "messages": [{
    "type": "Inform",
    "isContentSafe": true,
    "message": "현재 주말 반 수강
      신청 방법에 대한 정보를
      불러올 수 없습니다. …
      상담원 연결을
      원하시나요?",
    "citedReferences": []
  }]
}

세션 시작 응답의 _links에서 messages는 이 동기 주소이고, 스트리밍 주소는 messagesStream에 따로 있습니다. 스트리밍을 쓰면 Accept를 text/event-stream으로 바꿔 /messages/stream에 보냅니다.

5. 세션을 닫습니다

END="x-session-end-reason"
curl -s -X DELETE \
  "$API/sessions/$SID" \
  -H "$AUTH" -H "$END: UserRequest"

응답의 type이 SessionEnded이고 reason이 ClientRequest면 세션이 닫힌 것입니다. 요청 헤더의 UserRequest와 응답의 ClientRequest가 달라도 정상입니다.

오류 대처

주소나 Secret을 잘못 넣으면 302, 401, 400이 오므로, 어느 요청에서 어떤 코드가 왔는지로 고칠 곳을 찾습니다.

응답	원인	고칠 곳
토큰 요청의 302	토큰 주소가 브라우저 주소	My Domain 주소로 보냄
토큰 요청의 400	Key나 Secret이 틀림	앱의 Key와 Secret 다시 복사
세션 시작의 401	endpoint가 브라우저 주소	endpoint를 My Domain으로
메시지의 400	한국어를 `--data`로 직접 넣음	UTF-8 파일과 `--data-binary`
세션의 423	요청을 동시에 둘 보냄	응답을 받은 뒤 다음 요청

토큰 요청의 400: Secret이 틀리면 invalid_client("invalid client credentials")가 옵니다.
302: 토큰 요청을 lightning.force.com 주소로 보내면 오류 본문 없이 다른 주소로 옮기라는 302만 옵니다.
401: 세션 시작 요청의 endpoint에 브라우저 주소를 넣으면 INVALID_SESSION_ID가 옵니다. 문서는 이 경우를 500 EngineConfigLookupException으로 안내하지만 이번에는 401이었습니다.
메시지의 400: Windows Git Bash에서 한국어 본문을 --data '…'로 넣으면 "Invalid UTF-8 middle byte"가 옵니다.
423과 500: 문서에 따르면 한 세션에 요청이 겹치면 423이 오고, 응답이 120초를 넘기거나 Agent ID가 틀리면 500이 옵니다.

권한 범위

bypassUser 값에 따라 에이전트 사용자나 연동 사용자의 권한으로 동작하므로, 외부에 열기 전에 그 사용자의 권한을 확인합니다.

Agent API 문서에 따르면 bypassUser가 true면 에이전트 사용자로, false면 토큰을 받은 연동 사용자로 동작합니다. 이번에는 두 값 모두 세션이 열렸고, 같은 질문에 한국어로 답했습니다. 에이전트에 앱을 따로 연결하는 단계는 없었습니다.

bypassUser가 정하는 실행 사용자

에이전트 사용자는 빌더의 Agent Access에서 Agent's User Record로 확인합니다. 에이전트에 레코드 조회 액션을 추가하면, 외부 방문자도 이 사용자가 볼 수 있는 데이터를 답으로 받을 수 있습니다.

에이전트 사용자 레코드

주의

홈페이지 위젯처럼 누구나 호출하는 곳에 열 때는, 쓰는 bypassUser 값에 해당하는 사용자(true면 에이전트 사용자, false면 연동 사용자)의 권한 집합을 필요한 오브젝트만 읽도록 줄여 둡니다.

위젯처럼 브라우저에서 부르는 구성은 Secret을 서버 함수에 두어야 하므로 별도 글에서 다룰 예정입니다.

그림으로 쉽게 보는 요약

참고 문서

Marketing Cloud Next | Exit Event로 링크 클릭한 수신자의 후속 이메일 발송 중단

Luka.dev — Mon, 19 Oct 2026 13:37:28 +0900

안녕하세요, 루카입니다. 오늘은 연속 메일에서 첫 메일의 링크를 누른 사람에게는 두 번째 메일이 가지 않게 해 보겠습니다.

Exit Event는 받는 사람이 링크를 누르는 등 정한 행동을 하면, 그 사람을 Flow에서 내보내는 이탈 규칙의 한 종류입니다.

이탈 규칙이 없으면 Flow에 들어온 사람은 마지막 메일까지 받게 되므로, 이미 신청 단추를 누른 사람에게도 신청을 권하는 메일이 나갑니다.

준비할 것

이메일: 링크가 든 첫 메일과 두 번째 메일이 게시되어 있어야 합니다. 만드는 법은 008 Email Builder에서 다뤘습니다.
릴리스: 행동(이벤트)으로 내보내는 이탈 규칙은 Summer '26 릴리스에서 추가되었습니다.
받는 사람: 두 사람을 담은 Actionable List(연락처를 골라 담아 두는 목록)와 두 사람의 수신 동의가 필요합니다. 목록은 012 캠페인 만들기, 동의는 007 Consent Imports를 참고합니다.

완료 확인: 발송 기록에서 링크를 누른 사람은 첫 메일 SENT 한 행, 누르지 않은 사람은 SENT 두 행이면 끝입니다.

연속 메일 준비

목록에 두 사람을 담고, List로 시작하는 Flow에 메일, 대기, 메일을 넣습니다.

1. 목록에 두 사람을 담습니다

한 사람은 링크를 누르고 다른 사람은 누르지 않아 결과를 비교하므로, 받는 사람이 두 명 필요합니다. 이번에는 LUKA_032_수강생목록에 수강생01과 수강생02를 담았습니다.

2. 메일, 대기, 메일을 넣습니다

캠페인에서 Build Your Own의 List로 Flow를 만들고, 첫 메일(체험 수업 안내), Wait, 두 번째 메일(신청 마감 알림)을 차례로 넣습니다. 순서는 022와 같습니다.

메일, 대기, 메일 순서의 Flow

이번에는 결과를 빨리 보려고 대기를 1시간으로 두고, Resume at a specific time of day는 체크하지 않았습니다.

이탈 규칙 넣기

Flow Builder를 열어 시작 요소에 "첫 메일의 링크를 누르면 내보낸다"는 이탈 규칙을 넣습니다.

1. Flow Builder에서 시작 요소를 엽니다

이탈 규칙(Exit Rules)은 캠페인 화면의 Flow 요약에는 없습니다. 요약 오른쪽 위의 Open Flow를 눌러 Flow Builder를 열면, 시작 요소에 Exit Rules: 0과 Edit가 보입니다.

시작 요소의 Exit Rules

2. Add Exit Event를 누릅니다

Edit를 누르면 오른쪽에 Exit Rules 창이 열립니다. 창에는 행동으로 내보내는 Exit Events와 값으로 내보내는 Exit Conditions 두 구역이 있습니다. Exit Events 구역의 Add Exit Event를 누릅니다.

Exit Events와 Exit Conditions

도움말은 이탈 규칙을 데이터 값으로 거르는 조건으로만 설명합니다. 이벤트로 내보내는 방법은 Summer '26 릴리스 노트에 있고, 그 글은 지원하는 Flow에 List로 시작하는 Flow를 적지 않았지만 이번 Flow에서도 넣을 수 있었습니다.

3. Email Link Click을 고릅니다

Event 칸에 Email을 입력하고, Standard Automation Events 목록에서 Email Link Click을 고릅니다.

Event 목록의 Email Link Click

4. 첫 메일을 지정하고 저장합니다

Email Message 칸과 Link 칸이 더해집니다. Email Message에서 첫 메일을, Link에서 Any Link를 고르고, Label에 규칙 이름을 넣습니다.

첫 메일과 Any Link

주의

Link 목록에는 Any Link 하나만 있었습니다. 그래서 신청 단추가 아닌 링크(꼬리말의 수신 거부 링크 등)를 눌러도 빠지는 것으로 보입니다. 링크 클릭은 실제 신청과 같지 않으므로, 신청 여부가 레코드 값으로 남는다면 Exit Conditions로 거르는 방법을 함께 검토합니다.

Flow를 저장하면 활성화할 수 없다는 오류 창이 열리지만, 규칙은 저장됩니다. 오류 문구는 "Frequency: You set the flow trigger type to List, so you must also set the frequency"입니다.

이 오류는 Flow의 발송 일정이 비어 있어서 생깁니다. 캠페인 화면의 Send Now로 활성화하면 일정이 Once로 정해집니다.

저장한 뒤 시작 요소를 보면 Exit Rules: 1로 바뀌어 있습니다.

규칙이 하나 들어간 시작 요소

발송과 클릭

Send Now로 활성화한 뒤, 대기가 끝나기 전에 한 사람만 첫 메일의 링크를 누릅니다.

주의

이탈 규칙은 활성화하기 전에 넣습니다. 이미 활성화한 Flow는 Pause와 새 버전으로 고쳐야 하며, 절차는 도움말 Pause and Edit a Marketing Flow에 있습니다.

1. Send Now로 활성화합니다

캠페인 화면으로 돌아가 Schedule 옆 ▼에서 Send Now를 고르고, Send now? 창에서 Activate를 누릅니다. 순서는 022와 같습니다.

활성화한 뒤 Flow Builder에서 Exit Rules를 다시 열면 단추가 View로 바뀌고, 읽기 전용 안내가 보입니다.

활성화한 뒤의 Exit Rules

2. 한 사람만 링크를 누릅니다

수강생01이 받은 첫 메일에서 신청하기 단추를 누릅니다. 수강생02의 메일은 열지 않습니다.

누른 기록은 Data Cloud의 Query Editor에서 Email Engagement DMO(발송·열람·클릭 기록이 쌓이는 데이터 모델)를 조회해 확인합니다. 수강생01의 CLICK 행이 더해졌습니다.

수강생01의 클릭 기록

이번 시험에서 CLICK 행은 누르고 약 3분 반 뒤부터 조회되었습니다. 조회 쿼리는 아래 결과 확인 절의 접기에 있습니다.

결과 확인

이번 시험에서 링크를 누른 사람은 Flow에서 빠져 두 번째 메일을 받지 않았고, 누르지 않은 사람만 받았습니다.

누른 사람과 누르지 않은 사람

1. Flow Builder에서 요소별 실행 수를 봅니다

대기가 끝난 뒤 Flow Builder를 열면 요소마다 Total Runs가 보입니다. 첫 메일과 대기는 2, 두 번째 메일은 1입니다. 대기 요소의 이름은 기본값 Wait 1 Day로 남아 있지만, 실제 대기는 1시간입니다.

① 첫 메일 2 ② 대기 2 ③ 두 번째 메일 1

이 화면에서는 두 번째 메일의 실행 수가 하나 적은 것만 보이고, 누가 빠졌는지는 구별되지 않습니다. 사람별로는 아래 발송 기록으로 확인합니다.

2. 발송 기록으로 누가 받았는지 확인합니다

Query Editor에서 SEND_STATUS 행만 다시 조회합니다. 수강생01은 첫 메일 한 행, 수강생02는 첫 메일과 두 번째 메일 두 행입니다.

① 수강생01 한 통 ② 수강생02 두 통

수강생01은 대기가 끝나기 전에 빠졌습니다. Data Cloud의 Flow 요소 실행 기록(Flow Element Run)에는 링크를 누르고 약 5분 반 뒤에 수강생01의 대기 요소가 Stopped로 기록되었습니다.

릴리스 노트는 이탈 규칙을 Flow가 시작할 때, 일시 중지 뒤 다시 이어질 때, 액션을 부를 때 평가한다고 적지만, 이번에는 대기가 끝나기 전에 빠졌습니다. 클릭이 반영되기까지 몇 분이 걸렸으므로, 대기가 끝나기 직전에 누른 사람도 빠지는지는 확인하지 않았습니다.

사람마다, 메일마다 한 행이 나오고 시각은 한국 시간입니다.
주소가 결과에 나오지 않도록 CASE로 이름을 붙였습니다.
email_step은 메일 요소 이름의 끝부분입니다(M815가 첫 메일, M494가 두 번째 메일).
위 화면의 쿼리는 주소 대신 별칭 일부로 거른 것이고, 결과는 아래 쿼리와 같습니다.
시각은 UTC로 '2026-10-19 02:50:00'처럼 넣고, 클릭 기록까지 보려면 마지막 AND 조건(두 줄)을 지웁니다.

SELECT
  CASE WHEN
    ssot__SendtimeEmailAddress__c
    = '<누를 사람 주소>'
  THEN '수강생01'
  ELSE '수강생02' END AS person,
  regexp_replace(
    ssot__FlowElementRunId__c,
    '^.*_', '') AS email_step,
  ssot__EngagementChannelActionId__c
    AS action,
  ssot__EmailRecipientSendStatus__c
    AS send_status,
  to_char(
    ssot__EngagementDateTm__c
    + INTERVAL '9' HOUR,
    'MM-DD HH24:MI:SS') AS at_kst
FROM ssot__EmailEngagement__dlm
WHERE
  ssot__SendtimeEmailAddress__c
  IN ('<누를 사람 주소>',
      '<누르지 않을 사람 주소>')
AND ssot__EngagementDateTm__c
  > TIMESTAMP '<활성화 직전 UTC 시각>'
AND ssot__EngagementChannelActionId__c
  = 'SEND_STATUS'
ORDER BY ssot__EngagementDateTm__c

그림으로 쉽게 보는 요약

참고 문서

Agentforce | Retriever로 규정 문서를 프롬프트 응답의 근거로 활용하는법

Luka.dev — Mon, 19 Oct 2026 10:18:26 +0900

안녕하세요, 루카입니다. 오늘은 수강 안내 문서를 Data Library에 올리고, 프롬프트 템플릿이 그 문서를 근거로 문의에 답하게 해 보겠습니다.

Retriever는 Data 360에 올려 둔 문서에서 질문과 관련된 부분을 찾아 프롬프트에 넣는 기능입니다.

모델은 학원의 반 변경 규정을 모르므로, 문의에 정확히 답하게 하려면 규정 문서의 해당 부분을 프롬프트에 함께 넣어야 합니다.

준비할 것

Data 360: Data Cloud의 새 이름인 Data 360이 켜진 org가 필요합니다. Data Library는 문서를 처리할 때와 검색할 때마다 Data 360 크레딧을 씁니다(Agentforce 준비와 과금 글).
권한: Data Library를 만들려면 Data Cloud Admin과 System Administrator 권한이 필요합니다. 템플릿을 만들려면 Prompt Template Manager 권한 집합이나 Customize Application 권한이 필요합니다.
실행 권한: 도움말은 Retriever를 실행하는 사용자에게 Data Cloud User 권한 집합이 필요하고, 그 권한 집합에 기본 데이터 공간(default)이 추가되어 있어야 한다고 안내합니다.
규정 문서: 텍스트, HTML, PDF 파일을 준비합니다. Library 하나에 1,000개까지 올릴 수 있고, 이 글에서는 반 변경, 지점 이동, 환불, 교재 배송 규정을 적은 가상 수강 안내 텍스트 파일 하나를 씁니다.
시험 데이터와 앞 단계: Description이 있는 문의(Case)를 한 건 준비합니다. Flex 템플릿과 미리보기는 Flex 템플릿을 Flow에서 쓰는 글에서 다뤘습니다.

완료 확인: 미리보기 응답이 문서의 반 변경 규정으로 답하고, Resolved Prompt에 그 규정이 든 문서 조각이 보이면 끝입니다.

문서 올리기

파일을 올려 Data Library를 만들면, 문서를 찾는 데 쓰는 검색 인덱스와 Retriever가 자동으로 생깁니다.

1. Upload Files를 고릅니다

Setup의 Quick Find에서 Agentforce Data Library를 엽니다. 오른쪽 위 Add Data를 누르고 Upload Files를 고릅니다.

Add Data의 데이터 소스 선택지

2. 이름과 API 이름을 씁니다

같은 화면에 폼이 열립니다. Name과 Description을 채웁니다. Name에 한글이 있으면 API Name이 자동으로 채워지지 않으므로 영문 이름을 직접 씁니다.

Library의 이름과 설명

3. 파일을 추가하고 저장합니다

폼 아래 Intelligent Context 스위치는 기본으로 켜져 있습니다. 파일 속 표와 그림까지 읽어 내는 처리이고 크레딧을 더 쓰므로, 표와 그림이 없는 텍스트 파일이면 끕니다.

Upload Files로 파일을 추가하고 Save를 누릅니다.

스위치를 끄고 추가한 파일

주의

파일이 올라가는 동안 이 폼 화면을 떠나면 업로드가 실패합니다. 데이터 소스(이번에는 파일)와 Intelligent Context 설정은 나중에 바꿀 수 없으므로 저장 전에 정합니다.

4. 상태가 Ready가 될 때까지 기다립니다

저장하면 상세 화면의 Status 구역에서 다섯 단계가 차례로 끝납니다. Data Lake Object와 Data Model Object를 만들어 연결하고, 검색 인덱스와 Retriever를 만든 뒤, 마지막에 파일 내용을 검색 인덱스에 넣습니다.

도움말은 파일 수와 크기에 따라 몇 분에서 몇 시간이 걸린다고 안내합니다. 텍스트 파일 하나를 올린 이번 시험에서는 저장하고 6분 안에 Ready가 되었습니다.

Ready가 된 Library

Ready가 되기 전에는 Library를 쓸 수 없습니다. 기다리는 동안 다음 절의 템플릿을 먼저 만들어 두어도 됩니다.

템플릿에 넣기

Retriever의 Search Text에 문의 Description을 지정하면, 템플릿이 실행될 때마다 그 문의와 관련된 문서 조각이 프롬프트에 들어갑니다.

1. 지시문을 쓴 Flex 템플릿을 만듭니다

Prompt Builder에서 Flex 템플릿을 만들고 입력은 Case 하나로 둡니다. 지시문에는 문서를 넣을 자리("수강 안내:" 아래 줄)를 비워 둡니다.

당신은 온라인 학원의
상담 담당자입니다.
아래 문의에 보낼 답장 초안을
쓰세요.

문의 내용: (Description)

수강 안내:
(Retriever를 넣을 줄)

- 위 수강 안내에 있는 규정만
  근거로 답합니다.
- 수강 안내에 없는 내용은
  모른다고 씁니다.
- 세 문장 안으로, 한국어로
  씁니다.

(Description) 자리에는 Insert Resource로 Case의 Description 병합 필드(Merge Field)를 넣습니다. 줄은 화면 폭에 맞춰 나눈 것이라 이어 써도 됩니다.

Retriever를 넣기 전의 지시문

2. Retriever 없이 미리 봅니다

템플릿을 저장하고 Preview Settings(톱니 옆 조절 막대 아이콘)에서 반 변경 문의를 고른 뒤 Preview를 누릅니다. 수강 안내 자리가 비어 있으므로, 응답은 규정이 없어 답할 수 없다는 내용이었습니다. 첫 문장은 지시와 달리 영어로 나왔습니다.

Retriever 없이 받은 응답

3. Retriever를 고릅니다

"수강 안내:" 아래 빈 줄을 누르고 @를 친 뒤 Retrievers에서 Configure Retrievers를 누릅니다. 왼쪽에 Template Details 패널의 Resources 탭이 열리고, 앞 절에서 만든 Library의 Retriever가 목록에 보입니다.

이번 Retriever의 이름은 File_LUKA_030_Class_Guide였습니다. 목록 위 검색칸에 이름 일부를 넣으면 목록이 좁혀집니다.

Library의 Retriever

4. Search Text에 문의 Description을 지정합니다

Retriever를 누르면 같은 패널에 설정 칸이 열립니다. Search Parameters의 Search Text 검색칸에서 Case, Description을 차례로 고릅니다.

Search Text와 Number of Results

Output Fields와 Number of Results는 비워 둡니다. 비워 두면 Retriever에 정해진 값을 쓰고, Output Fields는 Retriever의 모든 필드가 프롬프트에 들어갑니다.

도움말에 따르면 Search Text에는 템플릿 입력의 병합 필드, 글로벌 값, 직접 쓴 글을 넣을 수 있고 255자까지입니다. 관련 목록, Flow, Apex의 결과는 쓸 수 없다고 안내합니다.

5. 편집기에 넣고 저장합니다

Apply and Insert를 누르면 비워 둔 줄에 Retriever가 들어갑니다. 템플릿을 저장합니다.

지시문에 들어간 Retriever

근거 확인

Generate Response를 끄고 미리 보면, AI를 부르지 않고도 Resolved Prompt에서 Retriever가 찾아 온 문서 조각을 볼 수 있습니다.

1. 응답을 만들지 않고 찾아 온 조각을 봅니다

Preview Settings에서 Generate Response를 끄고 Preview를 누릅니다. Resolved Prompt의 "수강 안내:" 아래에 검색 결과가 JSON으로 들어갑니다. 그 안의 Chunk 값이 Retriever가 찾아 온 문서 조각(chunk)입니다.

찾아 온 문서 조각

이번 문서(1.34 kB)는 전체가 조각 하나로 들어왔습니다. 도움말은 Number of Results를 "지식 기사 조각 15개"처럼 가져올 결과의 최대 수로 설명하므로, 긴 문서라면 여러 조각 가운데 관련된 것만 이 수만큼 들어옵니다.

2. 응답을 받아 봅니다

Generate Response를 다시 켜고 Preview를 누릅니다. 이번 응답은 문서의 반 변경 규정으로 답했습니다.

문서를 근거로 답한 응답

다만 "빈자리가 없으면 다음 달 개강반으로만 옮길 수 있다"는 문서에 없는 조합입니다. 문서는 빈자리가 있을 때만 처리한다고만 적습니다. Retriever는 근거를 넣어 줄 뿐이므로, 답장 초안은 보내기 전에 사람이 문서와 대조합니다.

같은 문의로 받은 두 응답을 비교하면 아래와 같습니다. Retriever 없이는 수강 안내에 규정이 없어 답할 수 없다고 했고, Retriever를 넣은 뒤에는 문서의 규정으로 답했습니다.

Retriever를 넣기 전과 뒤의 응답

그림으로 쉽게 보는 요약

참고 문서

Agentforce | Structured Outputs로 JSON 응답 형식을 지정하고 Flow에서 사용

Luka.dev — Fri, 16 Oct 2026 15:51:06 +0900

안녕하세요, 루카입니다. 오늘은 프롬프트 템플릿의 응답을 JSON으로 받고, Flow에서 긴급도 값으로 분기해 보겠습니다.

Structured Outputs는 프롬프트 템플릿이 돌려줄 응답의 형식을 JSON이나 HTML로 정해 두는 기능입니다.

지시문에 형식을 적어도 응답 형식은 호출마다 달라질 수 있으므로, Flow가 응답에서 값을 꺼내 쓰려면 형식을 템플릿 설정으로 정해 두는 편이 안전합니다.

준비할 것

권한: 템플릿을 만들려면 Prompt Template Manager 권한 집합이나 Customize Application 권한이 필요합니다. Flow를 만들려면 Manage Flow 권한이 필요합니다.
시험 데이터: 제목과 Description이 있는 문의(Case)를 한 건 준비합니다.
앞 단계: Flex 템플릿과 Flow의 Prompt Template 액션은 AF-06 글에서 다뤘습니다.

완료 확인: Flow Debug 결과에서 긴급도(urgency) 값이 필드로 보이고, Decision이 그 값으로 경로를 고른 내역이 보이면 끝입니다.

형식 바꾸기

응답 형식을 JSON으로 바꾸면 응답을 JSON 하나로 받지만, 키 이름은 모델이 정합니다.

1. 문의를 분류하는 Flex 템플릿을 만듭니다

Prompt Builder에서 Flex 템플릿을 만들고 입력은 Case 하나로 둡니다. 지시문에는 받을 항목과 값 목록을 적고, 응답 형식은 적지 않습니다.

당신은 온라인 학원의
상담 담당자입니다.
아래 문의를 읽고 분류하세요.

문의 제목: (Subject)
문의 내용: (Description)

- 분류는 반 변경, 교재·배송,
  결제·영수증, 환불, 기타
  가운데 하나입니다.
- 긴급도는 높음, 보통, 낮음
  가운데 하나입니다.
- 요약은 문의 내용을
  한 문장으로 씁니다.
- 다음 할 일은 상담 담당이
  할 일을 한 문장으로 씁니다.
- 한국어로 씁니다.

괄호 자리에는 Insert Resource로 Case의 Subject와 Description 병합 필드를 넣습니다. 줄은 화면 폭에 맞춰 나눈 것이라 이어 써도 됩니다.

지시문과 Case 병합 필드

2. 기본 형식으로 미리 봅니다

Preview Settings에서 문의를 고르고 Generate Response를 켠 채 Save & Preview를 누릅니다. 형식을 정하지 않은 기본(Default) 상태에서는 모델이 글머리표 목록으로 답했습니다.

기본 형식의 응답

3. 응답 형식을 JSON으로 바꿉니다

편집 화면의 톱니 아이콘을 누르면 왼쪽에 Template Details 패널이 열립니다. Format 구역의 Response Format에서 JSON을 고르고 저장합니다.

Response Format의 JSON

JSON을 고르면 바로 아래에 Response Structure (optional) 칸이 생깁니다. 지금은 비워 둡니다.

4. JSON 형식으로 미리 봅니다

같은 문의로 다시 Save & Preview를 누르면, 이번에는 "분류", "긴급도" 같은 한국어 키로 답했습니다.

Lightning Type 없이 받은 JSON

필드 정하기

Lightning Type으로 필드를 정해 두면 모델은 구조를 직접 정하지 않고 그 필드에 값을 채워 돌려줍니다.

Lightning Type은 응답에 들어갈 필드(JSON의 키)의 이름, 데이터 유형, 필수 여부를 정한 스키마입니다.

1. 새 Lightning Type을 만듭니다

Response Structure 칸을 누르고 New Lightning Type을 고릅니다. Label, API Name, Description을 채우고 Next를 누릅니다.

API Name은 영문자와 숫자만 쓸 수 있습니다. 라벨에서 자동으로 채운 값에는 한글과 밑줄이 들어가 Next가 눌리지 않으므로 직접 고쳐 씁니다.

Lightning Type의 이름과 설명

2. 필드 넷을 정하고 저장합니다

줄마다 Field Name, Description, Data Type을 채우고, 반드시 받아야 하는 필드는 Required를 켭니다. 필드를 더할 때는 Add Row를 누릅니다. 이번에 만든 필드 넷은 모두 String이고, nextAction만 Required를 껐습니다.

category: 분류, 앞의 다섯 값 가운데 하나
urgency: 긴급도, 높음·보통·낮음 가운데 하나
summary: 문의 내용 한 문장
nextAction: 상담 담당이 할 일 한 문장

필드 넷과 필수 여부

주의

저장한 뒤에는 필드 이름과 데이터 유형을 바꿀 수 없고, Required를 끈 필드를 나중에 켤 수도 없습니다. 나중에 더하는 필드는 Required가 꺼진 채로 더해지므로, 반드시 받을 필드는 처음 만들 때 정합니다.

Save를 누르면 Response Structure 칸에 방금 만든 Lightning Type이 골라집니다. 템플릿을 저장하고 다시 미리 보면, 이번에는 정해 둔 키 넷으로 응답했습니다.

Lightning Type을 고른 뒤의 응답

도움말은 Lightning Type을 고르면 모델이 구조를 정하지 않고 정해 둔 스키마에 값을 채운다고 안내합니다. 이번 미리보기와 뒤의 Debug에서 두 번 모두 키 넷이 같았고, summary 문장은 서로 달랐습니다.

같은 문의로 받은 세 응답을 비교하면 아래와 같습니다.

같은 문의의 형식별 응답

Flow에서 읽기

Lightning Type을 고른 템플릿을 Flow에서 부르면 액션 출력에 StructuredResponse가 생기고, 그 필드를 Decision 조건에 바로 씁니다.

1. 템플릿을 활성화합니다

활성화한 버전은 고칠 수 없으므로, 형식과 필드를 확인한 뒤 Activate를 누릅니다. 나중에 고치려면 새 버전을 만듭니다(AF-05 글). Flow에서 템플릿을 부르려면 활성 버전이 있어야 합니다.

활성화한 템플릿

2. Flow에서 템플릿을 부릅니다

트리거 없는 Autolaunched Flow를 만들고, Case 레코드 변수를 하나 만들어 Available for input을 켭니다. Action에서 Prompt Template 범주의 템플릿을 고르고 Case 입력에 그 변수를 넘깁니다. 이 글의 액션 API 이름은 Classify_Case입니다.

액션 설정 창의 View Output Resources를 보면 Prompt Response와 함께 StructuredResponse가 있습니다.

액션 출력의 StructuredResponse

Lightning Type이 없는 템플릿의 액션에는 StructuredResponse가 없었습니다. 도움말의 Flow 액션 문서에는 아직 StructuredResponse가 없으므로, 문서보다 이 출력 목록을 봅니다.

3. urgency로 분기합니다

액션 아래에 Decision을 더하고 조건의 Resource를 고릅니다. 액션 출력의 StructuredResponse를 펼치면 Lightning Type의 필드 넷이 보입니다.

StructuredResponse의 필드

결과(Outcome) 이름은 "긴급도 높음"으로 하고, 조건은 urgency Equals 높음으로 둡니다.

urgency 조건

주의

Lightning Type의 Data Type에는 값 목록을 정하는 유형이 없어, 높음·보통·낮음은 지시문과 필드 설명으로만 부탁합니다. 이 Flow의 기본 경로에는 보통·낮음과 함께 모델이 돌려준 다른 값도 들어갑니다. 정해진 값 밖의 응답을 따로 다루려면 보통과 낮음 결과도 만들고, 남는 기본 경로를 "판정하지 못함"으로 둡니다.

4. Debug로 확인합니다

Flow를 저장하고 Debug를 누른 뒤 입력 변수에 문의를 골라 실행합니다. 액션 내역의 structuredResponse에 필드별 값이 보입니다.

Debug의 structuredResponse

이 문의의 urgency는 "보통"이라, Decision은 긴급도 높음이 아닌 기본 경로를 골랐습니다.

Decision이 고른 경로

Debug 내역에는 urgency_set 같은 항목이 함께 보이지만, Flow에서 고를 수 있는 것은 필드 넷입니다.

그림으로 쉽게 보는 요약

참고 문서

Agentforce | Flow 병합 필드로 열린 문의 데이터를 프롬프트에 반영하는법

Luka.dev — Fri, 16 Oct 2026 14:26:50 +0900

안녕하세요, 루카입니다. 오늘은 Flow로 연락처의 열린 문의만 골라, 문의 내용과 함께 프롬프트 템플릿에 넣어 보겠습니다.

Template-Triggered Prompt Flow는 프롬프트 템플릿이 실행될 때마다 함께 실행되어, Flow가 만든 지시문을 템플릿에 넣어 주는 Flow입니다.

관련 목록 병합 필드에는 닫힌 문의도 들어가고 페이지 레이아웃에 있는 열만 담기므로, 열린 문의의 내용(Description)까지 넣으려면 Flow로 직접 골라야 합니다.

준비할 것

템플릿과 요약 필드: 연락처의 요약 필드에 붙여 쓰는 Field Generation 템플릿이 있어야 합니다. 이 글은 AF-04 글에서 만든 템플릿의 새 버전을 만듭니다.
권한: Flow를 만들려면 Manage Flow 권한이, 템플릿을 고치려면 Prompt Template Manager 권한 집합(또는 Customize Application 권한)이 필요합니다.
시험 데이터: 열린 문의와 닫힌 문의가 함께 연결된 연락처를 하나 준비합니다. 열린 문의의 Description에는 제목에 없는 내용을 적어 둡니다.

완료 확인: 연락처 화면에서 받은 요약 초안에 열린 문의의 Description 내용이 들어 있고 닫힌 문의가 없으면 끝입니다.

Flow 만들기

Flow는 템플릿이 넘긴 연락처로 열린 문의를 조회하고, Add Prompt Instructions 요소로 문의마다 상태·제목·내용을 한 줄씩 씁니다.

1. Template-Triggered Prompt Flow를 만듭니다

Setup의 Flows에서 New Flow를 누르고, Autolaunched 범주에서 Template-Triggered Prompt Flow 카드를 고른 뒤 Create를 누릅니다. 템플릿에 넣을 수 있는 Flow는 이 유형뿐입니다.

Template-Triggered Prompt Flow 카드

2. Start에서 템플릿 유형과 오브젝트를 고릅니다

Select Input Type에서 Automatic Inputs를 고르고, Prompt Template Type은 Field Generation Template Capability, Object는 Contact를 고릅니다. 목록에 같은 이름이 두 줄 있으면 Object 칸이 나타나는 첫 줄을 고릅니다.

Start의 입력 유형, 템플릿 유형, 오브젝트

Object가 템플릿의 오브젝트와 같아야 이 Flow를 템플릿에 넣을 수 있습니다. 이렇게 고르면 템플릿이 넘긴 연락처를 Flow 안에서 Prompt Template Input으로 읽습니다.

주의

샌드박스에서 만들어 다른 org로 배포할 계획이면 Automatic Inputs 대신 Manual Inputs로 만듭니다. 도움말은 Automatic Inputs Flow를 참조하는 템플릿은 배포에 실패한다고 안내합니다.

3. 연락처의 열린 문의를 조회합니다

Start 아래에 Get Records를 더하고 Object는 Case를 고릅니다. 이 글에서는 라벨을 "열린 문의 조회", API 이름을 Get_Open_Cases로 했습니다. 조건은 두 줄입니다.

Contact ID Equals Prompt Template Input > Contact > Contact ID
Closed Equals False

How Many Records to Store는 All records를 고릅니다. How to Store Record Data를 Automatically store all fields로 두면 Description도 함께 저장됩니다.

열린 문의 조회 조건

Closed는 문의가 닫혔는지 나타내는 표준 필드라, 닫힌 상태의 이름을 몰라도 거를 수 있습니다.

4. 문의마다 지시문을 한 줄씩 씁니다

Get Records 아래에 Decision을 더합니다. Yes 결과(Outcome)에는 Get Records로 조회한 문의 목록이 Is Null False라는 조건을 둡니다. 기본 결과(Default Outcome)의 이름은 No로 바꿉니다.

No 경로: Add Prompt Instructions 요소를 더하고 Prompt Instructions 칸에 "열린 문의가 없습니다."를 씁니다. 열린 문의가 없어도 병합 필드가 비지 않게 합니다.
Yes 경로: 조회한 문의 목록을 도는 Loop를 더하고, For Each 경로에 Add Prompt Instructions 요소를 하나 더 둡니다. 이 글의 Loop는 라벨 "문의마다", API 이름 Each_Case입니다.

Loop 안의 요소에는 Resource Picker로 현재 문의의 필드를 넣어 아래 한 줄을 씁니다. Each_Case 자리에는 직접 지은 Loop의 API 이름이 들어갑니다. 화면 폭에 맞춰 줄을 나눴고, 실제로는 한 줄입니다.

- {!Each_Case.Status}:
{!Each_Case.Subject} /
{!Each_Case.Description}

Loop 안의 지시문

Loop가 돌 때마다 이 요소가 실행되어 앞의 글 뒤에 한 줄씩 이어 붙습니다. Flow가 끝나면 모인 글이 템플릿으로 넘어갑니다. 이번 미리보기에서는 문의 사이에 줄바꿈이 저절로 들어가, 줄바꿈을 따로 넣지 않았습니다.

5. Debug로 확인하고 활성화합니다

저장한 뒤 Debug를 누르고 RelatedEntity 칸에서 연락처를 골라 실행합니다. 결과의 $Output.Prompt에 열린 문의 두 건이 차례로 쌓였는지 봅니다. Debug 화면에서는 두 건이 한 문단으로 이어져 보입니다.

Debug 결과의 지시문

Debug는 Flow만 실행하고 LLM은 부르지 않습니다. 내역에서는 Add Prompt Instructions 요소가 Assignment로 표시됩니다.

Prompt Builder에는 활성 Flow만 보이므로, 확인이 끝나면 Activate를 누릅니다.

활성화한 Flow

템플릿에 넣기

쓰던 템플릿은 새 버전을 만들어, 관련 목록 병합 필드를 지우고 그 자리에 Flow 병합 필드를 넣습니다.

1. 새 버전을 만듭니다

활성 버전은 고칠 수 없으므로 새 버전에서 고칩니다(AF-05 글). Prompt Builder에서 템플릿을 열고 Save As 메뉴의 Save as a New Version을 누릅니다. 누르는 즉시 새 버전(이 글에서는 버전 3)이 저장되고 편집 화면도 그 버전으로 바뀝니다.

2. 관련 목록 병합 필드를 Flow로 바꿉니다

템플릿 지시문에서 Related List:Contact.Cases 병합 필드를 지웁니다. 그 자리에서 Insert Resource를 누르거나 @를 친 뒤, Flows에서 방금 활성화한 Flow를 고릅니다.

Flows 목록의 새 Flow

3. 지시문을 고치고 저장합니다

Flow가 닫힌 문의를 이미 걸렀으므로 "상태가 Closed 인 문의는 빼고 씁니다." 줄을 지웁니다. '- 상태: 제목' 형식으로 한 줄씩 쓰라던 줄은 내용 한 문장을 더하도록 바꾸고 Save를 누릅니다.

당신은 온라인 학원의
상담 담당자입니다.
아래 수강생의 문의 목록을
읽고, 아직 닫히지 않은
문의를 한 문단으로
요약하세요.

문의 목록: (Flow)

지시:
- 한국어로 300자 이내로
  씁니다.
- 문의마다 '- 상태: 제목'
  한 줄을 쓰고, 다음 줄에
  문의 내용을 한 문장으로
  줄여 씁니다.
- 제목 앞의 LUKA_ 는
  쓰지 않습니다.
- 목록에 없는 내용은
  지어내지 않습니다.

화면 폭에 맞춰 줄을 나눴습니다. LUKA_ 줄은 시험 데이터의 제목 앞 글자를 빼려고 넣은 줄입니다.

"(Flow)" 자리에는 Flows:LUKA_028 열린 문의 가져오기 병합 필드가 들어갑니다. 버전 3은 저장만 했으므로 아직 비활성입니다.

버전 3의 지시문

주의

템플릿이 참조하는 Flow의 입력(예: Start의 입력 유형과 오브젝트)을 바꾸지 않습니다. 도움말은 입력을 바꾸면 템플릿이 동작하지 않고 새 버전도 저장할 수 없다고 안내합니다.

미리보기 비교

미리보기의 Resolved Prompt에는 Flow가 쓴 글이 그대로 들어가므로, 열린 문의만 내용과 함께 있는지 여기서 확인합니다.

Preview Settings에서 Resolved Prompt를 체크하고 Generate Response를 끈 뒤, 연락처를 골라 Preview를 누릅니다. Generate Response를 끄면 LLM을 부르지 않고 템플릿에 들어간 글만 보여 줍니다.

버전 3의 Resolved Prompt

같은 연락처를 버전 2(관련 목록)로 미리 본 결과와 견주면 아래와 같습니다.

활성화와 확인

버전 3을 활성화하면 페이지 설정을 바꾸지 않아도, 연락처 화면에서 받은 초안의 근거로 문의 내용이 들어갑니다.

1. 버전 3을 활성화합니다

Activate를 누르면 버전 3이 활성이 되고 버전 2는 비활성이 됩니다. 첫 클릭에 "Select a model." 오류가 나면 한 번 더 누릅니다.

활성화한 버전 3

2. 연락처 화면에서 초안을 받습니다

연락처 화면에서 요약 필드의 연필 아이콘을 누르고, 입력칸 오른쪽의 별 모양 아이콘을 누릅니다. 첫 클릭에 패널만 열리면 아이콘을 한 번 더 누릅니다. 초안이 나오면 Use를 누른 뒤 Save를 누릅니다.

문의 내용이 들어간 초안

이번 초안에는 "강남지점"과 "대전 물류센터에서 멈춰 있어" 같은 Description의 내용이 들어갔습니다. 닫힌 문의는 없었습니다.

이번 초안은 형식 줄의 '상태'를 New, Working 같은 값으로 바꾸지 않고 글자 그대로 썼습니다. 응답 형식을 고정하는 방법은 별도 글에서 다룰 예정입니다.

그림으로 쉽게 보는 요약

참고 문서