클라우드 API
한국어 버전으로 돌아가기
문서가 업데이트되었습니다.
한국어로 번역이 아직 완료되지 않았습니다.
영어 업데이트됨: 2월 1일

WhatsApp Business 플랫폼 > 클라우드 API > 참고 자료

메시지

/PHONE_NUMBER_ID/messages 엔드포인트를 사용하여 고객에게 메시지 템플릿과 문자, 미디어, 연락처, 위치, 인터랙티브 메시지를 전송합니다. 전송할 수 있는 메시지에 대해 자세히 알아보세요.

엔드포인트인증

/PHONE_NUMBER_ID/messages

(전화번호 ID 가져오기 참조)

Developers can authenticate their API calls with the access token generated in the App Dashboard > WhatsApp > API Setup.


Solution Partners must authenticate themselves with an access token with the whatsapp_business_messaging permission.

메시지는 고유 ID(WAMID)로 식별됩니다. 메시지 상태는 Webhooks에서 WAMID를 통해 추적할 수 있습니다. 수신되는 메시지는 메시지 엔드포인트를 통해 읽음으로 표시할 수도 있습니다. 이 WAMID의 최대 길이는 128자입니다.

클라우드 API를 사용하는 경우 전화번호에 WhatsApp ID가 있는지 명시적으로 확인할 방법을 더 이상 제공하지 않습니다. 클라우드 API를 사용하여 누군가에게 메시지를 보내려면 고객이 옵트인한 후 고객의 전화번호로 직접 메시지를 전송하면 됩니다. 관련 예시는 참고 자료, 메시지를 참조하세요.

메시지 개체

메시지를 전송하려면 먼저 전송하고자 하는 콘텐츠로 메시지 개체를 구성해야 합니다. message 개체에서 사용한 매개변수는 다음과 같습니다.

이름설명 (왼쪽 열의 화살표를 클릭하여 지원되는 옵션을 확인하세요.)

audio

개체

type=audio일 때 필수 항목.

오디오를 포함하는 media 개체.

biz_opaque_callback_data

문자열

선택 사항.

임의의 문자열이며, 추적에 사용합니다.


예를 들어 이 필드에 메시지 템플릿 ID를 전달하여 비즈니스가 전송한 첫 메시지부터 고객의 여정을 추적할 수 있습니다. 그런 다음, 다양한 메시지 템플릿 유형의 ROI를 추적하여 가장 효과적인 템플릿을 확인할 수 있습니다.


이 문자열은 Webhooks 페이로드 내의 statuses 개체에 포함되어 있으므로 WhatsApp Business 계정에서 messages Webhooks 필드를 구독하는 모든 앱은 이 문자열을 받을 수 있습니다.


클라우드 API는 이 필드를 처리하지 않고 메시지 전송됨/전달됨/읽음 Webhooks에서 반환합니다.


최대 512자입니다.


클라우드 API 전용.

contacts

개체

type=contacts일 때 필수 항목.

contacts 개체.

context

개체

대화 중 메시지에 답장하는 경우 필수 항목.

답장하려는 이전 메시지의 ID를 포함하는 개체. 예를 들면 다음과 같습니다.


{"message_id":"MESSAGE_ID"}


클라우드 API 전용.

document

개체

type=document일 때 필수 항목.

문서를 포함하는 media 개체.

hsm

개체

hsm 개체를 포함합니다. 이 옵션은 온프레미스 API의 v2.39부터 사용 중단되었습니다. 대신 template 개체를 사용하세요.


온프레미스 API 전용.

image

개체

type=image일 때 필수 항목.

이미지를 포함하는 media 개체.

interactive

개체

type=interactive일 때 필수 항목.

interactive 개체. 각 interactive 개체의 구성 요소는 일반적으로 일관된 패턴(header, body, footer 및 action)을 따릅니다.

location

개체

type=location일 때 필수 항목.

location 개체.

messaging_product

문자열

필수 항목.

요청에 사용된 메시지 서비스. "whatsapp"을 사용합니다.


클라우드 API 전용.

preview_url

부울

type=text일 때 필수 항목.

문자 메시지에서 URL 미리 보기 허용 — 문자 메시지에서 URL 전송을 참조하세요. 메시지에 URL을 포함하지 않는 경우 이 필드는 선택 사항입니다. 값:false(기본값), true.


온프레미스 API 전용. 클라우드 API 사용자는 텍스트 개체 내의 preview_url 필드와 동일한 기능을 사용할 수 있습니다.

recipient_type

문자열

선택 사항.

현재는 개인에게만 메시지를 보낼 수 있습니다. 이 필드를 individual로 설정하세요.


기본값: individual

status

문자열

메시지 상태. 이 필드를 사용하여 메시지를 read로 표시할 수 있습니다. 자세한 내용은 다음 가이드를 참조하세요.


sticker

개체

type=sticker일 때 필수 항목.

스티커를 포함하는 media 개체.


클라우드 API: 모든 유형의 인바운드 스티커 외에 고정 및 애니메이션 타사 아웃바운드 스티커도 지원됩니다. 고정 스티커는 512x512픽셀이어야 하고 100KB를 초과할 수 없습니다. 애니메이션 스티커는 512x512픽셀이어야 하고 500KB를 초과할 수 없습니다.


온프레미스 API: 모든 유형의 인바운드 스티커 외에 고정 타사 아웃바운드 스티커만 지원됩니다. 고정 스티커는 512x512픽셀이어야 하고 100KB를 초과할 수 없습니다. 애니메이션 스티커는 지원되지 않습니다.

template

개체

type=template일 때 필수 항목.

template 개체.

text

개체

문자 메시지에 필수 항목.

text 개체.

to

문자열

필수 항목.

메시지를 보낼 대상인 고객의 WhatsApp ID 또는 전화번호. 전화번호 형식을 참조하세요.


필요한 경우 온프레미스 API 사용자는 contacts 엔드포인트를 호출하여 이 번호를 받을 수 있습니다.

type

문자열

선택 사항.

전송하고자 하는 메시지 유형. 생략하는 경우 기본값은 text로 지정됩니다.

다음 개체는 메시지 개체 내에 중첩됩니다.

연락처 개체

NameDescription

addresses

object

Optional.

Full contact address(es) formatted as an addresses object. The object can contain the following fields:

streetstring – Optional. Street number and name.

citystring – Optional. City name.

statestring – Optional. State abbreviation.

zipstring – Optional. ZIP code.

countrystring – Optional. Full country name.

country_codestring – Optional. Two-letter country abbreviation.

typestring – Optional. Standard values are HOME and WORK.

birthday

Optional.

YYYY-MM-DD formatted string.

emails

object

Optional.

Contact email address(es) formatted as an emails object. The object can contain the following fields:

emailstring – Optional. Email address.

typestring – Optional. Standard values are HOME and WORK.

name

object

Required.

Full contact name formatted as a name object. The object can contain the following fields:

formatted_namestring – Required. Full name, as it normally appears.

first_namestring – Optional*. First name.

last_namestring – Optional*. Last name.

middle_namestring – Optional*. Middle name.

suffixstring – Optional*. Name suffix.

prefixstring – Optional*. Name prefix.


*At least one of the optional parameters needs to be included along with the formatted_name parameter.

org

object

Optional.

Contact organization information formatted as an org object. The object can contain the following fields:

companystring – Optional. Name of the contact's company.

departmentstring – Optional. Name of the contact's department.

titlestring – Optional. Contact's business title.

phones

object

Optional.

Contact phone number(s) formatted as a phone object. The object can contain the following fields:

phonestring – Optional. Automatically populated with the `wa_id` value as a formatted phone number.

typestring – Optional. Standard Values are CELL, MAIN, IPHONE, HOME, and WORK.

wa_idstring – Optional. WhatsApp ID.

urls

object

Optional.

Contact URL(s) formatted as a urls object. The object can contain the following fields:

urlstring – Optional. URL.

typestring – Optional. Standard values are HOME and WORK.

인터랙티브 개체

이름설명

action

개체

필수 항목.

사용자가 메시지를 읽고 수행하기를 바라는 행동.

body

개체

product 유형에 선택 사항. 다른 메시지 유형에 필수 항목.

메시지 본문이 포함된 개체.


body 개체에는 다음과 같은 필드가 포함됩니다.

text문자열 – 본문이 있는 경우 필수 항목. 메시지 내용. 이모티콘과 마크다운이 지원됩니다. 최대 길이: 1,024자.

footer

개체

선택 사항. 메시지 바닥글이 있는 개체.


footer 개체에는 다음과 같은 필드가 포함됩니다.

text문자열 – 바닥글이 있는 경우 필수 항목. 바닥글 내용. 이모티콘, 마크다운, 링크가 지원됩니다. 최대 길이: 60자.

header

개체

product_list 유형에 필수 항목. 다른 유형에는 선택 사항.

메시지 상단에 표시되는 헤더 내용. 인터랙티브 개체가 product 유형일 경우 헤더를 설정할 수 없습니다. 자세한 내용은 header 개체를 참조하세요.

type

개체

필수 항목.

전송하고자 하는 인터랙티브 메시지의 유형. 지원되는 값은 다음과 같습니다.


  • button: 답장 버튼에 사용합니다.
  • catalog_message: 카탈로그 메시지에 사용합니다.
  • list: 리스트 메시지에 사용합니다.
  • product: 단일 제품 메시지에 사용합니다.
  • product_list: 다중 제품 메시지에 사용합니다.
  • flow: 플로 메시지에 사용합니다.

다음 개체는 interactive 개체 내에서 중첩됩니다.

행동 개체

이름설명

button

문자열

리스트 메시지에 필수 항목.

버튼 내용. 빈 문자열일 수 없으며 메시지 내에서 고유해야 합니다. 이모티콘은 지원되지만 마크다운은 지원되지 않습니다.


최대 길이: 20자.

buttons

개체 배열

답장 버튼에 필수 항목.

버튼 개체에는 다음과 같은 매개변수를 포함할 수 있습니다.


  • type: 지원되는 유형은 reply(답장 버튼용)뿐입니다.
  • title: 버튼 제목. 빈 문자열일 수 없으며 메시지 내에서 고유해야 합니다. 이모티콘은 지원되지만 마크다운은 지원되지 않습니다. 최대 길이: 20자.
  • id: 버튼의 고유한 식별자. 사용자가 버튼을 클릭하면 Webhook에서 이 ID가 반환됩니다. 최대 길이: 256자.

최대 3개의 버튼을 넣을 수 있습니다. ID를 설정할 때는 앞/뒤에 공백을 둘 수 없습니다.

catalog_id

문자열

단일 제품 메시지와 다중 제품 메시지에 필수 항목.

WhatsApp Business 계정과 연결된 Facebook 카탈로그의 고유 식별자. 이 ID는 Meta 커머스 관리자를 통해 가져올 수 있습니다.

product_retailer_id

문자열

단일 제품 메시지와 다중 제품 메시지에 필수 항목.

카탈로그 내 제품의 고유 식별자.


이 ID를 가져오려면 Meta 커머스 관리자로 이동하여 Meta Business 계정을 선택하세요. 계정에 연결된 Shop 리스트가 표시됩니다. 사용하고자 하는 Shop을 클릭합니다. 왼쪽 창에서 카탈로그 > 항목을 클릭하고 언급하고 싶은 항목을 찾습니다. 이 항목의 ID는 항목 이름에 표시됩니다.

sections

개체 배열

리스트 메시지와 다중 제품 메시지에 필수 항목.

section 개체의 배열. 최소 1, 최대 10. section 개체를 참조하세요.

mode

문자열

플로 메시지에 선택 사항.

플로의 현재 모드(draft 또는 published).


기본값: published

flow_message_version

문자열

플로 메시지에 필수 항목.

3이어야 합니다.

flow_token

문자열

플로 메시지에 필수 항목.

비즈니스가 식별자 역할을 하도록 생성한 토큰.

flow_id

문자열

플로 메시지에 필수 항목.

WhatsApp에서 제공한 플로의 고유 식별자.

flow_cta

문자열

플로 메시지에 필수 항목.

CTA 버튼 텍스트(예: '가입하기').


최대 길이: 20자(이모티콘 불포함).

flow_action

문자열

플로 메시지에 선택 사항.

navigate 또는 data_exchange. navigate를 사용하여 메시지에서 첫 화면을 미리 정의합니다. 고급 사용 사례에는 data_exchange를 사용합니다. 이 경우, 첫 화면은 엔드포인트에서 제공합니다.


기본값: navigate

flow_action_payload

개체

플로 메시지에 선택 사항.

flow_action이 navigate인 경우에만 필수 항목. 이 개체에는 다음과 같은 매개변수를 포함할 수 있습니다.

screen문자열 – 필수 항목. 플로 첫 화면의 id입니다.

data개체 – 선택 사항. 플로 첫 화면의 입력 데이터. 비어 있지 않은 개체여야 합니다.

헤더 개체

이름설명

document

개체

type이 document로 설정된 경우 필수 항목.

이 문서의 미디어 개체를 포함합니다.

image

개체

type이 image로 설정된 경우 필수 항목.

이 이미지의 미디어 개체를 포함합니다.

text

문자열

type이 text로 설정된 경우 필수 항목.

헤더 텍스트. 서식에서 이모티콘은 허용되지만 마크다운은 허용되지 않습니다.


최대 길이: 60자.

type

문자열

필수 항목.

사용하려는 헤더 유형. 지원되는 값은 다음과 같습니다.


  • text: 리스트 메시지, 답장 버튼, 다중 제품 메시지에 사용합니다.
  • video: 답장 버튼에 사용합니다.
  • image: 답장 버튼에 사용합니다.
  • document: 답장 버튼에 사용합니다.

video

개체

type이 video로 설정된 경우 필수 항목.

이 동영상의 미디어 개체를 포함합니다.

섹션 개체

이름설명

product_items

개체 배열

다중 제품 메시지에 필수 항목.

product 개체의 배열. 모든 섹션에 걸쳐 섹션당 최소 1개, 최대 30개 제품이 있습니다.


각 product 개체에는 다음과 같은 필드가 포함되어 있습니다.


  • product_retailer_id문자열 – 다중 제품 메시지에 필수 항목. 카탈로그 내 제품의 고유 식별자. 이 ID를 가져오려면 Meta 커머스 관리자로 이동하여 계정과 사용하려는 Shop을 선택합니다. 그런 다음, 카탈로그 > 항목을 클릭하고 언급하고자 하는 항목을 찾습니다. 이 항목의 ID는 항목 이름에 표시됩니다.

rows

개체 배열

리스트 메시지에 필수 항목.

행 리스트를 포함합니다. 섹션 전체에 총 10개의 행을 둘 수 있습니다.


각 행에는 제목(최대 길이: 24자)과 ID(최대 길이: 200자)가 있어야 합니다. 설명(최대 길이: 72자)을 추가할 수도 있지만 이는 선택 사항.


예:

"rows": [
  {
   "id":"unique-row-identifier-here",
   "title": "row-title-content-here",
   "description": "row-description-content-here",           
   }
]

title

문자열

메시지에 섹션이 2개 이상인 경우 필수 항목.

섹션 제목.


최대 길이: 24자.

위치 개체

NameDescription

latitude

Required.

Location latitude in decimal degrees.

longitude

Required.

Location longitude in decimal degrees.

name

Required.

Name of the location.

address

Required.

Address of the location.

미디어 개체

미디어 개체의 ID를 가져오는 방법에 대한 자세한 내용은 미디어 ID가져오기를 참조하세요. 클라우드 API에 지원되는 미디어 유형에 대한 자세한 내용은 지원되는 미디어 유형을 참조하세요.

NameDescription

id

string

Required when type is audio, document, image, sticker, or video and you are not using a link.


The media object ID. Do not use this field when message type is set to text.

link

string

Required when type is audio, document, image, sticker, or video and you are not using an uploaded media ID (i.e. you are hosting the media asset on your public server).

The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs.


Do not use this field when message type is set to text.


Cloud API users only:


  • See Media HTTP Caching if you would like us to cache the media asset for future messages.
  • When we request the media asset from your server you must indicate the media's MIME type by including the Content-Type HTTP header. For example: Content-Type: video/mp4. See Supported Media Types for a list of supported media and their MIME types.

caption

string

Optional.


Media asset caption. Do not use with audio or sticker media.


On-Premises API users:

  • For v2.41.2 or newer, this field is is limited to 1024 characters.
  • Captions are currently not supported for document media.

filename

string

Optional.


Describes the filename for the specific document. Use only with document media.


The extension of the filename will specify what format the document is displayed as in WhatsApp.

provider

string

Optional. On-Premises API only.

This path is optionally used with a link when the HTTP/HTTPS link is not directly accessible and requires additional configurations like a bearer token. For information on configuring providers, see the Media Providers documentation.

템플릿 개체

대화 기반 가격이 변경되었습니다. 새로운 대화 기반 가격 모델의 적용 방법에 대해 알아보려면 가격을 참조하세요.

또한 metric_types의 표시 방식이 2023년 7월 1일부터 변경되었습니다. 자세한 내용은 전환 분석 표를 참조하세요.

NameDescription

name

Required.

Name of the template.

language

object

Required.

Contains a language object. Specifies the language the template may be rendered in.


The language object can contain the following fields:

policystring – Required. The language policy the message should follow. The only supported option is deterministic. See Language Policy Options.

codestring – Required. The code of the language or locale to use. Accepts both language and language_locale formats (e.g., en and en_US). For all codes, see Supported Languages.

components

array of objects

Optional.

Array of components objects containing the parameters of the message.

namespace

Optional. Only used for On-Premises API.

Namespace of the template.

다음 개체는 template 개체 내에서 중첩됩니다.

버튼 매개변수 개체

이름설명 (왼쪽 열의 화살표를 클릭하여 지원되는 옵션을 확인하세요.)

type

문자열

필수 항목.

버튼의 매개변수 유형을 나타냅니다.

지원되는 옵션

  • "payload"
  • "text"

payload

quick_reply 버튼에 필수 항목.

버튼을 클릭했을 때 버튼에 텍스트를 표시하는 동시에 반환되는 개발자 정의 페이로드.


예시는 빠른 답장 버튼 클릭 시 콜백을 참조하세요.

text

URL 버튼에 필수 항목.

템플릿에서 사전 정의된 프리픽스 URL에 추가되는 개발자 제공 서픽스.

구성 요소 개체

NameDescription (Click the arrow in the left column for supported options.)

type

string

Required.

Describes the component type.


Example of a components object with an array of parameters object nested inside:

 "components": [{
   "type": "body",
   "parameters": [{
                "type": "text",
                "text": "name"
            },
            {
            "type": "text",
            "text": "Hi there"
            }]
      }]

Supported Options

  • header
  • body
  • button

For text-based templates, we only support the type=body.

sub_type

string

Required when type=button. Not used for the other types.

Type of button to create.

Supported Options

  • quick_reply: Refers to a previously created quick reply button that allows for the customer to return a predefined message.
  • url: Refers to a previously created button that allows the customer to visit the URL generated by appending the text parameter to the predefined prefix URL in the template.
  • catalog: Refers to a previously created catalog button that allows for the customer to return a full product catalog.

parameters

array of objects

Required when type=button.

Array of parameter objects with the content of the message.

For components of type=button, see the button parameter object.

index

Required when type=button. Not used for the other types.

Position index of the button. You can have up to 10 buttons using index values of 0 to 9.

통화 개체

이름설명

fallback_value

필수 항목.

현지화 실패 여부를 나타내는 기본 텍스트.

code

필수 항목.

ISO 4217로 정의된 통화 코드.

amount_1000

필수 항목.

1,000을 곱한 금액.

Date_Time 개체

이름설명

fallback_value

필수 항목.

기본 텍스트. 클라우드 API에서는 언제나 폴백 값을 사용하며, 다른 선택 필드를 사용하여 현지화를 시도하지 않습니다.

매개변수 개체

이름설명

type

문자열

필수 항목.

매개변수 유형을 설명합니다. 지원되는 값은 다음과 같습니다.


  • currency
  • date_time
  • document
  • image
  • text
  • video

텍스트 기반 템플릿의 경우 currency, date_time 및 text 유형 매개변수만 지원됩니다.

text

문자열

type=text일 때 필수 항목.

메시지 텍스트. 글자 수 제한은 다음과 같이 포함된 구성 요소 유형에 따라 달라집니다.


header 구성 요소 유형:

  • 60자

body 구성 요소 유형:

  • 다른 구성 요소 유형을 포함하는 경우 1,024자
  • body가 구성 요소 유형으로 유일하게 포함된 경우 32,768자

currency

개체

type=currency일 때 필수 항목.

currency 개체.

date_time

개체

type=date_time일 때 필수 항목.

date_time 개체.

image

개체

type=image일 때 필수 항목.

image 유형의 media 개체. 미디어 템플릿에 사용할 때는 캡션이 지원되지 않습니다.

document

개체

type=document일 때 필수 항목.

document 유형의 media 개체. 미디어 기반 메시지 템플릿에 대해서는 PDF 문서만 지원됩니다. 미디어 템플릿에 사용할 때는 캡션이 지원되지 않습니다.

video

개체

type=video일 때 필수 항목.

video 유형의 media 개체. 미디어 템플릿에 사용할 때는 캡션이 지원되지 않습니다.

텍스트 개체

이름설명

body

문자열

문자 메시지에 필수 항목.

http:// 또는 https://로 시작하는 URL과 서식을 포함할 수 있는 문자 메시지의 텍스트. 사용 가능한 서식 옵션은 여기를 참조하세요.


텍스트에 URL을 포함하고 문자 메시지에 미리보기 상자(preview_url: true)를 포함하려면 URL이 http:// 또는 https://로 시작하는지 확인하세요. https:// URL이 선호됩니다. IP 주소가 매칭되지 않기 때문에 호스트 이름을 포함해야 합니다.


최대 길이: 4,096자

preview_url

부울

선택 사항. 클라우드 API만 해당.

true로 설정하면 WhatsApp Messenger와 WhatsApp Business 앱이 body 텍스트 문자열에 있는 URL의 링크 미리보기를 렌더링하려고 시도합니다. URL은 http:// 또는 https://로 시작해야 합니다. 여러 URL이 body 텍스트 문자열에 있는 경우 첫 번째 URL만 렌더링됩니다.


preview_url이 생략되거나 미리보기를 가져올 수 없는 경우 대신 클릭 가능한 링크가 렌더링됩니다.


온프레미스 API 사용자는 대신 최상위 수준 메시지 페이로드에서 preview_url을 사용합니다. 매개변수를 참조하세요.

공감 개체

이름설명

message_id

문자열

필수 항목.

공감을 표시해야 하는 메시지의 WhatsApp 메시지 ID(wamid). 공감은 다음과 같은 경우에 전송되지 않습니다.


  • 메시지가 30일을 초과한 경우
  • 메시지가 공감 메시지인 경우
  • 메시지가 삭제된 경우

삭제된 메시지의 ID인 경우 해당 메시지는 전달되지 않습니다.

emoji

문자열

필수 항목.

메시지에 표시할 이모티콘.


  • Android 및 iOS 기기에서 지원되는 모든 이모티콘을 지원합니다.
  • 렌더링된 이모티콘을 지원합니다.
  • 이모티콘 유니코드 값을 사용하는 경우 이는 Java 또는 JavaScript 이스케이프로 인코딩된 값이어야 합니다.
  • 공감 메시지에서 하나의 이모티콘만 보낼 수 있습니다.
  • 빈 문자열을 사용하여 앞서 전송한 이모티콘을 삭제하세요.

개요

가이드

/messages 엔드포인트를 사용하여 메시지를 보내는 방법에 대한 자세한 내용은 다음 가이드를 참조하세요.

예

문자 메시지

curl -X  POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '
    {
      "messaging_product": "whatsapp",
      "recipient_type": "individual",
      "to": "PHONE_NUMBER",
      "type": "text",
      "text": { // the text object
        "preview_url": false,
        "body": "MESSAGE_CONTENT"
        }
    }'

공감 메시지

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "reaction",
  "reaction": {
    "message_id": "wamid.HBgLM...",
    "emoji": "\uD83D\uDE00"
  }
}'

미디어 메시지

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM-PHONE-NUMBER-ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE-NUMBER",
  "type": "image",
  "image": {
    "id" : "MEDIA-OBJECT-ID"
  }
}'

위치 메시지

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "to": "PHONE_NUMBER",
  "type": "location",
  "location": {
    "longitude": LONG_NUMBER,
    "latitude": LAT_NUMBER,
    "name": LOCATION_NAME,
    "address": LOCATION_ADDRESS
  }
}'

연락처 메시지

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "to": "PHONE_NUMBER",
  "type": "contacts",
  "contacts": [{
      "addresses": [{
          "street": "STREET",
          "city": "CITY",
          "state": "STATE",
          "zip": "ZIP",
          "country": "COUNTRY",
          "country_code": "COUNTRY_CODE",
          "type": "HOME"
        },
        {
          "street": "STREET",
          "city": "CITY",
          "state": "STATE",
          "zip": "ZIP",
          "country": "COUNTRY",
          "country_code": "COUNTRY_CODE",
          "type": "WORK"
        }],
      "birthday": "YEAR_MONTH_DAY",
      "emails": [{
          "email": "EMAIL",
          "type": "WORK"
        },
        {
          "email": "EMAIL",
          "type": "HOME"
        }],
      "name": {
        "formatted_name": "NAME",
        "first_name": "FIRST_NAME",
        "last_name": "LAST_NAME",
        "middle_name": "MIDDLE_NAME",
        "suffix": "SUFFIX",
        "prefix": "PREFIX"
      },
      "org": {
        "company": "COMPANY",
        "department": "DEPARTMENT",
        "title": "TITLE"
      },
      "phones": [{
          "phone": "PHONE_NUMBER",
          "type": "HOME"
        },
        {
          "phone": "PHONE_NUMBER",
          "type": "WORK",
          "wa_id": "PHONE_OR_WA_ID"
        }],
      "urls": [{
          "url": "URL",
          "type": "WORK"
        },
        {
          "url": "URL",
          "type": "HOME"
        }]
    }]
}'

인터랙티브 메시지

단일 제품 메시지

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
   "messaging_product": "whatsapp",
   "recipient_type": "individual",
   "to": "PHONE_NUMBER",
   "type": "interactive",
   "interactive": {
     "type": "product",
     "body": {
       "text": "optional body text"
     },
     "footer": {
       "text": "optional footer text"
     },
     "action": {
       "catalog_id": "CATALOG_ID",
       "product_retailer_id": "ID_TEST_ITEM_1"
     }
   }
 }'

다중 제품 메시지

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
 "messaging_product": "whatsapp",
   "recipient_type": "individual",
   "to": "PHONE_NUMBER",
   "type": "interactive",
   "interactive": {
     "type": "product_list",
     "header":{
       "type": "text",
       "text": "header-content"
     },
     "body": {
       "text": "body-content"
     },
     "footer": {
       "text": "footer-content"
     },
     "action": {
       "catalog_id": "CATALOG_ID",
       "sections": [
         {
           "title": "section-title",
           "product_items": [
             { "product_retailer_id": "product-SKU-in-catalog" },
             { "product_retailer_id": "product-SKU-in-catalog" },
             ...
           ]
         },
         {
           "title": "section-title",
           "product_items": [
             { "product_retailer_id": "product-SKU-in-catalog" },
             { "product_retailer_id": "product-SKU-in-catalog" },
             ...
           ]
         }
       ]
     }
   }
 }

카탈로그 메시지

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "interactive",
  "interactive" : {
    "type" : "catalog_message",
    "body" : {
      "text": "Thanks for your order! Tell us what address you’d like this order delivered to."
    },
    "action": {
      "name": "catalog_message",
      "parameters": { 
        "thumbnail_product_retailer_id": "<Product-retailer-id>"
      }
    }
  }
}'

플로 메시지

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "interactive",
  "interactive" : {
    "type": "flow",
    "header": {
      "type": "text",
      "text": "Flow message header"
    },
    "body": {
      "text": "Flow message body"
    },
    "footer": {
      "text": "Flow message footer"
    },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s",
        "flow_id": "<FLOW_ID>",
        "flow_cta": "Book!",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "<SCREEN_ID>",
          "data": {
            "user_name": "name",
            "user_age": 25
          }
        }
      }
    }
  }
}'

리스트 메시지

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "HEADER_TEXT"
    },
    "body": {
      "text": "BODY_TEXT"
    },
    "footer": {
      "text": "FOOTER_TEXT"
    },
    "action": {
      "button": "BUTTON_TEXT",
      "sections": [
        {
          "title": "SECTION_1_TITLE",
          "rows": [
            {
              "id": "SECTION_1_ROW_1_ID",
              "title": "SECTION_1_ROW_1_TITLE",
              "description": "SECTION_1_ROW_1_DESCRIPTION"
            },
            {
              "id": "SECTION_1_ROW_2_ID",
              "title": "SECTION_1_ROW_2_TITLE",
              "description": "SECTION_1_ROW_2_DESCRIPTION"
            }
          ]
        },
        {
          "title": "SECTION_2_TITLE",
          "rows": [
            {
              "id": "SECTION_2_ROW_1_ID",
              "title": "SECTION_2_ROW_1_TITLE",
              "description": "SECTION_2_ROW_1_DESCRIPTION"
            },
            {
              "id": "SECTION_2_ROW_2_ID",
              "title": "SECTION_2_ROW_2_TITLE",
              "description": "SECTION_2_ROW_2_DESCRIPTION"
            }
          ]
        }
      ]
    }
  }
}'

답장 버튼

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": {
      "text": "BUTTON_TEXT"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "UNIQUE_BUTTON_ID_1",
            "title": "BUTTON_TITLE_1"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "UNIQUE_BUTTON_ID_2",
            "title": "BUTTON_TITLE_2"
          }
        }
      ]
    }
  }
}'

템플릿 메시지

대화 기반 가격이 변경되었습니다. 새로운 대화 기반 가격 모델의 적용 방법에 대해 알아보려면 가격을 참조하세요.

또한 metric_types의 표시 방식이 2023년 7월 1일부터 변경되었습니다. 자세한 내용은 전환 분석 표를 참조하세요.

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "http(s)://URL"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "TEXT_STRING"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "VALUE",
              "code": "USD",
              "amount_1000": NUMBER
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "MONTH DAY, YEAR"
            }
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "0",
        "parameters": [
          {
            "type": "payload",
            "payload": "PAYLOAD"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "1",
        "parameters": [
          {
            "type": "payload",
            "payload": "PAYLOAD"
          }
        ]
      }
    ]
  }
}'

메시지에 답장 보내기

curl -X POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "context": {
     "message_id": "MESSAGE_ID"
  },
  "to": "PHONE_NUMBER",
  "type": "text",
  "text": {
    "preview_url": false,
    "body": "your-text-message-content"
  }
}’

성공적인 응답

    {
      "messaging_product": "whatsapp",
      "contacts": [
        {
          "input": "16505555555",
          "wa_id": "16505555555"
        }
      ],
      "messages": [
        {
          "id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA"
        }
      ]
    }

Applies to businesses in Brazil, Colombia, and Singapore, starting September 12, 2023. Applies to all businesses starting October 12, 2023.

Messages will have one of the following statuses which will be returned in each of the messages objects

  • "message_status":"accepted" : means the message was sent to the intended recipient
  • "message_status":"held_for_quality_assessment": means the message send was delayed until quality can be validated and it will either be sent or dropped at this point

      {
      "messaging_product": "whatsapp",
      "contacts": [
        {
          "input": "16505555555",
          "wa_id": "16505555555"
        }
      ],
      "messages": [
        {
          "id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA",
          "message_status": "accepted",
        }
      ]
    }