Receive MO messages by specifying an HTTP URL - Chat App Message Service

Specify an HTTP URL to receive Mobile Originated (MO) messages.

Protocol specification

Parameter	Description
Protocol	HTTP + JSON
Encoding	UTF-8

Prerequisites

You have registered an Alibaba Cloud account and created an AccessKey pair. For more information, see Create an AccessKey pair.
You have reviewed the overview and configuration of message receipts and understand their modes, types, and configuration process. Then, configure the message receipts accordingly.

Request format

A single request may contain multiple MO messages.

Example request when Type is TEXT

[
   {
   "MessageId": "1000000000000001",  
   "From": "861388888****",    
   "To": "86137888****",    
   "DisplayName": "Mr Liu",
   "Type": "TEXT",
   "Message": "hello,it's me",    
   "Timestamp": 1662104191973,
   "Name": "jack"
   },
   {
   "MessageId": "1000000000000002",  
   "From": "861388888****",    
   "To": "86139123****",    
   "DisplayName": "Mr Wang",
   "Type": "TEXT",
   "Message": "hello,it's me",    
   "Timestamp": 1662104191973,
   "Name": "Jones"
   }
]

Example request when Type is AUDIO

[ 
   {    
   "MessageId": "1000000000000003",    
   "CustSpaceId": "cams-83m8j9xxxxadc",
   "From": "+861388888****",     
   "DisplayName": "Mr Liu",
   "NoticeType": "inbound",     
   "To": "+861378886****",    
   "Type": "AUDIO",    
   "Message": 
     "{
     \"filename\":\"File.ogg\",
     \"animated\":false,
     \"id\":\"3214520xxxx75431\",
     \"mimeType\":\"audio/ogg\",
     \"url\":\"https://whatsapp-prod-oss-bucket.oss-ap-southeast-1.aliyuncs.com/1161931534xxxx19904.ogg\"
     }",
   "Timestamp ": 1662104191973,        
   "Name": "jack",
   "WabaId": "95271863xxxx233",
   },
   {    
   "MessageId": "1000000000000004",
   "CustSpaceId": "cams-83m8j9xxxxadc",  
   "From": "+861388888****",     
   "DisplayName": "Mr Wang",
   "NoticeType": "inbound",  
   "To": "+861378886****",
   "Type": "AUDIO",    
   "Message": 
     "{
     \"filename\":\"File.ogg\",
     \"animated\":false,
     \"id\":\"3214520xxxx75431\",
     \"mimeType\":\"audio/ogg\",
     \"url\":\"https://whatsapp-prod-oss-bucket.oss-ap-southeast-1.aliyuncs.com/1161931534xxxx19904.ogg\"
     }",   
   "Timestamp ": 1662104191973,        
   "Name": "John",
   "WabaId": "95271863xxxx233",
   }
]

Example request when Type is DOCUMENT

[
   {    
   "MessageId": "1000000000000005",    
   "From": "+861388888****",         
   "DisplayName": "Mr Liu",
   "NoticeType": "inbound", 
   "To": "+861378889****",    
   "Type": "DOCUMENT",    
   "Message": 
     "{
     \"filename\":\"eventlog_20251211_155722_GMT.jsonl\",
     \"animated\":false,
     \"id\":\"275171383xxxx878\",
     \"mimeType\":\"application/octet-stream\",
     \"url\":\"https://bucket-chatapp-file-internal.oss-ap-southeast-1.aliyuncs.com/1161931xxxxx8375296.jsonl\"
     }",
   "Timestamp ": 1662104191973,        
   "Name": "jack",
   "WabaId": "212506738xxxx650",
   "CustSpaceId": "cams-85sglhxxxxkw"
   },
   {    
   "MessageId": "1000000000000006",    
   "From": "+861388888****",         
   "DisplayName": "Mr Liu",    
   "NoticeType": "inbound", 
   "To": "+861378882****",    
   "Type": "DOCUMENT",    
   "Message": 
     "{
     \"filename\":\"eventlog_20251211_155722_GMT.jsonl\",
     \"animated\":false,
     \"id\":\"275171383xxxx878\",
     \"mimeType\":\"application/octet-stream\",
     \"url\":\"https://bucket-chatapp-file-internal.oss-ap-southeast-1.aliyuncs.com/1161931xxxxx8375296.jsonl\"
     }",  
   "Timestamp ": 1662104191973,        
   "Name": "Jone",
   "WabaId": "212506738xxxx650",
   "CustSpaceId": "cams-85sglhxxxxkw"
   } 
]

Example request when Type is REPLY

[
   {    
   "MessageId": "1000000000000007",    
   "From": "861388888****",        
   "DisplayName": "Mr Liu",    
   "To": "861378886****",    
   "Type": "REPLY",    
   "Message": "{ \"text\": \"click me\",\"payload\": \"1000000\" }" ,    
   "Timestamp ": 1662104191973
   },
   {    
   "MessageId": "1000000000000008",    
   "From": "861388888****",        
   "DisplayName": "Mr Wang",    
   "To": "861378883****",    
   "Type": "REPLY",    
   "Message": "{ \"text\": \"click me\",\"payload\": \"1000000\" }" ,    
   "Timestamp ": 1662104191973
   } 
]

Example request when Type is LOCATION

[
   {    
   "MessageId": "1000000000000009",    
   "From": "861388888****",        
   "DisplayName":"Mr Liu",    
   "To": "861378868****",    
   "Type": "LOCATION",    
   "Message": 
     "{
     \"address \": \"changsha yuelu street \", 
     \"latitude \": \"39.999137107913\", 
     \"longitude \": \"116.48074005043\", 
     \"name \": \"this is firest location message\" 
     }",    
   "Timestamp ": 1662104191973,        
   "Name": "jack"
   },
   {    
   "MessageId": "1000000000000010",    
   "From": "861388888****",        
   "DisplayName":"Mr Wang",    
   "To": "861378168****",    
   "Type": "LOCATION",    
   "Message": 
     "{
     \"address \": \"changsha yuelu street \", 
     \"latitude \": \"39.999137107913\", 
     \"longitude \": \"116.48074005043\", 
     \"name \": \"this is firest location message\" 
     }",    
   "Timestamp ": 1662104191973,        
   "Name": "Jone"
   }
]

Field description

Field	Type	Required	Description
MessageId	String	Yes	The unique identifier of the message.
CustSpaceId	String	Yes	The channel ID.
WabaId	String	Yes	The WhatsApp Business Account ID.
From	String	Yes	The sender's phone number.
To	String	Yes	The recipient's phone number.
Timestamp	Long	Yes	The Unix timestamp when the message was sent, in milliseconds.
DisplayName	String	Yes	The sender's display name.
Type	String	Yes	The type of the message. Valid values: TEXT LOCATION DOCUMENT VIDEO AUDIO REPLY IMAGE CONTACTS
Message	String	Yes	The content of the message. If Type is `TEXT` , this is the message text. If `Type` is `LOCATION` , see LOCATION object section. If `Type` is `VIDEO` , see VIDEO object section. If `Type` is `AUDIO` , see AUDIO object section. If `Type` is `DOCUMENT` , see DOCUMENT object section. If `Type` is `REPLY` , see REPLY object section. If `Type` is `IMAGE` , see IMAGE object section. If `Type` is `SYSTEM` , see SYSTEM object section.
Name	String	Yes	The name of the user.

LOCATION object

Field	Type	Required	Description
address	String	Yes	The address information.
latitude	String	Yes	The latitude.
longitude	String	Yes	The longitude.
name	String	Yes	A location description.

VIDEO object

Field	Type	Required	Description
name	String	Yes	A description of the video file.
id	String	Yes	The ID of the video file.
mimeType	String	Yes	Fixed value: ogg. Note This parameter can be ignored if `codecs=opus`.
url	String	Yes	The URL of the video file. Note The URL is valid for 7 days.

AUDIO object

Field	Type	Required	Description
name	String	Yes	A description of the audio file.
id	String	Yes	The ID of the audio file.
mimeType	String	Yes	Fixed value: audio. Note This parameter can be ignored if `codecs=opus`.
url	String	Yes	The URL of the audio file. Note The URL is valid for 7 days.

IMAGE object

Field	Type	Required	Description
caption	String	No	A description of the image.
id	String	Yes	The ID of the image.
mimeType	String	Yes	The MIME type of the image.
url	String	Yes	The URL of the image. Note The URL is valid for 7 days.

DOCUMENT object

Field	Type	Required	Description
name	String	Yes	A description of the document.
id	String	Yes	The ID of the document.
filename	String	Yes	The file name of the document.
mimeType	String	Yes	Fxed value: `application/pdf` .
url	String	Yes	The URL of the document. Note The URL is valid for 7 days.

REPLY object

Field	Type	Required	Description
text	String	Yes	The text label of the button that the user clicked.
payload	String	Yes	The payload associated with the clicked button, which you defined when sending the message.

SYSTEM object

Field	Type	Required	Description
body	String	Yes	Describes a change in the user's identity or phone number.
wa_id	String	Yes	The user's new WhatsApp ID after their phone number is updated.
type	String	Yes	The type of system update. Valid values: `customer_changed_number` : The user changed their phone number. `customer_identity_changed` : The user changed their profile.

Response

To acknowledge the receipt of a callback, your endpoint must return an HTTP 200 status code in 3 seconds. The response body must be a JSON object in the following format. Otherwise, the platform considers the delivery a failure and retries the request.

Example response

{
  "code": 0,
  "msg": "Success"
}

Field description

Field	Type	Required	Description
code	Number	Yes	The response code.
msg	String	No	A descriptive message.

Retry policy

If an initial push attempt fails, the service retries the request after 1 minute and again after 5 minutes. An attempt fails if your endpoint returns a non-200 HTTP status code or if the request times out. After three failed attempts, the service stops retrying.