SMS delivery receipt-Phone Number Verification Service(PNVS)-阿里云帮助中心

You can specify an HTTP URL to receive SMS delivery receipts. After you call the SendSmsVerifyCode API to send an SMS verification code, the platform pushes the delivery status to the receiving URL that you provide. You must receive the message and respond in the required format.

Usage notes

To get the delivery status of SMS verification codes, log on to the Phone Number Verification Service console. On the SMS Authentication Service > SMS Authentication Parameter Configuration > Status Report Reception page, enable HTTP Batch Push Mode and configure a receiving URL. This configuration is required to receive the delivery status of SMS verification codes.

Click Test to verify the push configuration. If the response is {"code": 0, "msg": "Success"}, the configuration is successful. Then, click OK to save.

Parameters

The request body from the platform is a JSON array. A single request can contain multiple status reports, and the format is the same for both individual and bulk messages.

Protocol

Parameter	Description
Request protocol	HTTP
Request format	application/json
Encoding	UTF-8

Sample payload

[
  {
    "phone_number" : "1381111****",
    "send_time" : "2017-01-01 00:00:00",
    "report_time" : "2017-01-01 00:00:00",
    "success" : true,
    "err_code" : "DELIVERED",
    "err_msg" : "Delivered successfully",
    "sms_size" : "1",
    "biz_id" : "12345********",
    "out_id" : "67890**"
  }
]

Fields

Parameter	Type	Description
phone_number	String	The recipient's phone number.
send_time	String	The time the message was sent.
report_time	String	The time the status report was generated.
success	Boolean	Indicates whether the message was delivered. Valid values: true: The message was delivered successfully. false: The message failed to be delivered.
err_code	String	The status report code.
err_msg	String	The delivery status message.
sms_size	String	The length of the SMS message. For more information about how message length is calculated, see SMS sending rules.
biz_id	String	The receipt ID. The SendSmsVerifyCode API returns a unique `BizId` for each call from the same Alibaba Cloud account.
out_id	String	The `outId` that you specified when calling the SendSmsVerifyCode API.

Response

After your HTTP endpoint receives a request, it must return a response in the following format.

Sample response

{
  "code" : 0,
  "msg" : "Received successfully"
}

Fields

Parameter	Type	Required	Example	Description
code	Number	Yes	0	The response code.
msg	String	No	Received successfully	The response message.

Note

A push is considered successful if your endpoint returns an HTTP 200 status code. The system only validates that the code field contains a number and ignores other content in the response body. If the status code is not 200 or the request times out, the system performs a retry push.
If your endpoint encounters a system exception or fails to process the message, return a 5xx HTTP status code.

Retry push

If the initial push fails, the system automatically retries three times: after 1 minute, 5 minutes, and 10 minutes. No further attempts are made after the third retry fails.

Receiving reports

@PostMapping("/resMsg")
public JSONObject resMsg(@RequestBody JSONArray array) {
   // TODO: Process the status report. This example only prints the report information.
   System.out.println(array.toJSONString());
   JSONObject json = new JSONObject();
   json.put("code", 0);
   json.put("msg", "Received successfully");
   return json;
}