Send Batch SMS - SendBatchUSMSMessage

Supports sending different content SMS to multiple different phone numbers in a single request. A maximum of 200 numbers are supported in a single batch request. For more details on the API, see USMS API Overview.

Request Parameters

Parameter name	Type	Description	Required	Remark
Action	String	Corresponding API name, SendBatchUSMSMessage	Yes	Public parameter
PublicKey	String	Corresponding API public key	Yes	Public parameter
Signature	String	User signature generated based on API public and private keys, see Signature Algorithm	Yes	Public parameter
ProjectId	string	Project ID, default project if main and financial account is empty; it is required for sub-accounts, see Get Project ID	Yes	Public parameter
TaskContent	string	Batch sending parameters, json array encoded in base64. Examples before and after encoding can be referenced below: TaskContent example before Base64 encoding、 TaskContent example after Base64 encoding	Yes

TaskContent (Before Base64 Encoding)

Parameter name	Type	Description	Case	Required
TemplateId	string	SMS template ID	UTB20092XXXXD02	Yes
SigContent	string	SMS signature	UCloud Global	Yes
Target	Array	List of number and SMS content combination		Yes

Target (Before Base64 Encoding)

Parameter name	Type	Description	Case	Required
TemplateParams	Array	Variables in the SMS template (array format)	[“UCloud Global”,“13455”]	Yes
Phone	string	Phone number, format is (60)1xxxxxxxx, where () is the international long-distance area code (e.g., 86 or 0086 for China, both formats supported), followed by the phone number. If the international area code is not provided, e.g., 185XXXX0507, it defaults to a domestic mobile number.	185XXXX0507	Yes
UserId	string	Custom business ID, string (cannot exceed 32 characters), does not support single quotes, emoji, or other special characters	xxx-uhost-001	No
ExtendCode	string	SMS extension code, which is a string of Arabic numerals. It is not activated by default; contact UCloud Global technical support for activation if needed.	123	No

TaskContent Example (Before Base64 Encoding)


[
    {
        "TemplateId":"UTA20212831C85C",
        "SigContent":"UCloud Global",
        "Target":[
            {
                "TemplateParams":[
                    "Top diamond user Liu Dachui",
                    "24680"
                ],
                "Phone":"185XXXX0507",
                "UserId":"you man c define the content by yrself"
            },
            {
                "TemplateParams":[
                    "Cheerful Pistachio Excavator",
                    "13579"
                ],
                "Phone":"185XXXX0608",
                "ExtendCode":"123",
                "UserId":"catch the big fish"
            }
        ]
    }
]

TaskContent Example (After Base64 Encoding)


WwogICAgewogICAgICAgICJUZW1wbGF0ZUlkIjoiVVRBMjAyMTI4MzFDODVDIiwKICAgICAgICAiU2lnQ29udGVudCI6IlVDbG91ZCIsCiAgICAgICAgIlRhcmdldCI6WwogICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAiVGVtcGxhdGVQYXJhbXMiOlsKICAgICAgICAgICAgICAgICAgICAi6aG257qn6ZK755+z55So5oi35YiY5aSn6ZSkIiwKICAgICAgICAgICAgICAgICAgICAiMjQ2ODAiCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgIlBob25lIjoiMTg1WFhYWDA1MDciLAogICAgICAgICAgICAgICAgIlVzZXJJZCI6InlvdSBtYW4gYyBkZWZpbmUgdGhlIGNvbnRlbnQgYnkgeXJzZWxmIgogICAgICAgICAgICB9LAogICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAiVGVtcGxhdGVQYXJhbXMiOlsKICAgICAgICAgICAgICAgICAgICAi5byA5b+D5p6c5oyW5Zyf5py6IiwKICAgICAgICAgICAgICAgICAgICAiMTM1NzkiCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgIlBob25lIjoiMTg1WFhYWDA2MDgiLAogICAgICAgICAgICAgICAgIkV4dGVuZENvZGUiOiIxMjMiLAogICAgICAgICAgICAgICAgIlVzZXJJZCI6ImNhdGNoIHRoZSBiaWcgZmlzaCIKICAgICAgICAgICAgfQogICAgICAgIF0KICAgIH0KXQ==

Response Elements

Parameter name	Type	Description	Required
RetCode	int	Return status code, 0 means success, non-0 indicates failure	Yes
Action	string	Operation command name	Yes
Message	string	Return error message, provides detailed information when `RetCode` is not 0	Yes
SessionNo	string	Unique ID for this submission and sending task, can be used to query the list of messages sent in this batch. Note: the field is returned only when the number of successfully submitted messages is greater than 0.	No
ReqUuid	string	Uuid of this request	No
SuccessCount	int	Number of messages successfully submitted (not split)	No
FailContent	array	Details of failed sends. The field is effective when the return code is non-0 and can be retried based on these data.	No

BatchInfo

Parameter name	Type	Description	Required
TemplateId	string	SMS template ID	Yes
SigContent	string	SMS signature	Yes
Target	array	Information combination of specific phone numbers, template variables, etc.	Yes
FailureDetails	string	Details of failures to send. Note: This field is effective when template/signature validation fails.	No

FailPhoneDetail

Parameter name	Type	Description	Required
TemplateParams	array	SMS template parameters	Yes
Phone	string	Phone number	Yes
ExtendCode	string	Extension number	No
UserId	string	User-defined ID	No
FailureDetails	string	Reason for failure to send. Note: If template/signature verification fails, this field is empty.	No

Request Example


https://https://api.ucloud-global.com/?Action=SendBatchUSMSMessage
&PublicKey=vsRhB0Qzo9elXXXXXkw8o/vmss8Tb0vxi74A=
&Signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
&ProjectId=org1234
&TaskContent=WwogICAgewogICAgICAgICJUZW1wbGF0ZUlkIjoiVVRBMjAyMTI4MzFDODVDIiwKICAgICAgICAiU2lnQ29udGVudCI6IlVDbG91ZCIsCiAgICAgICAgIlRhcmdldCI6WwogICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAiVGVtcGxhdGVQYXJhbXMiOlsKICAgICAgICAgICAgICAgICAgICAi6aG257qn6ZK755+z55So5oi35YiY5aSn6ZSkIiwKICAgICAgICAgICAgICAgICAgICAiMjQ2ODAiCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgIlBob25lIjoiMTg1WFhYWDA1MDciLAogICAgICAgICAgICAgICAgIlVzZXJJZCI6InlvdSBtYW4gYyBkZWZpbmUgdGhlIGNvbnRlbnQgYnkgeXJzZWxmIgogICAgICAgICAgICB9LAogICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAiVGVtcGxhdGVQYXJhbXMiOlsKICAgICAgICAgICAgICAgICAgICAi5byA5b+D5p6c5oyW5Zyf5py6IiwKICAgICAgICAgICAgICAgICAgICAiMTM1NzkiCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgIlBob25lIjoiMTg1WFhYWDA2MDgiLAogICAgICAgICAgICAgICAgIkV4dGVuZENvZGUiOiIxMjMiLAogICAgICAgICAgICAgICAgIlVzZXJJZCI6ImNhdGNoIHRoZSBiaWcgZmlzaCIKICAgICAgICAgICAgfQogICAgICAgIF0KICAgIH0KXQ==

Response Example


{
    "RetCode":0,
    "Action":"SendBatchUSMSMessageResponse",
    "Message":"submit success",
    "SessionNo":"abcd-dadd-dafs-dadfa-dafdsa",
    "ReqUuid":"abcd-dadd-dafs-dadfa-dafdsa",
    "SuccessCount":2,
    "FailContent":[
        {
            "TemplateId":"UTA20212831C85C",
            "SigContent":"UCloud Global",
            "Target":[
                {
                    "TemplateParams":[
                        "Cheerful Pistachio Excavator",
                        "13579"
                    ],
                    "Phone":"185XXXX0608",
                    "ExtendCode":"123",
                    "UserId":"catch the big fish"
                }
            ],
            "FailureDetails":"phone in the black list"
        }
    ]
}