Contact API
Contact API로 연락처 및 연락처 태그를 관리할 수 있다.
Contact API를 호출하려면 구성원 계정 또는 서비스 계정으로 인증하여 얻은 Access Token이 필요하다.
API scope는 contact
, contact.read
이다.
연락처 관리
연락처에는 '고객/거래처 연락처'와, 'LINE 사용자' 또는 '다른 회사의 NAVER WORKS 사용자'를 가리키는 '외부 대화 상대'가 있다.
Contact API로는 '고객/거래처 연락처'만 생성할 수 있다.
생성 시 연락처 접근 권한 모델(permission
)을 지정한다. permission
은 연락처 마스터 구성원 ID(masterUserId
)와 연락처 접근 가능 범위(accessibleRange
)를 포함한다. accessibleRange
를 ALL
로 지정하면 도메인 전체 구성원이 접근할 수 있다.
연락처 이름 정보(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
)로 판단할 수 있다.
'고객/거래처 연락처'일 경우 linkedExternalUser
는 null
이며, '외부 대화 상대'일 경우 linkedExternalUser
와 type
에 값이 지정된다.
같은 '외부 대화 상대'가 다른 사용자의 주소록에 등록되면 다른 연락처로 취급된다.
'외부 대화 상대' 연락처의 마스터가 변경되면, 변경된 마스터의 사용자 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 Request | Description |
---|---|
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 Request | Description |
---|---|
POST /contact-tags | 회사 연락처 태그 생성 |
'사용자 태그'는 다음 API로 관리한다.
HTTP Request | Description |
---|---|
POST /users/{userId}/contact-tags | 구성원 단위의 연락처 태그 생성 |
GET /users/{userId}/contact-tags | 구성원이 접근 가능한 태그 목록 |
연락처 태그는 다음 API로 관리한다.
HTTP Request | Description |
---|---|
GET /contact-tags | 연락처 태그 목록 조회 |
GET /contact-tags/{contactTagId} | 연락처 태그 조회 |
PUT /contact-tags/{contactTagId} | 연락처 태그 수정 |
PATCH /contact-tags/{contactTagId} | 연락처 태그 부분 수정 |
DELETE /contact-tags/{contactTagId} | 연락처 태그 삭제 |