Contact API

Contact API로 연락처 및 연락처 태그를 관리할 수 있다.

Contact API를 호출하려면 구성원 계정 또는 서비스 계정으로 인증하여 얻은 Access Token이 필요하다.
API scope는 contact, contact.read이다.

연락처 관리

연락처에는 '고객/거래처 연락처'와, 'LINE 사용자' 또는 '다른 회사의 NAVER WORKS 사용자'를 가리키는 '외부 대화 상대'가 있다.

Contact API로는 '고객/거래처 연락처'만 생성할 수 있다.
생성 시 연락처 접근 권한 모델(permission)을 지정한다. permission은 연락처 마스터 구성원 ID(masterUserId)와 연락처 접근 가능 범위(accessibleRange)를 포함한다. accessibleRangeALL로 지정하면 도메인 전체 구성원이 접근할 수 있다.
연락처 이름 정보(contactName)도 반드시 지정해야 하며, 성(lastName) 또는 이름(firstName) 중 한 가지는 필수로 입력해야 한다.
또한, 연락처 전화 목록(telephones) 또는 연락처 메일 목록(emails) 중 하나는 필수로 입력해야 한다.

{
"permission": {
"masterUserId": "userf7da-f82c-4284-13e7-030f3b4c756x",
"accessibleRange": "ALL"
},
"contactName": {
"lastName": "고객",
"firstName": "연락처"
},
"telephones": [
{
"type": "CELLPHONE",
"telephone": "1234-5678",
"primary": true
}
]
}

응답받은 연락처가 '고객/거래처 연락처'인지 '외부 대화 상대'인지는 외부 대화 상대 ID(linkedExternalUser)로 판단할 수 있다.
'고객/거래처 연락처'일 경우 linkedExternalUsernull이며, '외부 대화 상대'일 경우 linkedExternalUsertype에 값이 지정된다.
같은 '외부 대화 상대'가 다른 사용자의 주소록에 등록되면 다른 연락처로 취급된다.
'외부 대화 상대' 연락처의 마스터가 변경되면, 변경된 마스터의 사용자 ID가 buddyUserIds에 추가된다.

{
"contactId": "81c6c568-e090-4d9e-549f-049dea60cbc7",
"contactName": {
"lastName": "작업",
"firstName": "사용자"
},
"linkedExternalUser": {
"id": "32deb574-f7a9-4973-44c9-040944411275",
"type": "WORKS",
"buddyUserIds": [
"0c9cf0c3-83ba-48ed-10eb-043fcd624244"
]
}
...
}

다음 API로 연락처를 관리할 수 있다.

HTTP RequestDescription
POST /contacts연락처 생성
GET /contacts연락처 목록 조회
GET /users/{userId}/contacts구성원이 접근 가능한 연락처 목록 조회
GET /contacts/{contactId}연락처 정보 조회
PUT /contacts/{contactId}연락처 수정
PATCH /contacts/{contactId}연락처 부분 수정
DELETE /contacts/{contactId}연락처 삭제
DELETE /contacts/{contactId}/forcedelete연락처 즉시 삭제
POST /contacts/{contactId}/photo연락처 사진 업로드
GET /contacts/{contactId}/photo연락처 사진 조회
DELETE /contacts/{contactId}/photo연락처 사진 삭제

연락처 태그 관리

태그는 연락처를 분류하는 기능이다.
태그에는 전체 구성원이 확인할 수 있는 '회사 태그'와 생성한 사용자만 볼 수 있는 '사용자 태그'가 있다.

태그 생성 시 태그 이름(contactTagName)을 지정한다.

{
"contactTagName": "태그"
}

태그 조회 시 응답값 태그 타입(type)으로 '회사 태그'인지 '사용자 태그'인지 구분할 수 있다.

{
"contactTagId": "ctag2a81-94b6-4642-6903-03aa7977da91",
"contactTagName": "회사 태그",
"type": "COMPANY"
}

'회사 태그'는 다음 API로 생성한다.

HTTP RequestDescription
POST /contact-tags회사 연락처 태그 생성

'사용자 태그'는 다음 API로 관리한다.

HTTP RequestDescription
POST /users/{userId}/contact-tags구성원 단위의 연락처 태그 생성
GET /users/{userId}/contact-tags구성원이 접근 가능한 태그 목록

연락처 태그는 다음 API로 관리한다.

HTTP RequestDescription
GET /contact-tags연락처 태그 목록 조회
GET /contact-tags/{contactTagId}연락처 태그 조회
PUT /contact-tags/{contactTagId}연락처 태그 수정
PATCH /contact-tags/{contactTagId}연락처 태그 부분 수정
DELETE /contact-tags/{contactTagId}연락처 태그 삭제