메시지

/v1/messages

messages 노드를 사용하여 고객에게 메시지 템플릿과 문자, 미디어, 연락처, 위치, 인터랙티브 메시지를 전송합니다.

전송할 수 있는 구체적인 메시지 유형과 관련된 정보는 문자 메시지, 미디어 메시지, 연락처 및 위치 메시지, 인터랙티브 메시지, 메시지 템플릿, 미디어 메시지 템플릿, 인터랙티브 메시지 템플릿 가이드를 참조하세요.

시작하기 전에

다음 항목이 필요합니다.

• 본인을 인증하고 서비스에 액세스하기 위한 인증 토큰을 받습니다. 진행 방법에 대한 자세한 내용은 로그인 및 인증 문서를 참조하세요.
• 메시지를 보내고자 하는 WhatsApp 계정을 인증하고 WhatsApp 사용자 ID를 가져오는 방법에 대해 자세히 알아보려면 연락처 문서를 참조하세요.
• 메시지의 컷오프 제어 서비스 요구 사항을 준수합니다.

제약 사항

• 지원되는 메시지 유형은 문자, 메시지 템플릿, 이미지, 문서, 오디오입니다.
• 문자 메시지는 최대 4,096자까지 가능합니다.

만들기

메시지 유형과 관계없이 /messages 노드로 POST 호출을 보내서 메시지를 전송합니다. JSON 메시지 본문 내용은 메시지 유형(예: 문자, 이미지)에 따라 다릅니다.

매개변수

/messages POST 요청에서 사용하는 주요 매개변수는 다음과 같습니다.

텍스트 개체

미디어 개체

온프레미스 API의 경우 media 엔드포인트를 통해 WhatsApp Business 온프레미스/참조 클라이언트에 미디어가 성공적으로 업로드되면 미디어 개체 ID가 반환됩니다.

연락처 개체

contacts 내에서 addresses, emails, name, org, phone 및 urls 개체를 중첩할 수 있습니다. 복수화된 개체는 아래의 예와 같이 배열로 래핑됩니다.

내부에 복수화된 개체를 중첩한 contacts 개체의 예는 다음과 같습니다.

"contacts": [
    {
        "addresses": [
            {
                "city": "city name",
                "country": "country name",
                "country_code": "code",
                "state": "Contact's State",
                "street": "Contact's Street",
                "type": "Contact's Address Type",
                "zip": "Contact's Zip Code"
            }
        ],
        "birthday": "birthday",
        "emails": [
            {
                "email": "email",
                "type": "HOME"
            },
            {
                "email": "email",
                "type": "WORK"
            }
        ],
        "name": {
            "first_name": "first name value",
            "formatted_name": "formatted name value",
            "last_name": "last name value",
            "suffix": "suffix value"
        },
        "org": {
            "company": "company name",
            "department": "dep name",
            "title": "title"
        },
        "phones": [
            {
                "phone": "Phone number",
                "wa-id": "WA-ID value",
                "type": "MAIN"
            },
            {
                "phone": "Phone number",
                "type": "HOME"
            },
            {
                "phone": "Phone number",
                "type": "WORK"
            }
        ],
        "urls": [{
            "url": "some url",
            "type": "WORK"
        }]
    }
]

위치 개체

템플릿 개체

template 안에서 components 및 language 개체를 중첩할 수 있습니다.

구성 요소 개체

components 안에서 parameters 개체를 중첩할 수 있습니다. 또한 type을 button으로 설정할 수 있습니다.

매개변수 개체

버튼 유형

components 개체 안에서 type을 button으로 설정할 수 있습니다. 버튼 매개변수는 다음과 같습니다.

sub_type quick_reply를 포함한 button 유형의 예는 다음과 같습니다.

 {
    "type": "button",
    "sub_type": "quick_reply",
    "index": 0,
    "parameters": 
     [{
    	"type": "payload",
    	"payload": "Yes-Button-Payload"
     }]
 } 

sub_type copy_code를 포함한 button 유형의 예는 다음과 같습니다.

    
 { 
    "type": "button", 
    "sub_type": "copy_code", 
    "index": 0, 
    "parameters": 
    [{ 
     "type": "coupon_code", 
     "coupon_code": "DISCOUNT20" 
    }] 
 }

Hsm 개체

인터랙티브 개체

행동 개체

예

오디오 메시지:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "audio",
  "audio": {
      "id": "your-media-id",
  }
}

문서 메시지(filename 사용):

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "document",
  "document": {
      "id": "your-media-id",
      "filename": "your-document-filename"
  }
}

문서 메시지(link 사용):

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "document",
  "document": {
      "link": "http(s)://the-url"
      "provider": {
          "name" : "provider-name"
      }     
    }
}

동영상 메시지(link 사용):

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "video",  
  "video": {
      "link": "http(s)://the-url"
      "provider": {
          "name" : "provider-name"
      }
    }
  }
}

문자 메시지:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "text",
  "text": {
      "body": "your-message-content"
  }
}

인터랙티브 메시지(리스트):

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "interactive",
  "interactive":{
    "type": "list",
    "header": {
      "type": "text",
      "text": "your-header-content-here"
    },
    "body": {
      "text": "your-text-message-content-here"
    },
    "footer": {
      "text": "your-footer-content-here"
    },
    "action": {
      "button": "cta-button-content-here",
      "sections":[
        {
          "title":"your-section-title-content-here",
          "rows": [
            {
              "id":"unique-row-identifier-here",
              "title": "row-title-content-here",
              "description": "row-description-content-here",           
            }
          ]
        },
        {
          "title":"your-section-title-content-here",
          "rows": [
            {
              "id":"unique-row-identifier-here",
              "title": "row-title-content-here",
              "description": "row-description-content-here",           
            }
          ]
        },
        ...
      ]
    }
  }

}

인터랙티브 메시지(답장 버튼):

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": { # optional
      "type": "text" | "image" | "video" | "document",
      "text": "your text"
      # OR
      "document": {
        "id": "your-media-id",
        "filename": "some-file-name"
      }
      # OR
      "document": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name",
        },
        "filename": "some-file-name"
      },
      # OR
      "video": {
        "id": "your-media-id"
      }
      # OR
      "video": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
      # OR
      "image": {
        "id": "your-media-id"
      }
      # OR
      "image": {
        "link": "http(s)://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
    }, # end header
    "body": {
      "text": "your-text-body-content"
    },
    "footer": { # optional
      "text": "your-text-footer-content"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "First Button’s Title" 
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "Second Button’s Title" 
          }
        }
      ] 
    } # end action   
  } # end interactive

}

인터랙티브 메시지(다중 및 단일 제품 메시지):

{ 
  "recipient_type": "individual",
  "to" : "{{Recipient-WA-ID}}",
  "type": "interactive",
  "interactive": {
    "type": "product",
    "body": {
      "text": "body text"
    },
    "footer": {
      "text": "footer text"
    },
    "action": {
      "
      
      _id": "catalog-ID",
      "product_retailer_id": "product-ID"
    }
  }
}

인터랙티브 메시지(다중 제품 메시지):

{ 
  "recipient_type": "individual",
  "to" : "whatsapp-id",
  "type": "interactive",
  "interactive": 
    {
    "type": "product_list",
    "Header":{
       "type": "text",
        "text": "text-header-content"
     },
     "body":{
        "text": "text-body-content"
      },
     "footer":{
        "text":"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": "the-section-title",
              "product_items": [
                 { "product_retailer_id": "product-SKU-in-catalog" }
                           ...
              ]},
               ...
       ]
     },  
    }
}

인터랙티브 메시지(카탈로그 메시지):

{ 
  "recipient_type": "individual",
  "to" : "whatsapp-id",
  "type": "interactive",
  "interactive": 
    {
    "type": "catalog_message",
     "body":{
        "text": "text-body-content"
      },
     "footer":{
        "text":"text-footer-content"
     },
     "action":{
        "name": "catalog_message",
      	"parameters":{ 
      	  "thumbnail_product_retailer_id": "product-SKU-in-catalog"
      	}
     },  
    }
}

인터랙티브 메시지(플로):

{
  "recipient_type": "individual",
  "to": "{{Recipient-WA-ID}}",
  "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": { # optional
            "user_name": "name",
            "user_age": 25
          }
        }
      }
    }
  }
}

응답의 payload 예시는 다음과 같습니다. 메타와 오류 개체는 간결함을 위해 생략했습니다.

{
  "messages": [{ 
    "id": "message-id" 
  }]    
}

요청이 성공하면 메시지 ID가 포함된 응답을 수신합니다. 요청이 errors 섹션을 반환하면 원본 메시지를 확인하고 오류를 수정한 다음 요청을 다시 보내세요. 오류에 대한 자세한 내용은 WhatsApp Business 온프레미스/참조 클라이언트 오류 코드 및 HTTP 상태 코드를 참조하세요.

품질 평가를 위해 요청이 보류되는 경우, 메시지가 즉시 전송되지 않았고 품질이 검증된 후에 전송되거나 드롭될 것임을 나타내는 메시지와 함께 message_status 속성이 응답에 포함됩니다. 이 속성은 메시지가 보류되는 경우에만 존재합니다.

    {
      "messages": [{ 
        "id": "message-id",
        "message_status": "Message has been held because quality assessment is pending",
      }]    
    }
    

문자 메시지에서 형식화

WhatsApp은 메시지에서 몇 가지 형식화가 가능합니다. 전체 또는 일부 메시지를 형식화하려면 다음의 형식화 기호를 사용하세요.

성능

이 경우 성능은 WhatsApp Business 온프레미스/참조 클라이언트를 사용하여 1초에 보낼 수 있는 메시지 수를 나타냅니다. 달성 가능한 최대 성능은 여러 가지 요소에 따라 달라집니다. 클라이언트 설정으로 무엇을 선택했는지, 메시지가 새로운 사용자 또는 기존 사용자에게 전송되었는지 여부가 가장 중요합니다. 새로운 사용자에게 메시지를 보낼 때 암호화 세션 설정은 시간이 다소 오래 걸릴 수 있습니다.

FAQ

더 알아보기

• 로그인 및 인증 문서
• 연락처 문서
• WhatsApp Business 온프레미스/참조 클라이언트 오류 코드
• HTTP 상태 코드