클라우드 API

WhatsApp Business 플랫폼 > 클라우드 API > 가이드

메시지 보내기

이 문서에서는 API를 사용하여 WhatsApp 사용자에게 메시지를 보내는 방법을 설명합니다.

메시지 유형

API를 사용하여 다음과 같은 유형의 메시지를 보낼 수 있습니다. 공감 메시지를 제외한 모든 유형의 메시지는 이전 메시지의 답장으로 전송할 수 있습니다.

주소 메시지를 사용하면 WhatsApp 사용자에게 쉽게 배송 주소를 요청할 수 있습니다.


오디오 메시지는 오디오 아이콘과 오디오 파일 링크를 표시합니다. WhatsApp 사용자가 아이콘을 누르면 WhatsApp 클라이언트가 오디오 파일을 읽어들여서 재생합니다.


연락처 메시지를 사용하면 WhatsApp 사용자에게 이름, 전화번호, 물리적 주소, 이메일 주소 등의 자세한 연락처 정보를 직접 전송할 수 있습니다.


문서 메시지는 WhatsApp 사용자가 눌러서 다운로드할 수 있는 문서가 연결된 문서 아이콘을 표시합니다.


이미지 메시지는 단일 이미지와 선택적 캡션을 표시합니다.


인터랙티브 CTA URL 버튼 메시지를 사용하면 모든 URL을 버튼에 매핑할 수 있으므로 메시지 본문에 길거나 모호한 원본 URL을 포함할 필요가 없습니다.


인터랙티브 플로 메시지를 사용하면 고객에게 더 자연스럽거나 편안한 구조화된 메시지를 보낼 수 있습니다. 예를 들어 예약, 제품 둘러보기, 고객 피드백 수집, 새로운 영업 잠재 고객 확보 등 작업에 WhatsApp 플로를 사용할 수 있습니다.


인터랙티브 리스트 메시지를 사용하면 WhatsApp 사용자에게 선택 가능한 옵션 리스트를 보여줄 수 있습니다.


인터랙티브 위치 요청 메시지는 본문 텍스트와 위치 보내기 버튼을 표시합니다. WhatsApp 사용자가 버튼을 누르면 사용자가 자신의 위치를 공유하는 데 사용할 수 있는 위치 공유 화면이 표시됩니다.


인터랙티브 답장 버튼 메시지를 사용하면 사용자가 선택할 수 있는 사전 정의된 답장을 최대 세 개 보낼 수 있습니다.


위치 메시지를 사용하면 WhatsApp 사용자에게 위치 위도와 경도를 보낼 수 있습니다.


스티커 메시지는 WhatsApp 메시지에 애니메이션 또는 고정 스티커 이미지를 표시합니다.


문자 메시지는 본문과 선택적 링크 미리 보기만 포함된 메시지입니다.


템플릿 메시지를 사용하면 WhatsApp 사용자에게 마케팅, 유틸리티, 인증 템플릿을 보낼 수 있습니다. 다른 메시지 유형과 달리, 템플릿 메시지는 비즈니스와 메시지 수신자 사이에 24시간의 고객 서비스 기간이 열려 있지 않아도 메시지를 보낼 수 있습니다.


동영상 메시지는 선택적 캡션이 있는 동영상 이미지의 썸네일 미리 보기를 표시합니다. WhatsApp 사용자가 미리 보기를 누르면 동영상이 읽어들여지고 사용자에게 표시됩니다.


공감 메시지는 비즈니스에서 수신한 이전의 WhatsApp 사용자 메시지에 적용할 수 있는 이모티콘 공감입니다.

고객 서비스 기간

WhatsApp 사용자가 메시지를 보내면 고객 서비스 기간이라는 24시간 타이머가 시작(또는 새로 고침)됩니다.

템플릿 메시지를 제외한 모든 메시지 유형은 비즈니스와 사용자 간의 고객 서비스 기간이 열려 있는 경우에만 사용자에게 보낼 수 있습니다.

템플릿 메시지는 언제든 WhatsApp 사용자에게 전송할 수 있습니다. 단, 사용자가 비즈니스로부터 메시지를 수신할 것을 옵트인했어야 합니다.

요청

모든 메시지 전송 요청은 POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID/messages 엔드포인트를 사용합니다.

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

게시물 본문은 전송하고자 하는 메시지 유형에 따라 달라지지만 페이로드는 다음의 공통적인 구문을 사용합니다.

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "type": "<MESSAGE_TYPE>",
  "<MESSAGE_TYPE>": {<MESSAGE_CONTENTS>}
}

게시물 본문 페이로드의 type 속성 값은 전송할 메시지 유형을 나타내고 해당 유형과 매칭되는 속성을 포함하여 메시지 내용을 설명할 수 있습니다.

예를 들어 문자 메시지를 WhatsApp 사용자에게 전송하는 요청은 다음과 같습니다. type이 text로 설정되어 있고 그 뒤에 메시지 내용을 설명하는 text 개체가 따라옵니다.

curl 'https://graph.facebook.com/v20.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "As requested, here'\''s the link to our latest product: https://www.meta.com/quest/quest-3/"
  }
}'

문자 메시지가 WhatsApp 사용자에게 성공적으로 전달된 후 WhatsApp 클라이언트에 다음과 같이 메시지가 표시됩니다.

응답

API가 요청 자체에서 오류가 발생하지 않고 메시지 전송 요청을 성공적으로 수신하면 다음과 같은 응답이 전송됩니다.

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "<WHATSAPP_USER_PHONE_NUMBER>",
      "wa_id": "<WHATSAPP_USER_ID>"
    }
  ],
  "messages": [
    {
      "id": "<WHATSAPP_MESSAGE_ID>"
      "message_status": "<PACING_STATUS>"
    }
  ]
}

이 응답은 API가 성공적으로 요청을 수신했음을 나타낼 뿐, 메시지가 성공적으로 전달되었다는 의미는 아닙니다. 메시지 전달 상태는 메시지 Webhooks를 통해 전달됩니다.

message_status 속성은 게재 빈도가 조절되는 중인 템플릿을 사용하는 템플릿 메시지를 전송할 때만 포함됩니다.

Webhooks

WhatsApp 사용자에게 전송된 메시지가 메시지 Webhooks를 트리거하므로 메시지 상태 알림을 받으려면 이 주제를 구독하세요.

커머스 메시지

커머스 메시지는 제품 카탈로그와 함께 사용하는 인터랙티브 메시지입니다. 이러한 유형의 메시지를 사용하는 방법은 고객에게 제품 공유를 참조하세요.

답글

모든 유형의 메시지는 이전 메시지의 답장으로 보낼 수 있습니다. 이전 메시지가 새로운 메시지 상단에 컨텍스트 버블로 인용되어 표시됩니다.

제한 사항

컨텍스트 버블이 답장으로 전송된 메시지 상단에 표시되지 않는 경우는 다음과 같습니다.

  • 이전 메시지가 삭제되었거나 장기 저장 공간으로 이동된 경우(일반적으로 메시지는 30일 후 장기 저장 공간으로 이동됨, 로컬 스토리지를 활성화한 경우 예외)
  • 오디오, 이미지 또는 동영상 메시지로 답장하고 WhatsApp 사용자가 KaiOS를 실행하는 경우
  • WhatsApp 클라이언트를 사용하여 PTT(push-to-talk) 메시지로 답장하고 WhatsApp 사용자가 KaiOS를 실행하는 경우
  • 템플릿 메시지로 답장하는 경우

요청 구문

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

POST 본문

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "context": {
    "message_id": "WAMID_TO_REPLY_TO"
  },

  /* Message type and type contents goes here */

}

POST 본문 매개변수

자리 표시자설명예시 값

<WAMID_TO_REPLY_TO>

문자열

필수 항목.

답장하고자 하는 이전 메시지의 WhatsApp 메시지 ID(wamid).

wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQTdCNTg5RjY1MEMyRjlGMjRGNgA=

<WHATSAPP_USER_PHONE_NUMBER>

String

Required.

WhatsApp user phone number.

+16505551234

요청 예시

이전 메시지에 답장으로 보낸 문자 메시지의 예:

curl 'https://graph.facebook.com/v19.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "context": {
    "message_id": "wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQTdCNTg5RjY1MEMyRjlGMjRGNgA="
  },
  "type": "text",
  "text": {
    "body": "You'\''re welcome, Pablo!"
  }
}'

WhatsApp User Phone Number Formats

Plus signs (+), hyphens (-), parenthesis ((,)), and spaces are supported in send message requests.

We highly recommend that you include both the plus sign and country calling code when sending a message to a customer. If the plus sign is omitted, your business phone number's country calling code is prepended to the customer's phone number. This can result in undelivered or misdelivered messages.

For example, if your business is in India (country calling code 91) and you send a message to the following customer phone number in various formats:

Number In Send Message RequestNumber Message Delivered ToOutcome

+16315551234

+16315551234

Correct number

+1 (631) 555-1234

+16315551234

Correct number

(631) 555-1234

+916315551234

Potentially wrong number

1 (631) 555-1234

+9116315551234

Potentially wrong number

미디어 자산

메시지에서 전송된 미디어 자산은 메시지를 전송할 비즈니스 전화번호에 업로드하거나, 공개 서버에서 자산을 호스팅하고 메시지 전송 요청에 해당 URL을 포함해야 합니다.

오류가 발생할 가능성을 낮추고 공개 서버에 불필요한 요청을 보내지 않도록 하려면 미디어 자산을 업로드하고 메시지를 보낼 때 해당 미디어 자산의 ID를 사용하는 것이 좋습니다.

미디어 HTTP 캐싱

WhatsApp 클라우드 API는 미디어 HTTP 캐싱을 지원합니다. (Meta 서버에 업로드한 자산의 ID(id)가 아니라) 서버에 있는 미디어 자산에 대한 링크(link)를 사용하고 있을 경우, Meta에서 자산을 요청할 때 서버 응답에 아래의 헤더를 포함하여 이후의 메시지에 재사용하기 위해 자산을 캐싱하도록 안내할 수 있습니다. 아래의 헤더 중 아무것도 포함하지 않으면 자산이 캐싱되지 않습니다.

Cache-Control: <CACHE_CONTROL>
Last-Modified: <LAST_MODIFIED>
ETag: <ETAG>

Cache-Control

Cache-Control 헤더는 자산 캐싱 처리 방법을 알려줍니다. Meta에서는 다음 지침을 지원합니다.

  • max-age=n: 자산을 캐싱할 초 단위 시간(n)을 나타냅니다. Meta에서는 이 시간을 초과할 때까지 이후의 메시지에서 캐싱된 자산을 재사용하고, 그 후에는 필요하면 다시 자산을 요청합니다. 예: Cache-Control: max-age=604800.
  • no-cache: 자산을 캐싱할 수 있지만 Last-Modified 헤더 값이 이전의 응답과 다르면 업데이트해야 한다는 것을 나타냅니다. Last-Modified 헤더가 필요합니다. 예: Cache-Control: no-cache.
  • no-store: 자산을 캐싱해서는 안 된다는 것을 나타냅니다. 예: Cache-Control: no-store.
  • private: 자산이 받는 사람에게 맞춤화되었으므로 캐싱해서는 안 된다는 것을 나타냅니다.

Last-Modified

자산이 마지막으로 수정된 시점을 나타냅니다. Cache-Control: no-cache와 함께 사용됩니다. Last-Modified 값이 이전의 응답과 다르고 Cache-Control: no-cache가 응답에 포함된 경우, 자산의 캐싱된 버전이 응답에 있는 자산으로 업데이트됩니다. 예: Date: Tue, 22 Feb 2022 22:22:22 GMT.

ETag

ETag 헤더는 자산의 특정 버전을 식별하는 고유한 문자열입니다. 예: ETag: "33a64df5". Cache-Control 및 Last-Modified 헤더가 모두 응답에 포함되지 않는 경우를 제외하고 이 헤더는 무시됩니다. 이 경우 Meta의 자체적인 내부 로직(비공개)에 따라 자산이 캐싱됩니다.

헤더를 포함한 응답 샘플

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 1024
Date: Tue, 22 Feb 2022 22:22:22 GMT
ETag: "33a64df5"
Cache-Control: max-age=604800

<IMAGE_PAYLOAD>

여러 메시지의 전송 순서

일련의 메시지를 보낼 때 메시지가 전송되는 순서가 반드시 API 요청의 순서와 일치하는 것은 아닙니다. 메시지 전송의 순서를 확인해야 할 경우, 메시지 순서에서 다음 메시지를 보내기 전에 메시지 Webhooks에서 delivered 상태를 수신했는지 확인하세요.

TTL(Time-To-Live)

WhatsApp 사용자에게 메시지를 전달할 수 없을 경우 TTL(Time-To-Live)이라고 하는 일정 시간 또는 메시지 검증 기간 동안 WhatsApp에서 메시지를 전달하려고 계속 시도합니다. TTL을 초과하는 시간 동안에도 메시지를 전달할 수 없을 경우 WhatsApp에서 재시도를 멈추고 메시지를 드롭합니다.

  • 인증 템플릿을 사용하는 템플릿 메시지를 제외한 모든 메시지의 TTL은 30일입니다.
  • 인증 템플릿을 사용하는 템플릿 메시지는 기본 TTL이 10분입니다.

인증 템플릿 및 유틸리티 템플릿에 맞춤 TTL을 설정하면 이 기본값을 적절히 설정할 수 있습니다. TTL(Time-To-Live) 맞춤 설정을 참조하세요.

메시지를 전송했지만 메시지가 TTL을 초과하기 전에 메시지가 전달되었음을 나타내는 해당 메시지 Webhooks를 수신하지 못하는 경우, 메시지가 드롭된 것으로 간주하세요.

메시지가 관련 없는 다른 이유로 실패하여 전달 실패메시지 Webhooks를 트리거하는 경우, Webhooks를 수신하기까지 다소 지연이 발생할 수 있으므로 드롭으로 간주하기 전에 작은 버퍼를 빌드하는 것이 좋습니다.

문제 해결

메시지 전송에 문제가 있을 경우 메시지 전달되지 않음을 참조하세요.