intercom-api

Intercom API

Intercom은 인앱 메시지, 이메일, 챗봇 등을 통해 고객 커뮤니케이션을 처리하는 고객지원 플랫폼이에요. Intercom API를 사용하면 워크스페이스에 있는 고객(컨택), 대화(컨버세이션), 메시지 데이터를 프로그래밍 방식으로 읽고 쓸 수 있어요. 여기서는 인증 방식과 핵심 리소스(컨택·컨버세이션·메시지), 그리고 OAuth와 웹훅까지 간단히 살펴볼게요. 코드와 명령은 공식 문서의 원문을 그대로 가져왔어요.

출처: 문서

본문

인증 (Authentication)

Intercom API를 사용하는 인증 방식은 두 가지가 있어요. Access Token은 자기 자신의 Intercom 워크스페이스 데이터에 접근할 때(프라이빗 앱) 쓰고, OAuth는 다른 사람의 Intercom 데이터에 접근하는 퍼블릭 앱을 만들 때 사용해요.

Access Token은 워크스페이스에 앱을 만들면 바로 발급되며, Developer Hub의 Configure > Authentication에서 찾을 수 있어요. 이 토큰은 비밀번호처럼 취급해야 해요 — 절대 제3자에게 주면 안 돼요.

토큰이 준비되면 요청 헤더에 Authorization: Bearer로 넣으면 돼요:

$ curl \
-s https://api.intercom.io/users/5321a20f72cdbb4192000013 \
-H 'Authorization:Bearer <access_token>' \
-H 'Accept:application/json'

OAuth

프라이빗 앱이라면 Access Token만으로 충분해서 OAuth를 설정할 필요가 없어요. 퍼블릭 앱을 만들 때는 Developer Hub의 Authentication 페이지에서 Use OAuth를 켠 뒤, client_id와 client_secret을 사용해요.

먼저 사용자를 아래 URL로 리다이렉트해서 인가 코드(Authorization Code)를 받아요:

https://app.intercom.com/oauth?client_id=___&state=___

인가 코드를 액세스 토큰으로 교환한 뒤, 이렇게 사용해요:

curl --request GET \
     --url 'https://api.intercom.io/me' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <ACCESS_TOKEN>'

import requests

url = "https://api.intercom.io/me"

headers = {
    "accept": "application/json",
    "authorization": "Bearer <ACCESS_TOKEN>"
}

response = requests.get(url, headers=headers)

print(response.text)

컨택 (Contacts)

컨택은 사용자(user) 또는 리드(lead)를 뜻해요. POST /contacts로 새 컨택을 만들 수 있어요:

$ curl https://api.intercom.io/contacts \
-X POST \
-H 'Authorization:Bearer <Your access token>' \
-H 'Accept:application/json'
-H 'Content-Type: application/json' -d

{
	"role": "user",
	"external_id": "25",
	"email": "[email protected]",
	"phone": "+1123456789",
	"name": "Joe Example",
	"avatar": "https://example.org/128Wash.jpg",
	"last_seen_at": 1571069751,
	"signed_up_at": 1571069751,
	"owner_id": 127,
	"unsubscribed_from_emails": false,
	"custom_attributes": {
		"paid_subscriber": true,
		"monthly_spend": 155.5,
		"team_mates": 1
	}
}

주요 필드로는 role(필수, user 또는 lead), external_id(role이 user일 때 필수), email, phone, name, custom_attributes 등이 있어요. 커스텀 속성은 워크스페이스에 이미 존재하는 데이터 속성에만 쓸 수 있어서, 새 속성이 필요하면 Data Attributes API로 먼저 만들어야 해요.

컨버세이션 (Conversations)

컨버세이션은 Intercom에서 사용자와 소통하는 단위예요. API로 대화를 시작하는 방법은 두 가지가 있어요.

  • 사용자 주도 대화 (user initiated): 사용자가 메시지를 보내 대화가 시작돼요.
  • 관리자 주도 대화 (admin initiated): 팀원이 한 명의 사용자에게 메시지를 보내 시작돼요.

주요 엔드포인트는 이래요:

  • GET /conversations — 전체 컨버세이션 목록 조회(페이징 지원)
  • POST /conversations — 사용자(또는 리드)가 시작한 컨버세이션 생성
  • GET /conversations/{id} — 단일 컨버세이션 상세 조회
  • POST /conversations/search — 속성 기반으로 컨버세이션 검색
  • POST /conversations/{id}/reply — 관리자나 컨택 입장에서 답장
  • POST /conversations/{id}/convert — 컨버세이션을 티켓으로 전환

참고할 점은, 컨택이 생성된 직후에는 바로 메시지를 보낼 수 없고 잠깐 지연이 생길 수 있어요. 이때는 404가 반환되니 잠시 후에 재시도하면 돼요. 또한 이메일을 구독 해지한 사용자에게 이메일을 보내려 하면 403과 함께 "This user is unsubscribed from emails" 메시지가 반환돼요.

메시지 (Messages)

메시지 API로 관리자(admin)가 시작한 메시지를 보낼 수 있어요. 메시지 종류는 인앱 메시지(inapp), 이메일, 또는 WhatsApp이 될 수 있어요. POST /messages 예시:

$ curl https://api.intercom.io/messages \
-X POST \
-H 'Authorization:Bearer <Your access token>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' -d {
  "message_type": "email",
  "subject": "Hey",
  "body": "Ponies, cute small horses or something more sinister?",
  "template": "plain",
  "from": {
    "type": "admin",
    "id": "394051"
  },
  "to": {
    "type": "user",
    "id": "536e564f316c83104c000020"
  }
}

주요 파라미터:

  • message_type — 필수. inapp 또는 email
  • subject — message_type: email일 때 필수(이메일 제목)
  • body — 필수. 메시지 본문(HTML과 plaintext 모두 지원)
  • template — message_type: email일 때 필수. plain 또는 personal
  • from — 필수. 발신자(항상 admin 타입)
  • to — 필수. 수신자(user 또는 lead 타입) 컨택

웹훅 (Webhooks)

웹훅은 워크스페이스에서 발생하는 이벤트(예: 컨택 생성, 인바운드 컨버세이션 수신, 아웃바운드 메시지 확인)에 대한 실시간 알림을 받는 방법이에요. 개발자는 Developer Hub에서 앱의 Webhooks 페이지에 엔드포인트 URL을 설정하고, 받고 싶은 **토픽(topic)**을 구독해요. 이벤트가 발생하면 구독한 토픽의 알림(notification)이 설정한 URL로 HTTP POST로 전송돼요.

웹훅 알림 페이로드 예시(ticket.created 토픽):

{
  type: 'notification_event',
  app_id: 'your-app-id',
  data: {
    type: 'notification_event_data',
    item: {
      type: 'ticket',
      id: '5',
      ticket_id: '1',
      ticket_attributes: [Object],
      ticket_state: 'submitted',
      ticket_state_internal_label: null,
      ...
    }
  }
}

주의할 점이 몇 가지 있어요:

  • 엔드포인트 URL은 HTTPS여야 하고, URL 검증을 위해 HEAD 요청을 받을 수 있어야 해요.
  • 15분 안에 엔드포인트가 1000개 이상의 연속 HTTP 에러를 반환하면 알림이 15분간 일시 중지돼요. 7일 이상 에러가 계속되면 구독이 중단(suspend)돼요.
  • US 리전은 분당 최대 150,000 이벤트, EU·AU 리전은 분당 20,000 이벤트까지 우선 처리되고 그 이후에는 rate limit이 적용돼요.
  • 엔드포인트가 방화벽 뒤에 있다면 Intercom이 알림을 보내는 IP 대역을 allowlist에 추가해야 해요.

서버 (Servers)

API 서버는 리전별로 달라요:

  • 프로덕션: https://api.intercom.io
  • 유럽: https://api.eu.intercom.io
  • 호주: https://api.au.intercom.io

더 알아보기 (Learn more)