콘텐츠로 이동

연락처

연락처 커넥터로는 메일이나 초대를 보낼 때 이름으로 이메일 주소를 찾을 수 있습니다. 읽기만 하는 커넥터라서 연락처가 만들어지거나 바뀌거나 지워지는 일은 없고, 세 가지 백엔드가 같은 검색에 응답합니다.

백엔드 검색 대상 동작 환경
Apple 연락처 Mac의 연락처 앱에 있는 모든 계정(iCloud, Google, Exchange, 나의 Mac) macOS 데스크톱 앱
Google 연락처 Google 캘린더가 사용하는 Google 로그인의 내 연락처('기타 연락처'는 검색하지 않음) 모든 플랫폼과 헤드리스 서버
Microsoft 365 연락처 Microsoft 365 로그인의 Outlook 연락처(조직 디렉토리는 제외) 모든 플랫폼과 헤드리스 서버

검색할 때마다 다른 커넥터 호출과 마찬가지로 AI가 한 작업에 기록되는데, 검색한 이름과 검색 결과는 남지 않습니다(개인정보 참고).

연결하기

Google 연락처와 Microsoft 365 연락처는 이미 있는 로그인을 사용하지만, 해당 로그인만으로는 연락처 권한이 요청되지 않습니다. 연락처 추가는 동의 화면이 따로 뜨는 별도 단계라서, 예전에 연결해 둔 Google 캘린더나 Outlook 계정이 사용자 승인 없이 연락처에 접근하게 되는 일은 없습니다.

설정 > 커넥터의 연락처 카드에는 세 출처가 모두 들어 있고, 출처마다 연결됨, 연결 안 됨, 권한 없음, 준비 안 됨(기반이 되는 로그인이 없는 경우), 오류(상태를 확인하지 못한 경우), 주의 필요 중 하나로 상태가 표시됩니다. 카드의 상태는 출처 중 하나가 주의 필요나 오류이면 주의 필요나 오류로, 그렇지 않으면 연결된 출처의 이름으로 표시되고, Microsoft 365는 Microsoft 365에 로그인한 뒤에 카드에 나타납니다.

Apple 연락처

Apple 연락처는 Apple 캘린더 및 미리 알림과 같은 방식으로, 종류 contacts로 연결합니다. 먼저 접근을 허용해야 하는데, macOS의 권한 요청 창은 AI:GO가 처음 요청할 때, 그것도 사용자가 직접 요청했을 때만 나타납니다. 한 번 답한 뒤에는 선택이 시스템 설정 > 개인정보 보호 및 보안 > 연락처에 저장되고, 이어서 커넥터를 연결하면 됩니다. 계정은 Mac마다 하나이고, 계정 ID는 local입니다.

접근 권한이 없으면 연결과 검색이 모두 거절되고, 권한을 허용할 위치가 메시지로 안내됩니다. 어느 쪽에서도 권한 요청 창은 뜨지 않습니다. AI:GO가 연락처 앱의 계정 목록을 읽지 못할 때도 연결이 거절되는데, 해당 목록으로 이 Mac의 연락처를 구별하기 때문입니다. 이때 예전 연결은 그대로 남으니 다시 시도해 주세요. 연결을 해제해도 연락처 앱에는 아무 변화가 없습니다.

연락처 카드의 허용 버튼은 macOS에 접근을 요청하는 버튼입니다. 접근이 꺼져 있거나 제한되어 있으면 시스템 설정 열기 버튼이 개인정보 보호 및 보안 > 연락처를 바로 열어 주고, 두 버튼 모두 이 Mac의 데스크톱 앱에서만 표시됩니다. 연결 해제를 누르면 해제하기 전에 확인 창이 먼저 뜹니다.

Google 연락처

Google 연락처에는 설정 > 커넥터에 있는 Google 캘린더 커넥터의 Google 로그인이 같은 계정 이름 그대로 사용되므로, 먼저 Google 캘린더에 로그인한 뒤 아래 순서로 연락처를 추가합니다.

  1. Google 캘린더 로그인과 같은 OAuth 클라이언트 ID와 리디렉션 URI로 연락처 추가 단계를 시작합니다. 캘린더와 연락처를 함께 요청하면서 예전에 허용한 범위도 유지하는 동의 주소가 반환됩니다.
  2. 해당 주소를 열어 Google이 보여 주는 항목을 확인하고 허용해 주세요.
  3. Google이 보내 준 주소의 code를 붙여 넣어 단계를 마칩니다.
  4. Google 연락처를 연결합니다.

새 로그인은 Google이 캘린더와 연락처를 모두 허용했고, 이미 연결된 Google 계정과 같은 계정으로 로그인했을 때만 저장된 로그인을 대신합니다. Google 화면에서 연락처나 캘린더의 체크를 해제했다면 아무것도 저장되지 않아 Google 캘린더는 원래 로그인을 그대로 사용하고, 다른 Google 계정으로 로그인했다면 단계가 거절되어 아무것도 바뀌지 않습니다.

연락처 카드의 권한 추가를 누르면 Google 캘린더 카드의 OAuth 클라이언트 ID와 리디렉션 URI로 위 단계가 진행되는데, 동의 화면이 열리고 code를 붙여 넣을 칸이 나타나며, Google이 연락처를 허용했다면 Google 연락처까지 연결됩니다. 권한 추가는 Google 캘린더에 로그인한 뒤에 표시되고, 그전에는 Google 캘린더 카드로 가는 링크가 대신 보입니다. Google 연락처는 Google 캘린더 로그인을 사용하므로, Google 캘린더 로그인을 삭제하면 Google 연락처 연결도 함께 해제됩니다.

Google Cloud 콘솔의 OAuth 클라이언트에는 People API가 켜져 있고, 동의 화면에 contacts.readonly 범위가 등록되어 있어야 합니다.

연락처를 추가하지 않은 계정에서 검색하면 CONTACTS_PERMISSION_REQUIRED로 응답됩니다.

Microsoft 365 연락처

Microsoft 365 연락처는 Microsoft 365에 로그인할 때 메일, 캘린더와 함께 연결되지만, 해당 로그인에는 Contacts.Read 권한이 없으므로 권한을 추가하기 전까지 검색하면 CONTACTS_PERMISSION_REQUIRED로 응답됩니다.

연락처 추가는 같은 계정으로 다시 한 번 진행하는 기기 코드 로그인입니다. 계정에 이미 있는 권한에 Contacts.Read가 더해져 요청되고, 같은 애플리케이션(클라이언트) ID와 테넌트가 사용되며, 확인과 취소는 첫 로그인과 같은 방식으로 합니다. 로그인이 끝나면 메일, 캘린더, 연락처가 원래 대기 시간 설정 그대로 다시 연결됩니다. 다른 Microsoft 계정으로 로그인했다면 different_account 오류로 끝나고 아무것도 저장되지 않습니다. 계정 식별 정보 없이 저장된 Microsoft 365 로그인으로는 연락처를 추가할 수 없으니, 먼저 Microsoft 365에 다시 로그인해 주세요.

설정에서는 메일과 캘린더가 연결된 뒤 Microsoft 365 카드나 연락처 카드의 연락처 접근 추가하기로 해당 단계를 시작합니다. Microsoft 365 연락처는 계정과 함께 연결되고 해제됩니다.

연락처 접근을 추가하려면 Microsoft Entra 앱 등록의 API 사용 권한에 위임된 Contacts.Read 권한을 추가해 주세요.

다시 시작한 뒤

연결한 출처는 앱을 다시 시작해도 데스크톱과 헤드리스 서버 모두에서 연결된 채로 유지되고, 시작할 때 권한 요청 창이나 로그인 창이 뜨는 일은 없습니다. Apple 연락처는 macOS에서 접근이 여전히 허용된 경우에만 다시 연결되고, Google 연락처는 키체인에 보관된 Google 로그인과 계정 식별 정보로, Microsoft 365 연락처는 계정 로그인으로 메일, 캘린더와 함께 다시 연결됩니다. 접근이 꺼졌거나 키체인에서 로그인 정보가 사라졌거나 연락처 앱이 없는 서버라서 다시 연결되지 못한 출처는, 다시 연결하거나 연결을 해제할 때까지 연락처 카드에 해결 방법과 함께 주의 필요로 표시됩니다. Microsoft 365의 메일과 캘린더는 다시 연결되었지만 연락처는 연결되지 않은 경우에는 여기의 Microsoft 365 영역이나 Microsoft 365 카드에서 연락처 접근 다시 추가하기를 누르면 됩니다.

검색어는 이름이나 이름의 일부로, 2자 이상 100자 이하여야 합니다. 검색어에 @가 들어 있으면 해당 주소와 정확히 일치하는 연락처가 검색되고, 그렇지 않으면 Apple 연락처와 Microsoft 365에서는 이름이나 성의 앞부분이 일치하는 연락처가, Google에서는 Google 자체 연락처 검색의 결과가 반환됩니다.

검색 결과에는 표시 이름, 라벨(집, 직장, 직접 입력한 라벨)이 붙은 이메일 주소, 조직이 있으면 조직 이름이 담기고, 전화번호, 우편 주소, 생일, 메모, 사진은 검색 결과에 포함되지 않고 애초에 읽히지도 않습니다. 검색은 주소를 찾는 용도이므로 이메일 주소가 없는 사람은 결과에서 빠집니다.

따로 정하지 않으면 10명까지 반환되고, 아무리 많이 요청해도 25명을 넘지 않으며, 조건에 맞는 사람이 더 있으면 결과에 truncated가 표시됩니다.

검색에는 승인이 필요 없습니다. 거버넌스에서 검색마다 domain:contacts와 pii 태그가 붙으므로, 정책 하나로 모든 연락처 백엔드에 적용할 수 있습니다.

개인정보

검색 결과는 다른 사람에 대한 정보라서, 감사 로그에는 다른 커넥터보다 적은 내용만 남습니다.

  • 검색한 이름은 짧은 해시로만 남아, 같은 검색끼리는 이어서 볼 수 있지만 이름 자체는 저장되지 않습니다.
  • 검색 결과는 남지 않고 결과의 지문만 남으며, 요약에는 '2 matches'처럼 개수만 표시됩니다.
  • 실패한 검색은 오류 문구를 남기지 않고, 오류 메시지에도 검색한 이름이 들어가지 않습니다.

연락처 항목도 다른 항목과 같은 감사 로그 보존 정책을 따르고, 로그에는 연락처나 주소, 검색어가 기록되지 않습니다.

서버나 다른 플랫폼에서

경로는 모든 환경에 존재합니다. 연결할 연락처 앱이 없는 환경(헤드리스 서버, Linux, Windows, 커넥터 없이 빌드한 macOS)에서는 Apple을 지정한 검색과 Apple 연락처 연결이 CONNECTOR_HOST_UNSUPPORTED 코드와 함께 HTTP 412로 응답됩니다. Google과 Microsoft 365는 이런 환경에서도 데스크톱과 똑같이 동작하고, 에어갭 모드에서는 둘 다 요청을 보내기 전에 거절됩니다.

REST API

관리 API에서는 같은 호출이 /api/v1 아래에서 제공됩니다. 검색과 Google 상태 조회에는 agent_read 범위가, 나머지에는 agent_write 범위가 필요합니다.

메서드 경로 동작
POST /connectors/contacts/search 검색(accountId, provider, query, limit)
POST /connectors/contacts/google/consent Google 연락처 추가 단계 시작
POST /connectors/contacts/google/consent/complete code로 단계 마무리
POST /connectors/contacts/google/activate Google 연락처 연결
POST /connectors/contacts/google/deactivate Google 연락처 연결 해제(Google 로그인은 유지)
GET /connectors/contacts/google/accounts/{accountId} 로그인 여부, 연락처 추가 여부, 연결 여부
POST /connectors/contacts/microsoft/consent Microsoft 연락처 추가 단계 시작

백엔드는 "provider"에 "apple"(계정 local), "google", "microsoft" 중 하나를 지정합니다. Apple 연락처는 /connectors/apple/activate에 {"kind": "contacts"}를 보내 연결하고, 권한은 /connectors/apple/permissions의 contacts 필드로 확인합니다. Microsoft 단계는 /connectors/microsoft/sign-in/poll과 /connectors/microsoft/sign-in/cancel로 확인하거나 취소하고, /connectors/microsoft/accounts/{accountId}의 contactsGranted에서 추가 여부를 볼 수 있습니다.