SAAS WhatsApp API createTemplate - nxtele/nxcloud-doc-en GitHub Wiki

Get Template Message List

Retrieve the list of template messages via API.

  • URL: https://api.nxcloud.com/saas/wa/template/{phone}?page_number={page_number}&page_size={page_size}&name={name}&tenant_id={tenant_id}
  • Method: GET
  • Content-Type: application/json
  • Requires Authentication: Yes

Request Parameters

Header Parameters:

Parameter Name Type Required Example Description
accessKey String Yes fme2na3kdi3ki User identity identifier
ts String Yes 1655710885431 Current request timestamp (in milliseconds), with a max error of 60 seconds between the client and server.
bizType String Yes 2 WhatsApp business type, use fixed value “2”
action String Yes mt WhatsApp business operation, use fixed value “mt”
sign String Yes 6e9506557d1f289501d333ee2c365826 Signature for API request parameters, as per common agreement

URL Parameters:

Parameter Name Type Required Example Description
phone String Yes 86158xxxx1795 WhatsApp number of the message sender, must include the country code. E.g., 86158xxxx1795
tenant_id Long Yes 1 Tenant ID
page_number Integer Yes 1 Page number
page_size Integer Yes 10 Number of items per page
name String No Template Name Name of the template

Response Parameters

Parameter Name Type Description
data data JsonObject The result of the request
message string Explanation of the request result
code integer Result code

Data Object

Parameter Name Type Description
id Long Template ID
channel Integer Channel type. 2: WhatsApp
name String Template name
content String Template content
created_at String Template creation time
updated_at String Template modification time
status Integer Template status
language String Template language code
language_name String Template language name
unsubscribe String Template unsubscribe option
quality String Template quality
category String Template type name (MARKETING, UTILITY)
category_type String Template type. 1: MARKETING, 2: UTILITY
waRejectedReason String Reason for WhatsApp template rejection
is_close_auto_flow Integer Whether to close unassigned sessions (0: No, 1: Yes)

Response Example

{
    "code": 0,
    "message": "",
    "data": {
        "list": [
            {
                "id": 314,
                "channel": 2,
                "name": "buttontest22",
                "content": "Hello, I am the new virtual assistant. I can help you discover products or provide support. Please reach out if I can help!",
                "created_at": "2024-06-25 14:31:26",
                "updated_at": "2024-06-25 15:27:39",
                "status": 2,
                "language": "en_GB",
                "language_name": "English (UK)",
                "unsubscribe": "",
                "additional": null,
                "quality": "UNKNOWN",
                "category": "MARKETING",
                "category_type": 1,
                "waRejectedReason": "",
                "is_close_auto_flow": 0
            }   
        ],
        "total": 1,
        "has_next_page": false
    },
    "traceId": "16f9ca88e70844a8a088f9a4a3806e5e"
}

Create Template Message

Create a template via API.

  • URL: https://api.nxcloud.com/saas/wa/template/{phone}
  • Method: POST
  • Content-Type: application/json
  • Authentication required: Yes

Request Parameters

Header Parameters:

Parameter Name Type Required Example Value Description
accessKey String Yes fme2na3kdi3ki User identity identifier
ts String Yes 1655710885431 Current request timestamp (in milliseconds), the server allows a time discrepancy of up to 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 Signature of API input parameters, commonly agreed upon format

URL Parameter:

Parameter Name Type Required Example Value Description
phone String Yes 86158xxxx1795 WhatsApp number of the message sender, must include country code, e.g., 86158xxxx1795

Body Parameters:

Parameter Name Type Required Example Value Description
tenant_id Long Yes 1 Tenant ID
name String Yes test_1 Template name (cannot be in Chinese)
language String Yes af Template language, e.g., "af"
category_type Integer Yes 1 Template type: 1 for MARKETING, 2 for UTILITY
content String Yes Template content Template content
headerText String No Template header text Optional header text for the template
mediaName String No Name of media file in the header (Refer to uploaded media, used for multimedia in the template, return parameter original_filename)
mediaId String No Media ID in the header (Refer to uploaded media, return parameter media_id)
mediaType String No IMAGE, DOCUMENT, VIDEO Type of media in the header
templateMediaId String No Template media ID (Refer to uploaded media, return parameter h)
footerText String No Template footer text Optional footer text for the template
tag_name String No Existing tag name The message will be tagged with this tag, must already exist
syn_meta Boolean No true Sync with the Meta interface, defaults to true: true (sync), false (do not sync)
is_close_auto_flow Integer No 0 Whether to close unassigned sessions: 0 for no, 1 for yes
buttonComponents Array[buttonComponent Object] No Template buttons Array of buttons in the template
  • buttonComponent Object Parameters:
Parameter Name Type Required Example Value Description
type String Yes - Button type: QUICK_REPLY (quick reply), URL (call-to-action URL), PHONE_NUMBER (call-to-action phone number), FLOW (form button)
customizeType String No - Custom button type, required if button type is QUICK_REPLY, options: conventional (standard), unsubscribe (unsubscribe)
text String Yes - Button text
phoneNumber String Yes - Phone number, required for PHONE_NUMBER button type
url String Yes - URL, required for URL button type. If it's a dynamic URL, add suffix variable 1, like {{1}}
flow_id String No - Flow ID, required for FLOW button type
buttonEvents Array[buttonEvent Object] No - Events related to the button
  • buttonEvent Object Parameters:
Parameter Name Type Required Example Value Description
event String Yes - Event type: tag (tag), text (text), template (template)
tagName String No - Tag name, required if event type is tag
text String No - Text content, required if event type is text
templateId String No - Template ID, required if event type is template
templateName String No - Template name, required if event type is template

Sample Request 1

{
    "name": "test_23",
    "tenant_id": 123,
    "language": "af",
    "category_type": 1,
    "content": "send message content: WhatsApp:{{WhatsApp}}, end message",
    "headerText": "",
    "footerText": "foot",
    "mediaName": "1705406614735.jpg",
    "templateMediaId": "4:MTcwNTQwNjYxNDczNS5qcGc=:...",
    "mediaId": "1167113681293447",
    "mediaType": "IMAGE",
    "tag_name": "tag1",
    "is_close_auto_flow": 0,
    "buttonComponents": [
        {
            "customizeType": "conventional",
            "text": "button1",
            "type": "QUICK_REPLY",
            "buttonEvents": [
                {
                    "event": "tag",
                    "tagName": "Viber tag"
                },
                {
                    "event": "template",
                    "templateId": 314,
                    "templateName": "buttontest22"
                }
            ]
        },
        {
            "customizeType": "conventional",
            "text": "button 2",
            "type": "QUICK_REPLY",
            "buttonEvents": [
                {
                    "event": "tag",
                    "tagName": "Viber tag"
                },
                {
                    "event": "text",
                    "text": "test text"
                }
            ]
        },
        {
            "customizeType": "conventional",
            "text": "button3",
            "type": "QUICK_REPLY",
            "buttonEvents": [
                {
                    "event": "template",
                    "templateId": 313,
                    "templateName": "test_8"
                }
            ]
        }
    ]
}

Sample Request 2

{
    "name": "test_45",
    "language": "af",
    "tenant_id": 1,
    "category_type": 1,
    "content": "template content https://...",
    "headerText": "test head",
    "footerText": "foot",
    "tag_name": "tag1",
    "is_close_auto_flow": 0,
    "buttonComponents": [
        {
            "text": "phone",
            "type": "PHONE_NUMBER",
            "phoneNumber": "8613128xxxx"
        },
        {
            "text": "web1",
            "type": "URL",
            "url": "https://testnxlink.nxcloud.com/"
        },
        {
            "text": "web2",
            "type": "URL",
            "url": "https://www.baidu.com/"
        }
    ]
}

Sample Request 3

{
    "name": "test_99",
    "language": "sq",
    "tenant_id": 1,
    "category_type": 1,
    "content": "template content",
    "headerText": "header content",
    "footerText": "foot content",
    "tag_name": "tag1",
    "is_close_auto_flow": 0,
    "buttonComponents": [
        {
            "type": "flow",
            "text": "button",
            "flow_id": "803348158336427"
        }
    ]
}

Update Template

Update a template via API

  • URL: https://api.nxcloud.com/saas/wa/template/{phone}
  • Method: PUT
  • Content-Type: application/json
  • Requires Authentication: Yes

Request Parameters

Header Parameters:

Parameter Name Type Required Example Value Description
accessKey String Yes fme2na3kdi3ki User identity token
ts String Yes 1655710885431 Current request timestamp (in milliseconds). The server allows a maximum client time discrepancy of 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 Signature of API request parameters, as per agreement

Path Parameter:

Parameter Name Type Required Example Value Description
phone String Yes 86158xxxx1795 WhatsApp sender number, including country code. For example: 86158xxxx1795

Body Parameters:

Parameter Name Type Required Example Value Description
tenant_id Long Yes 1 Tenant ID
id Long Yes 1 Template ID
name String Yes test_1 Template name (cannot be in Chinese)
language String Yes af Template language
category_type Integer Yes 1 Template type: 1 for MARKETING, 2 for UTILITY
content String Yes Template content Template content
headerText String No Header text Template header text
mediaName String No Media name Name of the media in the template header (reference: uploaded media response original_filename)
mediaId String No Media ID ID of the media in the template header (reference: uploaded media response media_id)
mediaType String No IMAGE, DOCUMENT, VIDEO Type of media in the template header
templateMediaId String No Media template ID Template ID of the media in the header (reference: uploaded media response)
footerText String No Footer text Template footer text
tag_name String No Existing tag Must be an existing tag, used for tagging template messages
syn_meta Boolean No true Synchronize with the meta API. Default is true: true for sync, false for no sync
is_close_auto_flow Integer No 0 Whether to close unassigned sessions: 0 for no, 1 for yes
buttonComponents Array[Object] No - Array of template buttons

buttonComponent Object Parameters:

Parameter Name Type Required Example Value Description
type String Yes QUICK_REPLY Button type: QUICK_REPLY, URL (Call-to-action URL button), PHONE_NUMBER (Call-to-action phone number button), FLOW (Form button)
customizeType String No conventional Custom button type (required when the type is QUICK_REPLY): conventional, unsubscribe (for unsubscribe)
text String Yes Button text Button name
phoneNumber String Yes - Phone number for the call-to-action button (required if type is PHONE_NUMBER)
url String Yes - URL for the call-to-action button (required if type is URL). If it's a dynamic URL, use {{1}} as a variable.
flow_id String No - Flow ID (required when type is FLOW)
buttonEvents Array[Object] No - Array of button-related events

buttonEvent Object Parameters:

Parameter Name Type Required Example Value Description
event String Yes - Event type: tag (tagging), text (text message), template (template event)
tagName String No - Tag name (required when event type is tag)
text String No - Text content (required when event type is text)
templateId String No - Template ID (required when event type is template)
templateName String No - Template name (required when event type is template)

Example Request Body:

{
    "id": 317,
    "name": "test_99",
    "language": "sq",
    "tenant_id": 1,
    "category_type": 1,
    "content": "template content",
    "headerText": "header content",
    "footerText": "footer content",
    "mediaName": "",
    "templateMediaId": "",
    "mediaId": "",
    "mediaType": "",
    "tag_name": "tag1",
    "is_close_auto_flow": 0,
    "buttonComponents": [
        {
            "type": "flow",
            "text": "button",
            "flow_id": "803348158336427"
        }
    ]
}

Get Template Details

Retrieve template details via API

  • URL: https://api.nxcloud.com/saas/wa/template/{phone}/{id}?tenant_id={tenant_id}
  • Method: GET
  • Content-Type: application/json
  • Authentication Required: Yes

Request Parameters

Header Parameters:

Parameter Type Required Example Value Description
accessKey String Yes fme2na3kdi3ki User identity identifier
ts String Yes 1655710885431 Current request timestamp (in milliseconds). The server allows a maximum time deviation of 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 Signature of the API input parameters, following a public agreement

URL Parameters:

Parameter Type Required Example Value Description
phone String Yes 86158xxxx1795 The WhatsApp phone number of the message sender, with country code (e.g., 86158xxxx1795).
tenant_id Long Yes 1 Tenant ID
id Long Yes 1 Template ID

Response Parameters

Parameter Type Description
data data JsonObject Result of the request
message string Request result description
code integer Result code

Data Object:

Parameter Type Description
id Long Template ID
channel integer Channel type (2: WhatsApp)
name String Template name
status String Template status (REJECTED, PENDING, APPROVED, IN_APPEAL, etc.)
language String Template language code (e.g., af)
quality_score JsonObject Template quality
category String Template type name (MARKETING, UTILITY)
category_type String Template type (1: MARKETING, 2: UTILITY)
is_close_auto_flow integer Whether to close unassigned sessions (0: No, 1: Yes)
components JsonObject Array of component objects

Component Object:

Parameter Type Example Value Description
type String - Template content (HEADER, BODY, FOOTER, BUTTONS)
format String - Format (text, IMAGE, DOCUMENT, VIDEO)
text String - Header text content
media_id String - Media ID
h String - Template media ID
example JsonObject - Example
filename String - Media file name
buttons array[button JsonObject] - When type is BUTTONS

Example Object:

Parameter Type Example Value Description
header_handle String - Message header variable (media link)
file_name String - Message header variable (media file name)
body_text array[String] - Message body variable values

Button Object:

Parameter Type Example Value Description
type String - Button type (QUICK_REPLY, URL, PHONE_NUMBER, FLOW)
text String - Button name
buttonReqs Object -

ButtonReqs Object:

Parameter Type Example Value Description
type String - Button type (QUICK_REPLY, URL, PHONE_NUMBER, FLOW)
text String - Button name
customizeType Object - Custom button type (if button type is QUICK_REPLY, values can be conventional or unsubscribe)
payload String - Button ID
flow_id String - Flow ID
navigate_screen String - Start screen in the process
flow_action String - Flow action (navigate, data_exchange; default: navigate)
buttonEvents array[buttonEvent Object] - Button-related events

ButtonEvent Object:

Parameter Type Example Value Description
event String - Event type (tag, text, template)
tagName String - Tag name
tagId Object - Tag ID
templateId String - Template ID
templateName String - Template name
buttonEvents array[buttonEvent Object] - Button-related events

Sample Response 1

{
    "code": 0,
    "message": "",
    "data": {
        "namespace": null,
        "name": "test_23",
        "category": "MARKETING",
        "category_type": 1,
        "components": [
            {
                "type": "HEADER",
                "format": "IMAGE",
                "text": null,
                "buttons": null,
                "parameters": null,
                "sub_type": null,
                "index": null,
                "example": {
                    "header_handle": "https://goss.oss-accelerate.aliyuncs.com/1167113681293447?Expires=1719311172&OSSAccessKeyId=LTAI5tBrjWM5EyDe6MA5uc7z&Signature=BqE8WVjP%2B%2B19G4I4bLuL7ISGyo8%3D",
                    "file_name": "1705406614735.jpg"
                },
                "filename": "1705406614735.jpg",
                "url": null,
                "media_id": "1167113681293447",
                "h": "4:YjZjODg1NGEtMDA4ZC00ZjcwLTkzYjAtZTVjZTdiNGZmNmJmMTcwNTQwNjYxNDczNS5qcGc=:aW1hZ2UvcG5n:ARbSZFssPqLjHjFifodFDQL_79OaBg9JDrz67b_wlP2wrobpzHRv6fqHfHg-YlZVOM4X4bGeYnIv7uXpsVcYvQULdQ1cFqPgVFIl0pkID7Ao6Q:e:1719656714:1407008009801826:100084713375965:ARYtgY7tK8u5Jn3qzt0",
                "media_type": null
            },
            {
                "type": "BODY",
                "format": null,
                "text": "send content：WhatsApp:{{WhatsApp}}，end message",
                "buttons": null,
                "parameters": null,
                "sub_type": null,
                "index": null,
                "example": {
                    "body_text": [
                        [
                            "8613800000000"
                        ]
                    ]
                },
                "filename": null,
                "url": null,
                "media_id": null,
                "h": null,
                "media_type": null
            },
            {
                "type": "FOOTER",
                "format": null,
                "text": "foot content",
                "buttons": null,
                "parameters": null,
                "sub_type": null,
                "index": null,
                "example": null,
                "filename": null,
                "url": null,
                "media_id": null,
                "h": null,
                "media_type": null
            },
            {
                "type": "BUTTONS",
                "format": null,
                "text": null,
                "buttons": [
                    {
                        "type": "QUICK_REPLY",
                        "text": "button1",
                        "payload": null,
                        "url": null,
                        "phone_number": null,
                        "flow_id": null,
                        "navigate_screen": null,
                        "flow_action": null,
                        "buttonReqs": {
                            "type": "QUICK_REPLY",
                            "customizeType": "conventional",
                            "text": "button1",
                            "phoneNumber": null,
                            "url": null,
                            "payload": "305",
                            "buttonEvents": [
                                {
                                    "event": "tag",
                                    "tagName": "Viber tag",
                                    "tagId": 33991,
                                    "templateName": null,
                                    "templateId": null,
                                    "text": null
                                },
                                {
                                    "event": "template",
                                    "tagName": null,
                                    "tagId": null,
                                    "templateName": "buttontest22",
                                    "templateId": 314,
                                    "text": null
                                }
                            ],
                            "flow_id": null,
                            "navigate_screen": null,
                            "flow_action": null
                        }
                    },
                    {
                        "type": "QUICK_REPLY",
                        "text": "tag2",
                        "payload": null,
                        "url": null,
                        "phone_number": null,
                        "flow_id": null,
                        "navigate_screen": null,
                        "flow_action": null,
                        "buttonReqs": {
                            "type": "QUICK_REPLY",
                            "customizeType": "conventional",
                            "text": "tag2",
                            "phoneNumber": null,
                            "url": null,
                            "payload": "306",
                            "buttonEvents": [
                                {
                                    "event": "tag",
                                    "tagName": "Viber tag",
                                    "tagId": 33991,
                                    "templateName": null,
                                    "templateId": null,
                                    "text": null
                                },
                                {
                                    "event": "text",
                                    "tagName": null,
                                    "tagId": null,
                                    "templateName": null,
                                    "templateId": null,
                                    "text": "test text"
                                }
                            ],
                            "flow_id": null,
                            "navigate_screen": null,
                            "flow_action": null
                        }
                    },
                    {
                        "type": "QUICK_REPLY",
                        "text": "button3",
                        "payload": null,
                        "url": null,
                        "phone_number": null,
                        "flow_id": null,
                        "navigate_screen": null,
                        "flow_action": null,
                        "buttonReqs": {
                            "type": "QUICK_REPLY",
                            "customizeType": "conventional",
                            "text": "button3",
                            "phoneNumber": null,
                            "url": null,
                            "payload": "307",
                            "buttonEvents": [
                                {
                                    "event": "template",
                                    "tagName": null,
                                    "tagId": null,
                                    "templateName": "test_8",
                                    "templateId": 313,
                                    "text": null
                                }
                            ],
                            "flow_id": null,
                            "navigate_screen": null,
                            "flow_action": null
                        }
                    }
                ],
                "parameters": null,
                "sub_type": null,
                "index": null,
                "example": null,
                "filename": null,
                "url": null,
                "media_id": null,
                "h": null,
                "media_type": null
            }
        ],
        "language": "af",
        "status": "APPROVED",
        "id": 1214365320013059,
        "quality_score": {
            "score": "UNKNOWN"
        },
        "tag_ids": [
            33991
        ],
        "is_close_auto_flow": 0
    },
    "traceId": "6dcc841ca255443c9ea0434e5ed0b7b2"
}

Sample Response 2

{
    "code": 0,
    "message": "",
    "data": {
        "namespace": null,
        "name": "test_45",
        "category": "MARKETING",
        "category_type": 1,
        "components": [
            {
                "type": "HEADER",
                "format": "TEXT",
                "text": "test text",
                "buttons": null,
                "parameters": null,
                "sub_type": null,
                "index": null,
                "example": null,
                "filename": null,
                "url": null,
                "media_id": null,
                "h": null,
                "media_type": null
            },
            {
                "type": "BODY",
                "format": null,
                "text": "template https://119.91.210.214:10001/api/shortLink/doAccess/Y3Mjmq  content",
                "buttons": null,
                "parameters": null,
                "sub_type": null,
                "index": null,
                "example": null,
                "filename": null,
                "url": null,
                "media_id": null,
                "h": null,
                "media_type": null
            },
            {
                "type": "FOOTER",
                "format": null,
                "text": "foot",
                "buttons": null,
                "parameters": null,
                "sub_type": null,
                "index": null,
                "example": null,
                "filename": null,
                "url": null,
                "media_id": null,
                "h": null,
                "media_type": null
            },
            {
                "type": "BUTTONS",
                "format": null,
                "text": null,
                "buttons": [
                    {
                        "type": "PHONE_NUMBER",
                        "text": "phone",
                        "payload": null,
                        "url": null,
                        "phone_number": "+861312895xxx",
                        "flow_id": null,
                        "navigate_screen": null,
                        "flow_action": null,
                        "buttonReqs": null
                    },
                    {
                        "type": "URL",
                        "text": "web1",
                        "payload": null,
                        "url": "https://testnxlink.nxcloud.com/",
                        "phone_number": null,
                        "flow_id": null,
                        "navigate_screen": null,
                        "flow_action": null,
                        "buttonReqs": null
                    },
                    {
                        "type": "URL",
                        "text": "web2",
                        "payload": null,
                        "url": "https://www.baidu.com/",
                        "phone_number": null,
                        "flow_id": null,
                        "navigate_screen": null,
                        "flow_action": null,
                        "buttonReqs": null
                    }
                ],
                "parameters": null,
                "sub_type": null,
                "index": null,
                "example": null,
                "filename": null,
                "url": null,
                "media_id": null,
                "h": null,
                "media_type": null
            }
        ],
        "language": "af",
        "status": "APPROVED",
        "id": 1500809463846053,
        "quality_score": {
            "score": "UNKNOWN"
        },
        "tag_ids": [],
        "is_close_auto_flow": 0
    },
    "traceId": "f42d64bb6b5f4e0fa12baf826b2ff787"
}

Sample Response 3

{
    "code": 0,
    "message": "",
    "data": {
        "namespace": null,
        "name": "test_99",
        "category": "MARKETING",
        "category_type": 1,
        "components": [
            {
                "type": "HEADER",
                "format": "TEXT",
                "text": "header text",
                "buttons": null,
                "parameters": null,
                "sub_type": null,
                "index": null,
                "example": null,
                "filename": null,
                "url": null,
                "media_id": null,
                "h": null,
                "media_type": null
            },
            {
                "type": "BODY",
                "format": null,
                "text": "template text",
                "buttons": null,
                "parameters": null,
                "sub_type": null,
                "index": null,
                "example": null,
                "filename": null,
                "url": null,
                "media_id": null,
                "h": null,
                "media_type": null
            },
            {
                "type": "FOOTER",
                "format": null,
                "text": "foot",
                "buttons": null,
                "parameters": null,
                "sub_type": null,
                "index": null,
                "example": null,
                "filename": null,
                "url": null,
                "media_id": null,
                "h": null,
                "media_type": null
            },
            {
                "type": "BUTTONS",
                "format": null,
                "text": null,
                "buttons": [
                    {
                        "type": "FLOW",
                        "text": "button",
                        "payload": null,
                        "url": null,
                        "phone_number": null,
                        "flow_id": "803348158336427",
                        "navigate_screen": "SIGN_IN",
                        "flow_action": "NAVIGATE",
                        "buttonReqs": null
                    }
                ],
                "parameters": null,
                "sub_type": null,
                "index": null,
                "example": null,
                "filename": null,
                "url": null,
                "media_id": null,
                "h": null,
                "media_type": null
            }
        ],
        "language": "sq",
        "status": "APPROVED",
        "id": 432230866355873,
        "quality_score": {
            "score": "UNKNOWN"
        },
        "tag_ids": [
            33989
        ],
        "is_close_auto_flow": 0
    },
    "traceId": "67a05b8528114fa29edeb6616458b12a"
}

Delete Template

Delete a template through the API

  • URL: https://api.nxcloud.com/saas/wa/template/{phone}/{id}?tenant_id=123
  • Method: DELETE
  • Content-Type: application/json
  • Requires Authentication: Yes

Request Parameters

Header Parameters:

Parameter Name Type Required Example Value Description
accessKey String Yes fme2na3kdi3ki User identity key
ts String Yes 1655710885431 Current request timestamp (in milliseconds), with a max time discrepancy of 60 seconds allowed by the NxCloud server
bizType String Yes 2 WhatsApp business type, with a fixed value of "2"
action String Yes mt WhatsApp business action, with a fixed value of "mt"
sign String Yes 6e9506557d1f289501d333ee2c365826 Signature for the API input parameters, based on public agreement

Parameter Parameters:

Parameter Name Type Required Example Value Description
phone String Yes 86158xxxx1795 WhatsApp number of the message sender, including country code, e.g., 86158xxxx1795
tenant_id Long Yes 1 Tenant ID
id Long Yes 1 Template ID

Get WhatsApp Form API

Retrieve WhatsApp form through the API

  • URL: https://api.nxcloud.com/saas/wa/flow/{phone}?tenant_id=123
  • Method: GET
  • Content-Type: application/json
  • Requires Authentication: Yes

Request Parameters

Header Parameters:

Parameter Name Type Required Example Value Description
accessKey String Yes fme2na3kdi3ki User identity key
ts String Yes 1655710885431 Current request timestamp (in milliseconds), with a max time discrepancy of 60 seconds allowed by the NxCloud server
bizType String Yes 2 WhatsApp business type, with a fixed value of "2"
action String Yes mt WhatsApp business action, with a fixed value of "mt"
sign String Yes 6e9506557d1f289501d333ee2c365826 Signature for the API input parameters, based on public agreement

Parameter Parameters:

Parameter Name Type Required Example Value Description
phone String Yes 86158xxxx1795 WhatsApp number of the message sender, including country code, e.g., 86158xxxx1795
tenant_id Long Yes 1 Tenant ID

Response Parameters

Parameter Name Type Description
data array[data JsonObject] Response result
message string Response message
code integer Result code

Data

Parameter Name Type Description
name String Form name
status String Form status: PUBLISHED (Published), DRAFT (Draft)
id String Form ID
categories array[String JsonObject] SIGN_UP, APPOINTMENT_BOOKING categories

Sample Response 3

{
    "code": 0,
    "message": "",
    "data": {
        "data": [
            {
                "name": "hqq_flow_endpoint_001",
                "status": "PUBLISHED",
                "categories": [
                    "SIGN_UP"
                ],
                "validation_errors": [],
                "id": "803348158336427"
            }
        ]
    },
    "traceId": "e0fcc69fde9547dd919d1ecbeb10787c"
}

Upload Media (Used for Uploading Media for Template Examples and Files to Meta) API

This API is used when creating or updating a template. If the template header type is rich media, this endpoint is used to upload files and obtain media links, media IDs, and template media IDs.

  • URL: https://api.nxcloud.com/saas/wa/media/{phone}
  • Method: POST
  • Content-Type: multipart/form-data
  • Requires Authentication: Yes

Request Parameters

Header Parameters:

Parameter Name Type Required Example Description
accessKey String Yes fme2na3kdi3ki User identity token
ts String Yes 1655710885431 Current request timestamp (in milliseconds). The server allows a maximum time deviation of 60 seconds.
bizType String Yes 2 WhatsApp business type, fixed value “2”
action String Yes mt WhatsApp business action, fixed value “mt”
sign String Yes 6e9506557d1f289501d333ee2c365826 Signature for the API request parameters, agreed upon by both parties

URL Parameters:

Parameter Name Type Required Example Description
phone String Yes 86158xxxx1795 WhatsApp phone number of the sender, including country code, e.g., 86158xxxx1795

Body Parameters:

Parameter Name Type Required Example Description
tenant_id Long Yes 1 Tenant ID
file MultipartFile Yes File stream

Response Parameters

Parameter Name Type Description
data data JsonObject Request results
message string Description of the request result
code integer Result code

Data Object:

Parameter Name Type Description
h String Template media ID
media_id String Media ID
original_filename String Original file name
mime_type String Media MIME type
url String Media URL

Response Example

Success Example

{
    "code": 0,
    "message": "",
    "data": {
        "h": "4:MTcwNTQwNTM3MTU4MS5qcGc=:aW1hZ2UvcG5n:ARZjTwWzWltYZ7anpdBq9AzRGbkrRnsxni3wUee8aRJhAKLjVV-rpxVMRhiKmssfVzzM4JsxjMNXLKKqfIQeWjk00Ve6hSnfkdxCDE4dfDuIVA:e:1719660668:1407008009801826:100084713375965:ARb9JldW1tEddKyFjg8\n4:MTcwNTQwNTM3MTU4MS5qcGc=:aW1hZ2UvcG5n:ARZEMW29V1o0vRUFe3z3IwtjUC9Ezcl_9ZzarcfekJHOhrSXCQQ90pgHd1suyeLdaMfV244p8c4rBZQ4T47RRq-OSManVUY9IJ6ghTstyg5Bhw:e:1719660668:1407008009801826:100084713375965:ARa48raWz1W1us7SJ8w\n4:MTcwNTQwNTM3MTU4MS5qcGc=:aW1hZ2UvcG5n:ARbEitR5qMUNvmTijnx627fPihUeT6i-mj2zrFI6ZYJBB8WnZCWeNQcAhzC-0u8RZISIbAV3yIyViQ67Bv_63OUxwdXz9xljkQaPs0utUQNT9A:e:1719660668:1407008009801826:100084713375965:ARakUEk8Sab0_H82e4E\n4:MTcwNTQwNTM3MTU4MS5qcGc=:aW1hZ2UvcG5n:ARarzhJe1V3XXnJpy2hW305vLuE8pzKNKynNFp16GxymY96ngrpbWKMd2QHIg7Xfjlcv_DzhSKP7d-YKzGqPeTJul3S5efcJYUJgIxm1ELg6Cw:e:1719660669:1407008009801826:100084713375965:ARZOtE2DJ-x_Q321sTk",
        "media_id": "1187184585633620",
        "original_filename": "1705405371581.jpg",
        "mime_type": "image/png",
        "url": "https://goss.oss-accelerate.aliyuncs.com/1187184585633620?Expires=1719315130&OSSAccessKeyId=LTAI5tBrjWM5EyDe6MA5uc7z&Signature=8NorCSFNymSYnBq56xKC6L2yaW0%3D"
    },
    "traceId": "e45e7e38faca4b39a9ec8905cc639116"
}

Response Code Description

Code Message Solution
0 Request successful
-1 Request failed Please contact technical support to resolve the issue
1000~100X Authentication issue Refer to the API authentication section for details
21058 Parameter error tenant_id is required
21060 Parameter error business_phone is required
22041 Business error Failed to send from cloud platform
22042 Business error Failed to send WhatsApp message
22049 Business error Merchant with business_phone={0} does not exist
22070 Business error Maximum of 3 buttons can be created
22089 Business error The phone number is unavailable (No Core App)
22090 Business error Invalid phone number
22092 Business error Language pack not found: {0}
22216 Business error Button name cannot be empty

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