To receive messages/events from SCG to your application, you can setup a delivery configuration (webhook) and Subscribe to the ESS: SCG-Message topic to have these events posted to their application as JSON/XML objects.
For more detailed information on how to setup a Webhook, please refer to the knowledge base article: How to setup a Webhook for Receiving Messages and Notifications – Syniverse Developer Community
This document describes the fields of the messaging events sent by ESS, via delivery configurations (aka webhooks), to clients. It describes the fields for the following event types:
- MT events (or DRs): These are generated when a mobile terminated message is sent from an enterprise application to a user’s handset via SCG.
- MO events: These are generated when a message sent from the user’s handset, is received in SCG.
Messaging Events specification
{
"topic": string
"attempt": integer
"event": json
"event_id": string
}
"event": {
"fld-val-list": json
"evt-tp": string
"timestamp": string
}
"fld-val-list": {
"previous_state": string
"message_request_id": string
"message_id": string
"to_address": string
"has_attachment": boolean
"attachment_ids": string
"reason_code": string
"reason_description": string
"number_type": string
"carrier_id": string
"carrier_name": string
"application_id": integer
"sender_id_alias": string
"company-id": integer
"sender_id_id": string
"external_message_request_id": string
"new_state": string
"fragments_count": integer
"from_address": string
"mt_price": decimal
"mo_price": decimal
"message_body": string
"message_body_truncated": boolean
}
|
Field |
Type |
Mandatory |
Description |
|
|
Topic |
string |
true |
The name of the topic customer has subscribed to receive events. |
|
|
Attempt |
integer |
true |
Number of times the events delivery service tried to deliver the event to target end point. |
|
|
Event |
json |
true |
The JSON object that stores the details of the event. |
|
|
event.fld-val-list |
json |
true |
The JSON object that stores the details of the event. mo_message_received message_request_state_change (applies only to MT message flow) message_state_change (applies only to MT message flow) |
|
|
event.evt-tp |
string |
true |
Type of event mo_message_received (Applies only to MO message flow) message_request_state_change (applies only to MT message flow) message_state_change (applies only to MT message flow) |
|
|
event.timestamp |
string |
true |
The date and time that this message created/received. |
|
|
event.fld-val-list.company-id |
integer |
true |
Unique ID of the customer account |
|
|
event.fld-val-list.from_address |
string |
false |
The sender address. |
|
|
event.fld-val-list.to_address |
string |
false |
The recipient address |
|
|
Field |
Type |
Mandatory |
Description |
|
event.fld-val-list.message_id |
string |
true |
The unique id of the message |
|
event.fld-val-list.message_request_id |
string |
false |
The unique id of the message request |
|
event.fld-val-list.sender_id_id |
string |
false |
The sender_id associated with the message delivery channel. For MT messages this will be the sender_id used to deliver the message. For MO messages this will be the sender_id corresponding to the downstream system which generated the message (determined by SCG based on the from/to address accordingly) |
|
event.fld-val-list.sender_id_alias |
string |
false |
The alias name for the sender_id address (if any). Default value is sender_id_id. |
|
event.fld-val-list.mt_price |
decimal |
false |
The cost for this MT message |
|
event.fld-val-list.mo_price |
decimal |
false |
The cost for this MO message |
|
event.fld-val-list.fragments_count |
integer |
false |
Number of fragments in this MO message (1 fragment is 160 chars (ASCII), 70 chars in case of GSM7BIT or UCS2) |
|
event.fld-val-list.has_attachment |
boolean |
false |
True - if the message has any attachments False – If there are no attachments |
|
event.fld-val-list.attachment_ids |
string |
false |
Attachment IDs (comma separated) which are associated with this message. |
|
event.fld-val-list.application_id |
integer |
false |
Unique ID of the application that has created the resource |
|
event.fld-val-list.message_body |
string |
true* |
This is the body of the message |
|
Field |
Type |
Mandatory |
Description |
|
event.fld-val-list.message_body_truncated |
boolean |
false |
If the body of the message is greater than 1530 characters, the event notification will pass only the first 1530 characters and will indicate message body has been truncated. |
|
event.fld-val-list.new_state |
string |
true |
New state of message request. DELIVERED indicates the operator has sent the message to the mobile successfully. |
|
event.fld-val-list.previous_state |
string |
true |
State of message request before the new state. |
|
event.fld-val-list.reason_code |
string |
true |
This code indicates if the message was delivered or not to the user’s handset. A 200 value indicates that the message was delivered successfully. For a comprehensive list of error codes returned by SCG via the Event Subscription Service, please refer to the following link, : SCG-Voice-and-Messaging-error-codes
|
|
event.fld-val-list.reason_description |
string |
true |
The description of the reason_code. If reason_code = 200, then reason_description is set to “SUCCESS” |
|
event.fld-val-list.number_type |
string |
false |
For MT messages this will be the type (“L” for Landline or “M” for mobile) of the recipient phone number. (Optional) |
|
event.fld-val-list.carrier_id |
string |
false |
For MO messages this is the carrier id (Optional). |
|
event.fld-val-list.carrier_name |
string |
false |
For MO messages this is the carrier name (Optional). |
|
event.fld-val-list.external_message_request_id |
string |
false |
Unique tracking ID for the message provided by the enterprise application. It can be used as an alternative key in query methods. (Optional) |
|
event_id |
string |
true |
Unique id of the event |
Optional information
Number type
The recipient number type (event.fld-val-list.number_type) can be included in the DR when the Phone Number Verification option is selected.
There are two ways of getting the number_type field in the DR:
Through the SCG Messaging API: The field "verify_number" must be set to ”true” when sending the MT message via the SCG Messaging API, as shown in this example:
curl -L -X POST https://api.syniverse.com/scg-external-api/api/v1/messaging/message_requests \
-H "Content-Type: application/json" \
-H "Authorization: Bearer [TOKEN]" \
-d "{\"from\":\"channel:1KJPMkuHQkair_o15etpmg\",\
\"verify_number\":true,\
\"to\":[\"+1813537XXXX\"],\
\"body\":\"Test message with PNV true\"\
}"
Through the “Send message” option in the SCG Voice & Messaging console: Check the Verify Number check box as shown here:
Carrier ID and name
Carrier ID (event.fld-val-list.carrier_id) and Carrier Name (event.fld-val-list.carrier_name) can be included in the MO notification by customer request. These fields can be enabled by raising a ticket to Syniverse.
The feature needs to be enabled on a per customer basis and the scope is account level. When this feature is enabled, it applies to all MO and DR messages.
External Message Request ID
The External Message Request ID (event.fld-val-list.external_message_request_id) can be included in the DR through the SCG Messaging API providing the field "external_id" when sending the MT message, as shown in this example:
curl -L -X POST https://api.syniverse.com/scg-external-api/api/v1/messaging/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer [TOKEN]" \
-d "{\"from\":\"channel:1KJPMkuHQkair_o15etpmg\", \
\"external_id\":\"1122334455\",\
\"to\":\"+1813537XXXX\",\
\"body\":\"Test message with external_id 1122334455 using curl command\"\
}"
As result, the DR for this request is:
{
"topic": "SCG-Message",
"attempt": 1,
"event": {
"fld-val-list": {
"previous_state": "SENT",
"message_request_id": "G4Hzsz1SzP1qPD4NUc8rH6",
"message_id": "G4Hzsz1SzP1qPD4NUc8rH6",
"to_address": "+1813537XXXX",
"has_attachment": false,
"reason_description": "SUCCESS",
"application_id": 11407,
"reason_code": "200",
"sender_id_alias": "FVwXNFWghnXyBazsR1HxQ3",
"company-id": [company_id],
"sender_id_id": "FVwXNFWghnXyBazsR1HxQ3",
"external_message_request_id": "1122334455",
"new_state": "DELIVERED",
"fragments_count": 1,
"from_address": "7777",
"mt_price": 0.024
},
"evt-tp": "message_state_change",
"timestamp": "2022-06-29T17:02:29.045Z"
},
"event-id": "P1bn6VXjTkyQ9HCLHDypAQ"
}
Samples of REST SMS API Call Delivery Receipts
MT event / Message Delivery Receipts
{
"topic": "SCG-Message",
"attempt": 1,
"event": {
"fld-val-list": {
"previous_state": "SENT",
"message_request_id": "tV9ldESMo3iGH2F39YY7V2",
"message_id": "tV9ldESMo3iGH2F39YY7V2",
"to_address": "wa:+1813809XXXX@1832999XXXX",
"has_attachment": false,
"reason_description": "SUCCESS",
"application_id": 11234,
"reason_code": "200",
"sender_id_alias": "whatsapp_1832999XXXX",
"company-id": [company_id],
"sender_id_id": "7ox2XHyusalKVReJSUEKd4",
"external_message_request_id": "",
"new_state": "DELIVERED",
"fragments_count": 1,
"from_address": "1832999XXXX",
"mt_price": 0.005
},
"evt-tp": "message_state_change",
"timestamp": "2022-06-17T18:24:53.218Z"
},
"event-id": "_nzwfwY-TsOA4eibsS6E5Q"
}
MO Event
{
"topic": "SCG-Message",
"attempt": 1,
"event": {
"fld-val-list": {
"sender_id_alias": "whatsapp_18329997008",
"mo_price": 0,
"company-id": [company_id],
"sender_id_id": "7ox2XHyusalKVReJSUEKd4",
"message_body": "hi",
"message_id": "xv2zjeoLRzJ8NFztxIx632",
"to_address": "1832999XXXX",
"has_attachment": false,
"from_address": "+1813809XXXX",
"application_id": 9762
},
"evt-tp": "mo_message_received",
"timestamp": "2022-06-17T18:24:48.06Z"
},
"event-id": "5OUWbEpORW63m_JXUdZlXA"
}
0 Comments