Skip to content

WhatsApp API mt

Jump to bottom
Jcateye edited this page Jul 3, 2024 · 30 revisions

Send Message

Initiate WhatsApp number message sending service through API

  • URL: https://api2.nxcloud.com/api/wa/mt
  • Method: POST
  • Content-Type: application/json
  • Requires authentication: Yes

Authentication Mechanism

Please refer to the following link for authentication rules: API Interface Call Agreement

Request Parameters

Header Parameters:

Parameter Type Required Example Description
accessKey String Yes fme2na3kdi3ki User identity identifier
ts String Yes 1655710885431 Current timestamp of the request (in milliseconds). The maximum time difference allowed between the user and the Nuix server is 60 seconds.
bizType String Yes 2 WhatsApp business type, fixed value: "2"
action String Yes mt WhatsApp business operation, fixed value: "mt"
sign String Yes 6e9506557d1f289501d333ee2c365826 API input parameter signature, signature algorithm

Body Parameters:

Parameter Type Required Example Description
appkey String Yes pem28kje Application appkey
business_phone String Yes 86158xxxx1795 WhatsApp number of the message sender, including the country code. For example, 86158xxxx1795
messaging_product String Yes whatsapp Channel for sending messages. When sending WhatsApp messages, the value must be "whatsapp".
recipient_type String Yes individual Type of message recipient. When sending WhatsApp messages, the value must be "individual".
to String Yes 86158xxxx1795 WhatsApp number of the message recipient, including the country code. For example, 86158xxxx1795
type String Yes text Supports the following message types:
1. text: Text
2. image: Image
3. video: Video
4. audio: Audio
5. document: Document
6. location: Location
7. sticker: Sticker
8. template: Template
9. interactive: Interactive
10. reacticon: Reacticon

Message Types

  1. Parameters for text messages:
Parameter Type Required Example Description
text JsonObject No Refer to the request example Content of the text message. Required when type=text.
context JsonObject No Refer to the request example This object contains the meta message ID of your previous response
  • Parameters for the text object:
Parameter Type Required Example Description
body String Yes - Text message body, which can contain URLs or formatting tags. The formatting tags are explained as follows: Bold: Text to be bolded, such as Your total is $10.50. Italic: Text to be italicized, such as Your total is $10.50. Strikethrough: Text to be strik ethrough, such as Your total is $10.50.
preview_url boolean No - Whether to enable URL preview. Set to true to enable preview, false to disable preview. The URL must start with "http://" or "https://". URL preview is a message rendering feature supported by the WhatsApp client.
  • Parameters for the context object:
Parameter Type Required Example Description
message_id String Yes - meta message id
  1. Parameters for image messages:
Parameter Type Required Example Description
image JsonObject No Refer to the request example Content of the image message. Required when type=image.
  • Parameters for the image object:
Parameter Type Required Example Description
link String No (either link or id is required) - URL link of the image. It must be an HTTP/HTTPS URL.
id String No (either link or id is required) - Storage ID of the image obtained after uploading the file through the Media interface.
caption String No - Image description
  1. Parameters for video messages:
Parameter Type Required Example Description
video JsonObject No Refer to the request example Content of the video message. Required when type=video.
  • Parameters for the video object:
Parameter Type Required Example Description
link String No (either link or id is required) - URL link of the video file. It must be an HTTP/HTTPS URL.
id String No (either link or id is required) - Storage ID of the video file obtained after uploading through the Media interface.
caption String No - Video description
  1. Parameters for audio messages:
Parameter Type Required Example Description
audio JsonObject No Refer to the request example Content of the audio message. Required when type=audio.
  • Parameters for the audio object:
Parameter Type Required Example Description
link String No (either link or id is required) - URL link of the audio file. It must be an HTTP/HTTPS URL.
id String No (either link or id is required) - Storage ID of the audio file obtained after uploading through the Media interface.
  1. Document message parameters:
Parameter Type Required Example Description
document JsonObject No Refer to the request example Content of the document message. Required when type=document.
  • Parameters for the document object:
Parameter Type Required Example Description
link String No (either link or id is required) - URL link of the document file. It must be an HTTP/HTTPS URL.
id String No (either link or id is required) - Storage ID of the document file obtained after uploading through the Media interface.
filename String No - Document file name.
  1. Location message parameters:
Parameter Type Required Example Description
location JsonObject No Refer to the request example Content of the location message. Required when type=location.
  • Parameters for the location object:
Parameter Type Required Example Description
longitude Double Yes - Longitude information.
latitude Double Yes - Latitude information.
name String No - Name of the location.
address String No - Detailed address information of the location.
  1. Sticker message parameters:
Parameter Type Required Example Description
sticker JsonObject No Refer to the request example Content of the sticker message. Required when type=sticker.
  • Parameters for the sticker object:
Parameter Type Required Example Description
link String No (either link or id is required) - URL link of the sticker file. It must be an HTTP/HTTPS URL.
id String No (either link or id is required) - Storage ID of the sticker file obtained after uploading through the Media interface.
  1. Template message parameters:
Parameter Type Required Example Description
template JsonObject No Refer to the request example Content of the template message. Required when type=template.
  • Parameters for the template object:
Parameter Type Required Example Description
name String Yes - Template name.
language JsonObject Yes - Template language settings.
components array[component JsonObject] No - Variable settings for template components.
  • Parameters for the language object:
Parameter Type Required Example Description
code String Yes - Language code. Refer to supported template languages.
policy String Yes - Fixed value: deterministic.
  • Parameters for the component object:
Parameter Type Required Example Description
type String Yes - Component type, can be header, body, button.
1) When type=header, set variable information for the template header.
2) When type=body, set variable information for the template content.
3) When type=button, set variable information for the template buttons.
sub_type String No - Button type created, only required when type=button, can be url, quick_reply. Not applicable for other types.
index String No - Button position index, only required when type=button, button's index, value range is 0-2.
parameters array[parameter JsonObject] No - Component parameter list.
  • Parameters for the parameter object:
Parameter Type Required Example Description
type String Yes - Where:
1) When the component object's type=header, it can be text, image, video, document;
2) When the component object's type=body, it takes the value text;
3) When the component object's type=button and sub_type=url, it takes the value text; when the component object's type=button and sub_type=quick_reply, it takes the value payload.
text String No - Only required when type=text, set the text content for the corresponding parameter. Not applicable for other types.
payload String No - Only required when type=payload, set the payload content for the corresponding parameter. Refer to the video message for payload object definition. Not applicable for other types.
image JsonObject No - Only required when type=image, set the image content for the corresponding parameter. Refer to the image message for image object definition. Not applicable for other types.
video JsonObject No - Only required when type=video, set the video content for the corresponding parameter. Refer to the video message for video object definition. Not applicable for other types.
document JsonObject No - Only required when type=document, set the document content for the corresponding parameter. Refer to the document message for document object definition. Not applicable for other types.
  1. Interactive message parameters:
Parameter Type Required Example Description
interactive JsonObject No Refer to the request example type=interactive required
  1. Reaction message parameters:
Parameter Type Required Example Description
reaction JsonObject No Refer to the request example type=reaction required
  • reaction object parameters:
Parameter Type Required Example Description
message_id String Yes wamid.HBgNODYxMzE2MzczMTQ2NxUCABIYEkVCQkE4NjdGRUE5RDgyQzg0RAA= meta message id
emoji String Yes ❤️

Request Example

Text Message Request Example

body（application/json） parameter：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "text",
    "text": {
        "body": "text-message-content",
        "preview_url": false
    }
}

Example of Image Message Request

body（application/json） parameter：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "image",
    "image": {
        "id": "5867096a-a9be-4a56-94d6-89377623b4ac",
        "caption":"image test"
    }
}

Example of video message request

body（application/json） parameter：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "video",
    "video": {
        "id": "5867096a-a9be-4a56-94d6-89377623b4ac",
        "caption":"video test"
    }
}

Example of Audio Message Request

body（application/json） parameter：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "audio",
    "audio": {
        "id": "a51ca059-e12e-4838-b28b-d471773efb71"
    }
}

Example of Document Message Request

body（application/json） parameter：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "document",
    "document": {
        "id": "5867096a-a9be-4a56-94d6-89377623b4ac",
        "filename":"document-test"
    }
}

Example of texture emoticon message request

body（application/json） parameter：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "sticker",
    "sticker": {
        "id": "5867096a-a9be-4a56-94d6-89377623b4ac"
    }
}

Example of Location Message Request

body（application/json） parameter：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "location",
    "location": {
        "latitude": "22.550802897696343",
        "longitude": "113.93844723701477",
        "name": "Guangdong Shenzhen",
        "address": "Ke Xing Science Park"
    }
}

Sample Template Message Request

  • Template message (parameter template message)

body（application/json） parameter：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "template",
    "template": {
		"name": "text_template",
		"language": {
			"code": "en_US",
			"policy": "deterministic"
		},
		"components": [
			{
				"type": "body",
				"parameters": [
					{
						"type": "text",
						"text": "David"
					},
					{
						"type": "text",
						"text": "B520"
					}
				]
			}
		]
	}
}
  • Template message (copy verification code message)

body（application/json） parameter：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "template",
    "template": {
        "name": "otp_test_02",
        "language": {
            "policy": "deterministic",
            "code": "zh_CN"
        },
        "components": [
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "123456"
                    }
                ]
            },
            {
                "type": "button",
                "sub_type": "url",
                "index": "0",
                "parameters": [
                    {
                        "type": "text",
                        "text": "123456"
                    }
                ]
            }
        ]
    }
}

Interactive-Message-Request

  • Interactive-Message(list)
{
  "appkey": "f54xxxtg",
  "business_phone": "185xxxx8399",
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "86136xxxx9759",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "What to eat today"
    },
    "body": {
      "text": "Choose your favorite food"
    },
    "footer": {
      "text": "nxcloud"
    },
    "action": {
      "button": "Which instant noodles do you like the most",
      "sections": [
        {
          "title": "Seafood",
          "rows": [
            {
              "id": "1",
              "title": "Seafood noodles",
              "description": "Noodles with fresh shrimp and fish"
            }
          ]
        },
        {
          "title": "Beef",
          "rows": [
            {
              "id": "2",
              "title": "Beef noodles",
              "description": "Braised beef noodles"
            }
          ]
        },
        {
          "title": "Mushroom",
          "rows": [
            {
              "id": "3",
              "title": "Chicken",
              "description": "Chicken and mushroom noodles"
            }
          ]
        },
        {
          "title": "Braised Pork",
          "rows": [
            {
              "id": "4",
              "title": "Sour cabbage noodles",
              "description": "Noodles with preserved vegetable and braised pork"
            }
          ]
        },
        {
          "title": "Red Soup",
          "rows": [
            {
              "id": "5",
              "title": "Tomato and egg",
              "description": "Tomato and beef noodles"
            }
          ]
        }
      ]
    }
  }
}
  • Interactive-Message(reply)
{
  "appkey": "f54xxxtg",
  "business_phone": "185xxxx8399",
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "86136xxxx9759",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": {
      "text": "If you could start your life over, would you be willing?"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "1",
            "title": "Willing"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "2",
            "title": "Unwilling"
          }
        }
      ]
    }
  }
}
  • Interactive-Message(cta)
{
    "appkey": "f54xxxtg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "interactive",
    "interactive": {
        "type": "cta_url",
        "header": {
            "type": "image",
            "image": {
                "link": "https://www.nxcloud.com/img/kv_visual_01.a1d1602e.png"
            }
        },
        "body": {
            "text": " Drive international success for your business through our trusted industry leading partners. "
        },
        "footer": {
            "text": "nxcloud"
        },
        "action": {
            "name": "cta_url",
            "parameters": {
                "display_text": "NXCloud",
                "url": "https://www.nxcloud.com"
            }
        }
    }
}
  • Interactive-Message(catalog)
{
    "appkey": "f54xxxtg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "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": "3qfw7ouze4"
            }
        }
    }
}
  • Interactive-Message(single product)
{
    "appkey": "f54xxxtg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "interactive",
     "interactive": {
     "type": "product",
     "body": {
       "text": "optional body text"
     },
     "footer": {
       "text": "optional footer text"
     },
     "action": {
       "catalog_id": "129002493482066",
       "product_retailer_id": "3qfw7ouze4"
     }
   }
}
  • Interactive-Message(Multiple product)
{
    "appkey": "f54xxxtg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "interactive",
    "interactive": {
    "type": "product_list",
    "header": {
      "type": "text",
      "text": "header-content"
    },
    "body": {
      "text": "optional body text"
    },
    "footer": {
      "text": "optional footer text"
    },
    "action": {
      "catalog_id": "129002493482066",
      "product_retailer_id": "3qfw7ouze4",
      "sections": [
        {
          "title": "section-title",
          "product_items": [
            {
              "product_retailer_id": "3qfw7ouze4"
            },
            {
              "product_retailer_id": "cm2i4b15t7"
            }
          ]
        },
        {
          "title": "section-title",
          "product_items": [
            {
              "product_retailer_id": "3qfw7ouze4"
            }
          ]
        }
      ]
    }
  }
}
  • Interactive-Message（flow）
{
    "appkey": "f54xxxtg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "interactive",
     "interactive": {
     "type": "flow",
     "body": {
       "text": "optional body text"
     },
     "footer": {
       "text": "optional footer text"
     },
     "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s",
        "flow_id": "7524375840909375",
        "flow_cta": "提交!",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "QUESTION_ONE",
          "data": {
            "demo": "5"
          }
        }
      }
    }
   }
}

Reaction-Message-Request

body（application/json）

{
    "appkey": "f54xxxtg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "reaction",
     "reaction": {
     "message_id": "<meta_message_id>",
     "emoji": "❤️"
   }
}

Response Parameters

Parameter Name Type Description
code Integer Result code
data JsonObject Request result
message String Description of the request result

Successful response

  • data object parameters:
Parameter Name Type Description
messaging_product String Type of communication channel
messages array[message JsonObject] Message sequence
  • message object parameters:
Parameter Name Type Description
id String Unique ID generated by the system

Failed response, meta error

  • data object parameters:
Parameter Name Type Description
error JsonObject Meta error
  • error object parameters:
Parameter Name Type Description
code String Meta code
message String Meta error message
type String Meta error type
fbtrace_id String Meta trace
error_data JsonObject Meta error data
  • error_data object parameters:
Parameter Name Type Description
messaging_product String Type of communication channel
details String Meta error details

Response Examples

Successful Example

{
    "code": 0,
    "data": {
        "messaging_product": "whatsapp",
        "messages": [
            {
                "id": "gBGHhhdgYFCBnwIJ6QRYvhwQk7Nc"
            }
        ]
    },
    "message": "Request succeeded"
}

Failed Example

nxcloud failure

{
    "code": -1,
    "message": "Request failed",
    "data": null
}

meta failure

{
    "code": 9099,
    "message": "WhatsApp error",
    "data":{
        "error":{
            "code":100,
            "message":"(#100) Invalid parameter",
            "type":"OAuthException",
            "fbtrace_id":"AmCuD7sOjcEDetBNhlT2cJm",
            "error_data":{
                "messaging_product":"whatsapp",
                "details":"Invalid parameter"
            }
        }
    }
}

Explanation of Response Codes

code message Solution
0 Request succeeded
-1 Request failed nxcloud failure, please contact technical personnel to troubleshoot the issue
1000~100X Authentication issue nxcloud failure, see details in the API authentication section
9000 Parameter exception nxcloud failure, missing parameters, please check the required parameters
9001 System business error nxcloud failure, please contact technical personnel to troubleshoot the issue
9002 Incorrect merchant phone number nxcloud failure, please confirm if the merchant number belongs to a WhatsApp number
9003 Application does not exist/unavailable nxcloud failure, contact business personnel to handle the creation/disabling of the cloud platform application
9004 No corresponding country price for the application nxcloud failure, contact business personnel to handle the application pricing issue
9005 Insufficient account balance nxcloud failure, please contact business personnel for recharge
9006 The WhatsApp number is not bound to the application nxcloud failure, please contact business personnel to handle the binding operation between the application and the phone number
9007 Downstream communication port exception nxcloud failure, please contact technical personnel to troubleshoot the issue
9099 WhatsApp error meta failure, official meta error prompt

Template Language

Language Code   Language Code   Language Code
Afrikaans af   Greek el   Portuguese (BR) pt_BR
Albanian sq   Gujarati gu   Portuguese (POR) pt_PT
Arabic ar   Hebrew he   Punjabi pa
Azerbaijani az   Hindi hi   Romanian ro
Bengali bn   Hungarian hu   Russian ru
Bulgarian bg   Indonesian id   Serbian sr
Catalan ca   Irish ga   Slovak sk
Chinese (CHN) zh_CN   Italian it   Slovenian sl
Chinese (HKG) zh_HK   Japanese ja   Spanish es
Chinese (TAI) zh_TW   Kannada kn   Spanish (ARG) es_AR
Croatian hr   Kazakh kk   Spanish (SPA) es_ES
Czech cs   Korean ko   Spanish (MEX) es_MX
Danish da   Lao lo   Swahili sw
Dutch nl   Latvian lv   Swedish sv
English en   Lithuanian lt   Tamil ta
English (UK) en_GB   Macedonian mk   Telugu te
English (US) en_US   Malay ms   Thai th
Estonian et   Marathi mr   Turkish tr
Filipino fil   Norwegian nb   Ukrainian uk
Finnish fi   Persian fa   Urdu ur
French fr   Polish pl   Uzbek uz
German de   Hausa  ha    Vietnamese vi
Malayalam ml   Zulu zu  

Introduction

WhatsApp

Short message

Voice

Call Center(NXLink)

Call Center(Callbot)

Flash Call

Short links

邮件验证码

DID号码

通用

号码检测

Clone this wiki locally