Sidetalk사용자 가이드
사이드톡 홈페이지 ↗대시보드 열기
가이드 홈사용자 가이드

고객 연락처 생성/업데이트 API

6 분 읽기가이드 기준일: 2026. 10. 14.노션 원문 보기 ↗

목적

이 API는 외부 서비스의 회원가입, 예약, 문의 폼 등에서 수집한 고객 정보를 Sidetalk 고객 연락처에 생성하거나 업데이트합니다.
동일한 memberId가 이미 존재하면 기존 고객 정보를 업데이트하고, 존재하지 않으면 새 고객 정보를 생성합니다.

URL

JavaScript
💡https://api.sidetalk.ai/v1/users

HTTP 메서드

POST

헤더

헤더값설명
Content-Typeapplication/json요청 본문이 JSON 형식임을 나타냅니다.
AuthorizationBearer <api_key>Sidetalk 대시보드에서 설치하기 메뉴에 제공된 API 키를 사용하세요.

본문

파라미터타입필수설명
userInfoIdNumber/String조건부 필수Sidetalk 고객정보 ID입니다. 기존 고객 연락처를 직접 업데이트할 때 사용합니다.
memberIdString조건부 필수외부 서비스의 회원 고유 ID입니다. 동일한 memberId가 있으면 기존 고객 연락처를 업데이트합니다.
sessionIdString조건부 필수채팅 세션 ID입니다. 비회원 채팅 세션 기준으로 고객 연락처를 생성/업데이트할 때 사용합니다.
userNameString아니요고객 이름입니다. Sidetalk 고객 정보의 userName에 저장됩니다.
userEmailString아니요고객 이메일입니다. Sidetalk 고객 정보의 userEmail에 저장됩니다.
userPhoneString아니요고객 전화번호입니다. Sidetalk 고객 정보의 userPhone에 저장됩니다.
customerMemoryString아니요고객 메모입니다.
extraFieldsObject아니요추가 고객 정보 항목입니다. key는 Sidetalk 대시보드 고객정보 설정의 항목 코드와 동일해야 합니다.
customerAliasString아니요고객 이름(userName)과 별도로 관리하는 고객 별칭입니다. 생략하면 기존 별칭을 유지합니다.
userInfoId, memberId, sessionId 중 하나는 반드시 포함해야 합니다.

extraFields 사용 방법

Sidetalk 고객정보 설정에서 추가 항목을 만든 경우, 해당 항목의 항목 코드를 extraFields의 key로 사용합니다.
예를 들어 고객정보 설정에 다음 항목이 있다면:
항목 이름항목 코드
회사 이름company_name
요청 본문은 다음처럼 전송합니다.
JavaScript
{
  "extraFields": {
    "company_name": "코스모스팜"
  }
}

요청 예시


회원 고객 생성/업데이트
memberId를 기준으로 고객 연락처를 생성하거나 업데이트합니다. 회원가입, 로그인 회원 정보 동기화, 외부 서비스 회원 정보 연동에 사용합니다.
JavaScript
curl -X POST https://api.sidetalk.ai/v1/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{
      "memberId": "user_123",
      "userName": "홍길동",
      "userEmail": "hong@example.com",
      "customerAlias": "VIP 고객",
      "userPhone": "01012345678",
      "customerMemory": "VIP 고객",
      "extraFields": {
          "company_name": "코스모스팜"
      }
  }'

비회원 고객 생성/업데이트
sessionId를 기준으로 고객 연락처를 생성하거나 업데이트합니다.
채팅 세션, 비회원 예약, 비회원 문의 폼처럼 회원 ID가 없는 고객 정보 연동에 사용합니다.
JavaScript
curl -X POST https://api.sidetalk.ai/v1/users \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${API_KEY}" \
-d '{
		"sessionId": "chat_session_abc123",
		"userName": "홍길동",
		"customerAlias": "VIP 고객",
		"userEmail": "hong@example.com",
		"userPhone": "01012345678",
		"customerMemory": "VIP 고객",
		"extraFields": {
		"company_name": "코스모스팜"
	}
}'
기존 고객 연락처 직접 업데이트
Sidetalk 고객정보 ID를 알고 있는 경우 userInfoId로 직접 업데이트할 수 있습니다.
JavaScript
curl -X POST https://api.sidetalk.ai/v1/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{
      "userInfoId": 123,
      "userName": "홍길동",
      "customerMemory": "상담 후 VIP 고객으로 변경"
  }'

응답 본문

JavaScript
{
  "success": true,
  "data": {
    "siteId": 1,
    "userInfoId": 123,
    "sessionId": "",
    "memberId": "user_123",
    "userName": "홍길동",
    "customerAlias": "VIP 고객",
    "userEmail": "hong@example.com",
    "userPhone": "821012345678",
    "userPhoneCountryCode": "82",
    "customerMemory": "{\"_sidetalk_customer_profile\":\"1\",\"memo\":\"VIP 고객\",\"extra_fields\":{\"company_name\":\"코스모스팜\"}}",
    "isManual": "1",
    "createdAt": "20260527143000",
    "updatedAt": "20260527143000"
  }
}
- userPhone은 저장 시 숫자만 정규화되어 저장될 수 있습니다. 예: 01012345678 → 821012345678 - userPhoneCountryCode가 함께 저장될 수 있습니다. 예: 82

응답 필드 설명

필드타입설명
successBoolean요청 성공 여부입니다.
dataObject저장된 고객정보 데이터입니다.
data.userInfoIdNumberSidetalk 고객정보 ID입니다.
data.memberIdString요청한 외부 회원 고유 ID입니다.
data.sessionIdString연결된 채팅 세션 ID입니다.
data.userNameString저장된 고객 이름입니다.
data.userEmailString저장된 고객 이메일입니다.
data.userPhoneString저장된 고객 전화번호입니다.
data.customerMemoryString고객 메모와 추가 항목 데이터입니다.
data.userPhoneCountryCodeString저장된 전화번호 국가번호입니다.
data.isManualString직접 입력 여부입니다. 1 또는 0입니다.
data.createdAtString생성 일시입니다.
data.updatedAtString수정 일시입니다.

오류 응답

JavaScript
{
  "success": false,
  "error": "userInfoId, memberId, or sessionId is required."
}
JavaScript
{
  "success": false,
  "error": "At least one customer field is required."
}
JavaScript
{
  "success": false,
  "error": "Name must be at least 2 characters."
}
JavaScript
{
  "success": false,
  "error": "Invalid phone format."
}
필드타입설명
successBoolean요청 실패 여부입니다.
errorString오류 메시지입니다.

예시 이미지

원본 가이드 이미지

참고 사항

  • memberId와 sessionId를 함께 보내면, 비회원 채팅 세션으로 쌓인 CRM 활동이 해당 memberId 고객 연락처로 연결될 수 있습니다.
  • 이 API로 저장된 고객 연락처는 CRM 활동 이력의 기준 고객으로 사용됩니다.
  • 외부 API로 저장된 연락처는 고객 연락처 화면에서 외부 API 연동 이력으로 확인할 수 있습니다.
  • 동일한 userInfoId가 있으면 해당 고객 연락처를 직접 업데이트합니다.
  • 동일한 sessionId가 있으면 해당 비회원 세션의 고객 연락처를 생성하거나 업데이트합니다.
  • 하위 호환 및 외부 서비스 연동 편의를 위해 다음 별칭 필드도 지원됩니다.
  • customerAlias는 userName과 별도로 저장되는 고객 별칭입니다.
  • customerAlias를 생략하면 기존 별칭은 변경되지 않습니다.
대표 필드지원 별칭
userInfoId user_info_id, id
memberId member_id, wpUserId, wp_user_id, userId, user_id
sessionId session_id
userName user_name
userEmail user_email
userPhone user_phone
userPhoneCountryCode user_phone_country_code
customerMemory customer_memory
extraFields extra_fields
isManual is_manual
customerAliascustomer_alias