상담문의(리드) 연동

사이트의 문의 폼 제출을 RootTale로 보내면 어드민 CRM(받은문의) 에서 관리됩니다. 블로그 조회와 같은 API 키 하나로 동작하며, 키가 테넌트를 식별하므로 별도 식별자가 필요 없습니다. 개인정보(이름·연락처 등)는 서버에서 암호화 저장됩니다.

권장 — Next.js Server Action

// lib/actions/submit-contact.ts
"use server";

import { submitInquiry } from "@roottale/cms-client/server";

export interface ContactState {
  status: "idle" | "success" | "error";
  message?: string;
  errors?: Partial<Record<"name" | "phone" | "privacyConsent", string>>;
}

export async function submitContact(
  _prev: ContactState,
  formData: FormData,
): Promise<ContactState> {
  const name = (formData.get("name") as string | null)?.trim() ?? "";
  const phone = (formData.get("phone") as string | null)?.trim() ?? "";
  const message = (formData.get("message") as string | null)?.trim() ?? "";
  const privacyConsent = formData.get("privacyConsent") !== null;

  const errors: ContactState["errors"] = {};
  if (!name) errors.name = "이름을 입력해주세요.";
  if (!phone || phone.length < 7) errors.phone = "연락처를 입력해주세요.";
  if (!privacyConsent) errors.privacyConsent = "개인정보 수집·이용에 동의해주세요.";
  if (Object.keys(errors).length > 0) {
    return { status: "error", message: "필수 항목을 입력해주세요.", errors };
  }

  const result = await submitInquiry({
    apiKey: process.env.ROOTTALE_API_KEY!,
    baseUrl: process.env.ROOTTALE_API_BASE,
    fields: {
      vertical: "tax", // consulting | medical | tax | legal
      contactName: name,
      businessName: name, // 사업체명 미수집 폼이면 이름으로 대체
      email: `noemail-${name}@example.invalid`, // 이메일 미수집 폼이면 placeholder
      phone, // 자동으로 010-1234-5678 형태 포맷됨
      message: message || undefined,
      privacyConsent: true, // 사용자가 명시 동의한 경우에만 true
    },
  });

  if (result.ok) {
    return { status: "success", message: "상담 문의가 접수되었습니다." };
  }
  return { status: "error", message: result.message };
}

클라이언트 폼에서는 useActionState(submitContact, { status: "idle" })로 연결합니다.

필드 레퍼런스 (SubmitInquiryFields)

extras에 개인정보가 담길 수 있으므로 폼의 동의 고지에 수집 항목을 반영하세요.

유입 어트리뷰션 (attribution)

문의가 어느 글·검색·단축링크/QR에서 왔는지를 CRM에 표시하려면 두 줄만 추가하면 됩니다. RootTale 비콘이 방문자의 first-touch(처음 도착한 경로·rt_src 토큰·utm·외부 referrer 호스트명)를 30일간 기억하며, readAttribution()(브라우저 전용, @roottale/cms-client/attribution)으로 읽습니다. 식별자가 아니므로 개인정보가 아닙니다.

1. 폼 안에 hidden input 추가 (클라이언트 컴포넌트):

"use client";
import { useEffect, useState } from "react";
import { readAttribution } from "@roottale/cms-client/attribution";

export function AttributionField() {
  const [value, setValue] = useState("");
  useEffect(() => {
    const attribution = readAttribution();
    if (attribution) setValue(JSON.stringify(attribution));
  }, []);
  return <input type="hidden" name="attribution" value={value} />;
}
// 사용: <form action={...}> ... <AttributionField /> ... </form>

1. Server Action에서 파싱해 전달:

import { parseAttributionJson, submitInquiry } from "@roottale/cms-client/server";

const attribution = parseAttributionJson(formData.get("attribution")); // 깨진 값은 null
const result = await submitInquiry({
  apiKey: process.env.ROOTTALE_API_KEY!,
  fields: { /* ...표준 필드 */ attribution },
});

InquiryAttribution 형태 (모든 필드 선택):

직접 HTTP 연동 시에는 같은 값을 attr_landing_path, attr_rt_src, attr_utm_source, attr_utm_medium, attr_utm_campaign, attr_referrer, attr_first_touch_at 폼 필드로 보내면 됩니다.

에러 처리

submitInquiry는 throw 하지 않고 구조화된 결과를 반환합니다:

type SubmitInquiryResult =
  | { ok: true }
  | { ok: false; code: string | null; message: string }; // message = 한국어 사용자 메시지

대안 — RootTaleLeadForm 컴포넌트

자체 폼 없이 빠르게 붙일 때는 @roottale/cms-renderer-next의 RootTaleLeadForm(RSC, HTML form)을 사용할 수 있습니다. 디자인·검증을 통제하려면 위의 Server Action 방식을 권장합니다.

raw HTTP로 직접 연동(비 JS 스택)하려면 api-reference.md의 POST /v1/public/inquiries를 참고하세요.