# Conversations API - 인바운드 메시지 추가 (연락처 ID 사용)

인바운드 메시지 추가 기능을 사용하면 대화 ID를 먼저 확인하지 않고도 연락처 ID만으로 대화(Conversations)에 인바운드 메시지를 게시할 수 있습니다. 이는 API 호출을 줄이고, 로직을 단순화하며, 최소한의 오버헤드로 메시지가 올바른 CRM 스레드에 표시되도록 보장합니다. 이 가이드를 통해 장점, 설정, 페이로드 구조, 스레딩 동작 및 모범 사례를 이해할 수 있습니다.

**중요**: HighLevel CRM 플랫폼의 완전한 REST API 문서는 여기서 찾을 수 있습니다. [HighLevel API Documentation - Send a new message](https://marketplace.gohighlevel.com/docs/ghl/conversations/send-a-new-message/index.html).

***

**목차**

* [연락처 기반 인바운드 메시지 추가란?](#연락처-기반-인바운드-메시지-추가란)
* [인바운드 메시지 추가의 주요 장점](#인바운드-메시지-추가의-주요-장점)
* [엔드포인트 개요 & 페이로드 (개념)](#엔드포인트-개요-페이로드-개념)
* [스레딩 & 연결 규칙](#스레딩-연결-규칙)
* [설정 & 요구사항](#설정-요구사항)
* [채널 고려사항 & 첨부파일](#채널-고려사항-첨부파일)
* [멱등성, 재시도 & 속도 제한](#멱등성-재시도-속도-제한)
* [오류 처리 & 일반적인 응답](#오류-처리-일반적인-응답)
* [테스트 & 검증](#테스트-검증)
* [자주 묻는 질문](#자주-묻는-질문)

## 연락처 기반 인바운드 메시지 추가란?

인바운드 메시지 추가는 연락처 ID를 받아 해당 대화에 새로운 인바운드 메시지를 게시합니다. 기존 스레드에 추가하거나 새로운 스레드를 생성합니다. 이를 통해 연락처를 이미 알고 있는 공급자, 웹훅 또는 가져오기에서 메시지를 수집할 때 통합이 더 빠르고 안정적이 됩니다.

* 연락처 ID + 채널 + 콘텐츠를 제공하면 시스템이 스레드 연결을 처리합니다.
* 일치하는 대화가 있으면 메시지가 추가되고, 없으면 새로 생성됩니다.
* 일반적인 채널(SMS/MMS, 이메일, 왓츠앱, 메신저, 인스타그램, 웹 채팅)에서 작동합니다.

![](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155064485147/original/wak6VQJHcXYmqMUzWxq_KbEj690GjHtGsQ.png?1770637957)

## 인바운드 메시지 추가의 주요 장점

이러한 장점은 네트워크 왕복 횟수 감소, 명확한 개발자 플로우, CRM에서의 더 나은 상담원 경험과 직접적으로 연결됩니다.

* API 호출 수 감소: 일반적인 인바운드 플로우에서 대화 조회/생성을 피할 수 있음
* 플로우 제어 단순화: "대화 존재 여부"에 대한 분기 로직 감소
* CRM UX 개선: 메시지가 자동으로 올바른 스레드에 배치됨
* 통합의 복원력 향상: 호출 수가 적어 일시적 장애 지점이 줄어듦
* 이전 버전과 호환: 기존 "대화 ID별" 패턴이 계속 작동

## 엔드포인트 개요 & 페이로드 (개념)

다음 예시는 요청 구조화 및 응답 사용 방법을 보여줍니다. 필드명은 대표적인 예시이므로, 환경의 최신 개발자 문서에 맞춰 구현하세요.

**HTTP**

```
POST /conversations/inbound-messages
Authorization: Bearer <token>
Content-Type: application/json
```

**요청 (예시)**

```json
{
  "contactId": "CONTACT_ID",
  "channel": "sms | whatsapp | email | messenger | instagram | webchat",
  "endpoint": {
    "phone": "+15551234567",
    "email": "user@example.com"
  },
  "content": {
    "text": "Hello from our provider",
    "attachments": [
      {
        "type": "image|file|video",
        "url": "https://example.com/file.jpg",
        "filename": "file.jpg",
        "sizeBytes": 123456
      }
    ]
  },
  "metadata": {
    "providerMessageId": "ext-abc-123",
    "externalThreadKey": "optional-correlation",
    "timestamp": "2026-02-04T10:15:30Z"
  },
  "idempotencyKey": "fd2d5f6f-5a9f-4b0a-8d68-0d5f6a1c9e5a"
}
```

**응답 (예시)**

```json
{
  "messageId": "MSG_123",
  "conversationId": "CONV_987",
  "contactId": "CONTACT_ID",
  "channel": "sms",
  "direction": "inbound",
  "createdAt": "2026-02-04T10:15:31Z"
}
```

## 스레딩 & 연결 규칙

스레딩 규칙은 시스템이 메시지를 기존 대화에 추가할지 새 대화를 생성할지 결정합니다. 이러한 규칙을 이해하면 중복되거나 분할된 스레드를 방지할 수 있습니다.

* 기존 스레드 (같은 채널): 연락처가 같은 채널에 열린 대화가 있으면 해당 스레드에 메시지가 추가됩니다.
* 적절한 스레드 없음: 시스템이 새 대화를 생성하고 응답에서 conversationId를 반환합니다.
* 연락처당 여러 엔드포인트: 연락처가 같은 채널에 여러 주소(예: 두 개의 전화번호나 이메일)를 가진 경우, 엔드포인트 힌트(예: endpoint.phone 또는 endpoint.email)를 포함하여 명확히 구분하세요.
* 다중 위치 컨텍스트: 연락처가 여러 위치에 존재하는 경우 인증 컨텍스트나 페이로드가 올바른 위치/워크스페이스를 대상으로 하는지 확인하세요.
* 보관/종료된 스레드: 종료/보관된 스레드만 존재하는 경우 새 대화가 생성됩니다.

## 설정 & 요구사항

자격 증명, 범위, 환경 컨텍스트를 미리 준비하면 안정성이 향상되고 통합 시간이 단축됩니다.

* 액세스 & 범위: API 액세스와 역할에 필요한 대화/연락처 범위를 확인하세요.
* 인증: 환경 표준에 따라 OAuth 또는 API 키를 사용하세요.
* 연락처 확인: 업스트림에서 연락처 ID를 얻고 검증하는 안정적인 방법(예: 전화/이메일 매칭)을 확보하세요.
* 위치 컨텍스트: 호출이 연락처와 대화 데이터를 소유한 올바른 위치로 해결되어야 합니다.

## 채널 고려사항 & 첨부파일

각 채널은 고유한 규칙을 적용합니다. 전송 실패나 거부된 업로드를 피하려면 페이로드를 검증하세요.

* SMS/MMS: 문자 및 미디어 크기/형식 제한을 준수하세요. 시스템에서 접근 가능한 미디어 URL을 선호하세요.
* 왓츠앱: 템플릿/자유 형식 제약을 준수하고 미디어 유형이 왓츠앱 사양을 충족하는지 확인하세요.
* 이메일: 적절한 MIME 유형을 제공하고 text/HTML 본문과 첨부파일을 지원하세요.
* 메신저/인스타그램: API 플랫폼 제한과 속도 제한이 적용될 수 있습니다. 미디어 크기를 검증하세요.
* 웹 채팅: 리치 콘텐츠 지원은 위젯 기능에 따라 다릅니다. 필요시 텍스트로 대체하세요.

## 멱등성, 재시도 & 속도 제한

네트워크 문제와 공급자 타임아웃은 일반적입니다. 멱등성과 체계적인 재시도 로직은 중복 메시지를 방지하고 사용자 신뢰를 향상시킵니다.

* 멱등성: 항상 idempotencyKey를 포함하세요. 같은 키로 재시도해도 중복이 생성되지 않아야 합니다.
* 재시도 정책: 5xx/타임아웃에서 지수 백오프로 재시도하세요. 429 응답과 Retry-After 헤더가 있을 때 이를 준수하세요.
* 관찰 가능성: 요청 ID와 providerMessageId를 로그에 기록하여 다운스트림 시스템과 상관관계를 추적하세요.

## 오류 처리 & 일반적인 응답

표준화된 오류 처리는 조사 시간을 줄이고 사용자에게 보이는 불일치를 방지합니다.

* **400 Bad Request** — 잘못된 contactId, 누락된 채널, 잘못된 콘텐츠 형식, 지원되지 않는 첨부파일 유형/크기
* **401/403** — 인증 실패 또는 위치에 대한 범위/역할 부족
* **404 Not Found** — contactId를 찾을 수 없거나 위치 컨텍스트에서 보이지 않음
* **409 Conflict** — 멱등성 키 충돌 또는 중복 제출 감지
* **413 Payload Too Large** — 첨부파일이 크기 제한 초과
* **429 Too Many Requests** — 속도 제한 초과; 백오프 후 재시도
* **5xx** — 일시적인 공급자/시스템 오류; 같은 idempotencyKey로 재시도

## 테스트 & 검증

반복 가능한 테스트 계획은 메시지가 올바르게 스레딩되고 프로덕션 출시 전에 CRM에서 예상대로 표시되도록 보장합니다.

* 정상 경로: 알려진 contactId로 인바운드를 게시하고 올바른 대화에 표시되는지 확인하세요.
* 스레드 없음 경우: 열린 대화가 없는 연락처로 게시하고 새 conversationId가 반환되는지 확인하세요.
* 엔드포인트 모호성: 여러 번호/이메일을 가진 연락처를 테스트하고 엔드포인트 힌트를 포함하여 올바른 스레딩을 확인하세요.
* 첨부파일: 허용된 미디어를 검증하고 CRM 타임라인에서 렌더링을 확인하세요.
* 복원력: 타임아웃을 시뮬레이션하고 멱등한 재시도가 중복을 생성하지 않는지 확인하세요.

## 자주 묻는 질문

**Q: 대화 ID를 사용하여 인바운드를 계속 게시할 수 있나요?** 네. 기존 플로우는 계속 지원됩니다. 연락처 기반 인바운드는 추가적인 단축 방법입니다.

**Q: 채널을 생략하면 어떻게 되나요?** 요청이 거부됩니다. 채널을 제공하고 필요시 명확한 엔드포인트 필드를 포함하세요.

**Q: 여러 스레드가 존재할 때 대화는 어떻게 선택되나요?** 시스템은 같은 채널의 열린 스레드를 우선합니다. 찾을 수 없으면 새 대화를 생성합니다.

**Q: 타임아웃 후 재시도할 때 중복을 어떻게 처리하나요?** 모든 요청에 idempotencyKey를 포함하고 재시도 시 이를 재사용하세요.

**Q: 과거 인바운드 메시지를 백필할 수 있나요?** 네. 원래 시간을 반영하는 metadata.timestamp를 제공하면 메시지가 타임라인에서 적절히 정렬됩니다.

**Q: 연락처가 여러 위치에 나타나는 경우 올바른 위치를 어떻게 대상으로 하나요?** 의도한 위치/워크스페이스에 연결된 자격 증명이나 헤더를 사용하세요. 호출은 연락처를 소유한 위치로 범위가 지정되어야 합니다.

***

*원문 최종 수정: Mon, 9 Feb, 2026 at 5:56 AM* *Hyperclass 사용 가이드 — hyperclass.ai*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hyperclass.gitbook.io/hyperclass-docs/developer/conversations-api-add-inbound-message-with-contact-id.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.