WhatsApp API mt - nxtele/nxcloud-doc-en GitHub Wiki

Send Message

Initiate WhatsApp number message sending service through the 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 Convention

Request Parameters

Header Parameters:

Parameter Name Type Required Example Description
accessKey String Yes fme2na3kdi3ki User identity identifier
ts String Yes 1655710885431 Current timestamp of the request (in milliseconds). The maximum allowed time difference is 60 seconds on the server side.
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 Name Type Required Example Description
appkey String Yes Appkey of the NxCloud WhatsApp application
business_phone String Yes 86158xxxx1795 WhatsApp number of the message sender, including country code. e.g., 86158xxxx1795
messaging_product String Yes whatsapp Channel for sending messages, must be "whatsapp" when sending WhatsApp messages
recipient_type String Yes individual Type of message recipient, must be "individual" when sending WhatsApp messages
to String Yes 86158xxxx1795 WhatsApp number of the message recipient, including country code. e.g., 86158xxxx1795
type String Yes text Type of message to be sent. Supported types:1. text2. image3. video4. audio5. document6. location7. sticker8. template
cus_message_id String No wamid.HBgLODUyNTUzMTE3MDUVAgARGBI Custom message ID. It will be returned as the message ID in both the message submission success and status callback. Please ensure it is globally unique.
dr_webhook String No https://test.com/webhook The message status callback will be pushed to this URL first. If not provided, it will be pushed to the app webhook. The HTTP status code returned by the webhook interface must be 200.
biz_opaque_callback_data String No Any string helpful for tracking. For example, you can pass a message template number here to track the customer journey from the first message sent. Then, you can track the return on investment (ROI) for different message template types to identify the most effective ones. This string is included in the "statuses" object of the Webhooks payload, so any application subscribed to the messages Webhooks field in the WhatsApp Business account will receive this string. This field is not processed and will only be returned as part of the sent/delivered/read message Webhooks.
api_type int No 0 API type. 0 represents Cloud API, 1 represents MM Lite API. If not provided, the default is 0.

Message Types

  1. Text Message Parameters:
Parameter Name Type Required Example Description
context JsonObject No See Request Example This object contains the message ID you are responding to from the previous messages.
text JsonObject No See Request Example Text message content, required when type=text
  • context object parameters:
Parameter Name Type Required Example Description
message_id String Yes - message ID.
  • text object parameters:
Parameter Name Type Required Example Description
body String Yes - Text message body, can include URLs or formatted identifiers. Formatting identifiers are as follows: Bold: text; Italic: text; Strikethrough: text.
preview_url boolean No - Whether to enable URL preview. Set to true to enable preview, set to false to disable preview. URLs must start with http:// or https:// and only domain-based links are recognized (IP-based links are not recognized). URL preview is a message presentation feature supported by the WhatsApp client.
  1. Image Message Parameters:
Parameter Name Type Required Example Description
image JsonObject No See Request Example Image message content, required when type=image
  • image object parameters:
Parameter Name Type Required Example Description
link String No (Either link or id is required) - URL link of the image. 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 caption.
  1. Video Message Parameters:
Parameter Name Type Required Example Description
video JsonObject No See Request Example Video message content, required when type=video
  • video object parameters:
Parameter Name Type Required Example Description
link String No (Either link or id is required) - URL link of the video file. Must be an HTTP/HTTPS URL.
id String No (Either link or id is required) - Storage ID of the video file. Obtained after uploading the file through the Media interface.
caption String No - Video caption.
  1. Audio Message Parameters:
Parameter Name Type Required Example Description
audio JsonObject No See Request Example Audio message content, required when type=audio
  • audio object parameters:
Parameter Name Type Required Example Description
link String No (Either link or id is required) - URL link of the audio file. Must be an HTTP/HTTPS URL.
id String No (Either link or id is required) - Storage ID of the audio file. Obtained after uploading the file through the Media interface.
  1. Document Message Parameters:
Parameter Name Type Required Example Description
document JsonObject No See Request Example Document message content, required when type=document
  • document object parameters:
Parameter Name Type Required Example Description
link String No (Either link or id is required) - URL link of the document file. Must be an HTTP/HTTPS URL.
id String No (Either link or id is required) - Storage ID of the document file. Obtained after uploading the file through the Media interface.
filename String No - Document file name.
  1. Location Message Parameters:
Parameter Name Type Required Example Description
location JsonObject No See Request Example Location message content, required when type=location
  • location object parameters:
Parameter Name Type Required Example Description
longitude Double Yes - Longitude information.
latitude Double Yes - Latitude information.
name String No - Location name.
address String No - Detailed address information.
  1. Sticker Message Parameters:
Parameter Name Type Required Example Description
sticker JsonObject No See Request Example Sticker message content, required when type=sticker
  • sticker object parameters:
Parameter Name Type Required Example Description
link String No (Either link or id is required) - URL link of the sticker file. Must be an HTTP/HTTPS URL.
id String No (Either link or id is required) - Storage ID of the sticker file. Obtained after uploading the file through the Media interface.
  1. Template Message Parameters:
Parameter Name Type Required Example Description
template JsonObject No See Request Example Template message content, required when type=template
  • template object parameters:
Parameter Name 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.
  • language object parameters:
Parameter Name Type Required Example Description
code String Yes - Language code, see supported template languages.
policy String Yes - Fixed value: deterministic.
  • component object parameters:
Parameter Name Type Required Example Description
type String Yes - Component type, can be header, body, button, carousel.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 button; 4）When type=carousel, set the carousel template card component information.
sub_type String No - Button type created, required only when type=button, can be URL, QUICK_REPLY. No value for other types.
index String No - Button position index, required only when type=button, value range is 0-2.
parameters array[parameter JsonObject] No - Component parameter list.
cards array[card JsonObject] No - required only when type=carousel.
  • card object参数：
Parameter Name Type Required Example Description
card_index int YES - Carousel card serial number
components array[component JsonObject] YES - Slideshow component, and the component type value is header，body，button.
  • parameter object parameters:
Parameter Name Type Required Example Description
type String Yes - Among:1) When component object's type=header, can be text, image, video, document;2) When component object's type=body, value is text;3) When component object's type=button and sub_type=URL, value is text;4) When component object's type=button and sub_type=QUICK_REPLY, value is payload. No value for other types.
text String No - Required only when type=text, set the text content of the corresponding parameter. No value for other types.
payload String No - Required only when type=payload, set the payload content of the corresponding parameter. Payload object definition refers to the video message. No value for other types.
image JsonObject No - Required only when type=image, set the image content of the corresponding parameter. Image object definition refers to the image message. No value for other types.
video JsonObject No - Required only when type=video, set the video content of the corresponding parameter. Video object definition refers to the video message. No value for other types.
document JsonObject No - Required only when type=document, set the document content of the corresponding parameter. Document object definition refers to the document message. No value for other types.

Request Example

Text Message Request Example

Body (application/json) parameters:

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

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

Image Message Request Example

Body (application/json) parameters:

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

Video Message Request Example

Body (application/json) parameters:

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

Audio Message Request Example

Body (application/json) parameters:

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

Document Message Request Example

Body (application/json) parameters:

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

Location Message Request Example

Body (application/json) parameters:

{
    "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": "Kexing Science Park"
    }
}

Template Message Request Example

  • Template Message (Parameterized Template)

Body (application/json) parameters:

{
    "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 (OTP Verification Code)

Body (application/json) parameters:

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

Carousel template message request example

body（application/json） parameters：

{
    "appkey": "8exxxyos",
    "business_phone": "852xxxx3867",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "template",
    "template": {
        "name": "carousel_template_media_cards_v1",
        "language": {
            "code": "en_US",
            "policy": "deterministic"
        },
        "components": [
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "AAAA"
                    },
                    {
                        "type": "text",
                        "text": "BBB"
                    },
                    {
                        "type": "text",
                        "text": "CCC"
                    }
                ]
            },
            {
                "type": "carousel",
                "cards": [
                    {
                        "components": [
                            {
                                "type": "header",
                                "parameters": [
                                    {
                                        "type": "image",
                                        "image": {
                                            "id": "653936870328698"
                                        }
                                    }
                                ]
                            },
                            {
                                "type": "button",
                                "index": 0,
                                "parameters": [
                                    {
                                        "type": "payload",
                                        "payload": "more-aloes"
                                    }
                                ],
                                "sub_type": "quick_reply"
                            },
                            {
                                "type": "button",
                                "index": 1,
                                "parameters": [
                                    {
                                        "type": "text",
                                        "text": "blue-elf"
                                    }
                                ],
                                "sub_type": "url"
                            }
                        ],
                        "card_index": 0
                    },
                    {
                        "components": [
                            {
                                "type": "header",
                                "parameters": [
                                    {
                                        "type": "image",
                                        "image": {
                                            "id": "1118343899978698"
                                        }
                                    }
                                ]
                            },
                            {
                                "type": "button",
                                "index": 0,
                                "parameters": [
                                    {
                                        "type": "payload",
                                        "payload": "more-crassulas"
                                    }
                                ],
                                "sub_type": "quick_reply"
                            },
                            {
                                "type": "button",
                                "index": 1,
                                "parameters": [
                                    {
                                        "type": "text",
                                        "text": "buddhas-temple"
                                    }
                                ],
                                "sub_type": "url"
                            }
                        ],
                        "card_index": 1
                    },
                    {
                        "components": [
                            {
                                "type": "header",
                                "parameters": [
                                    {
                                        "type": "image",
                                        "image": {
                                            "id": "608602548800223"
                                        }
                                    }
                                ]
                            },
                            {
                                "type": "button",
                                "index": 0,
                                "parameters": [
                                    {
                                        "type": "payload",
                                        "payload": "more-echeverias"
                                    }
                                ],
                                "sub_type": "quick_reply"
                            },
                            {
                                "type": "button",
                                "index": 1,
                                "parameters": [
                                    {
                                        "type": "text",
                                        "text": "black-prince"
                                    }
                                ],
                                "sub_type": "url"
                            }
                        ],
                        "card_index": 2
                    }
                ]
            }
        ]
    }
}

Response Parameters

Parameter Name Type Description
code Integer Result code
data JsonObject Request result
message String Request result description

Successful Response

  • data object parameters:
Parameter Name Type Description
messaging_product String Type of communication channel
messages array[message JsonObject] Sequence of messages
  • 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 Example

Successful Example

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

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

Response Code Explanation

code message Solution
0 Request successful
-1 Request failed NxCloud failure, please contact technical support to troubleshoot the issue
1000~100X Authentication issue NxCloud failure, refer to the API authentication section for details
9000 Parameter exception NxCloud failure, missing parameters, please check the required parameters
9001 System business error NxCloud failure, please contact technical support to troubleshoot the issue
9002 Merchant phone number error NxCloud failure, please confirm if the merchant number belongs to a WhatsApp number
9003 Application does not exist/unavailable NxCloud failure, please contact business personnel to handle the creation/disabling of the cloud platform application
9004 No corresponding country pricing for the application NxCloud failure, please contact business personnel to handle the application pricing issue
10003 WhatsApp business phone is not bind app The WhatsApp number is not linked to the application. Please contact the business representative to handle the application and phone number binding.
10005 WhatsApp Template does not exist or low quality The template does not exist or has been suspended.

Template Languages

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         Vietnamese vi