訊息

/v1/messages

使用 messages 節點來向您的顧客傳送文字訊息、媒體、聯絡人、位置、互動式訊息和訊息範本。

請參閱下列指南，了解有關您可傳送的特定訊息類型之資訊：文字訊息、媒體訊息、聯絡人和地點訊息、互動式訊息、訊息範本、媒體訊息範本，以及互動式訊息範本。

準備工作

您需要以下事項：

• 驗證自己的身分，然後接收可以用來存取此服務的驗證憑證。如要進一步了解如何執行此操作，請參閱登入和驗證文件。
• 如要驗證您想向其傳送訊息的 WhatsApp 帳戶，並獲取其 WhatsApp 用戶帳號，請參閱聯絡人聯絡人文件了解相關操作。
• 符合訊息阻斷控制服務要求。

限制

• 系統支援以下訊息類型：文字、訊息範本、圖像、文件和音訊。
• 文字訊息長度不得多於 4096 個字元。

建立

無論是何種訊息類型，系統都會向 /messages 節點傳送 POST 呼叫來傳送訊息。對於每種類型的訊息（文字、圖像等），JSON 訊息內文的內容會有所不同。

參數

/messages POST 要求中使用的主要參數如下：

text 物件

media 物件

對於內部部署 API，媒體物件編號是使用 media 端點將媒體成功上載至 WhatsApp Business API（詳見「內部部署 API」>「參考資料」）用戶端時所傳回的編號。

contacts 物件

在 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"
        }]
    }
]

location 物件

template 物件

在 template 中，您可以嵌套 components 和 language 物件。

components 物件

在 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 物件

interactive 物件

action 物件

範例

音訊訊息：

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" 
  }]    
}

如果這項要求成功，您會收到包含訊息編號的回應。如果這項要求傳回 errors 部分，請查看原始訊息並更正錯誤，然後再重新傳送要求。如需有關錯誤的詳細資訊，請參閱 WhatsApp Business API（詳見「內部部署 API」>「參考資料」）用戶端錯誤代碼和 HTTP 狀態代碼。

如這項要求因品質評估而暫緩傳送，您就會在回應中收到 message_status 屬性，以及一則指明訊息未能立即傳送並會在驗證品質後傳送或遭棄置的訊息。您只會在訊息遭暫緩傳送的情況下看到此屬性。

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

設定文字訊息的格式

WhatsApp 允許您在訊息加入格式。如要為訊息的全部或部分內容設定格式，請使用下列格式符號：

成效

在本建議的背景中，「成效」表示可透過 WhatsApp Business API（詳見「內部部署 API」>「參考資料」）用戶端在任何既定秒數內傳送的訊息數量。可達到的最高成效視乎多種因素而定，而其中最重要的因素是您的用戶端設定選擇，以及接收訊息的對象是新用戶還是現有用戶。例如，在向新用戶傳送訊息時，系統需要多一點時間來設定加密連線階段。

常見問題

了解詳情

• 登入和驗證文件
• 聯絡人文件
• WhatsApp Business API（詳見「內部部署 API」>「參考資料」）用戶端錯誤代碼
• HTTP 狀態代碼