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 an Alibaba Cloud account and an AccessKey pair. For more information, see Create an AccessKey.
You have reviewed the overview and configuration of message receipts and understand their modes, types, and configuration process. Then, configure the message receipts accordingly.

Note

For the procedure of configuring MO messages, see Configure message receipts.

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

Parameter	Type	Required	Description
MessageId	String	Yes	Unique message identifier.
CustSpaceId	String	Yes	The channel ID.
WabaId	String	Yes	The ID of the WhatsApp Business Account (WABA).
From	String	Yes	The sender's phone number.
To	String	Yes	The recipient's phone number.
FromUserId	String	No	BSUID
FromParentUserId	String	No	Parent BSUID (if any)
FromUserName	String	No	User account (if any)
Timestamp	Long	Yes	Unix timestamp of the message, in milliseconds.
DisplayName	String	Yes	The sender's display name.
Type	String	Yes	Message type. Valid values: `TEXT` `LOCATION` `DOCUMENT` `VIDEO` `AUDIO` `REPLY` `IMAGE` `CONTACTS` `SYSTEM`
Message	Object	Yes	Message content. If Type is TEXT, this field contains the message content. If Type is LOCATION, see LOCATION object. If Type is VIDEO, see VIDEO object. If Type is AUDIO, see AUDIO object. If Type is DOCUMENT, see DOCUMENT object. If Type is REPLY, see REPLY object. If Type is IMAGE, IMAGE object. If Type is SYSTEM, see SYSTEM object.
Name	String	Yes	User name.

LOCATION object

Parameter	Type	Required	Description
address	String	Yes	Address information.
latitude	String	Yes	The latitude.
longitude	String	Yes	The longitude.
name	String	Yes	Location description.

VIDEO object

Parameter	Type	Required	Description
name	String	Yes	Video file description.
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.

IMAGE object

Parameter	Type	Required	Description
caption	String	No	Image description.
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.

AUDIO object

Parameter	Type	Required	Description
name	String	Yes	Audio file description.
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.

DOCUMENT object

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

REPLY object

Parameter	Type	Required	Description
text	String	Yes	Text label of the clicked button.
payload	String	Yes	Payload returned when the user clicks the button. Matches the payload defined in the sent message.

SYSTEM object

Parameter	Type	Required	Description
body	String	Yes	A change to the user's identity or phone number.
wa_id	String	Yes	The user's new WhatsApp ID after a phone number change.
type	String	Yes	System update type. Valid values: `customer_changed_number` : The user changed their phone number. `customer_identity_changed` : The user changed their profile.

Response

To acknowledge receipt, your endpoint must return HTTP 200 within 3 seconds. The response body must be a JSON object in the following format. Otherwise, the platform 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 a push attempt fails (non-200 response or timeout), the service retries after 1 minute and again after 5 minutes. After three failed attempts, retries stop.