Event Subscription Messaging Events User Guide v1.2

Specification v1.2, June 2022

 

 

Introduction

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

 

Purpose of this document

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

Description

Topic

string

The name of the topic customer has subscribed to receive events.

Attempt

integer

Number of times the events delivery service tried to deliver the event to target end point.

Event

json

The JSON object that stores the details of the event.

event.fld-val-list

json

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

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

The date and time that this message created/received.

event.fld-val-list.company-id

integer

Unique ID of the customer account

event.fld-val-list.from_address

string

The sender address.

event.fld-val-list.to_address

string

The recipient address

 

 

Field

Type

Description

event.fld-val-list.message_id

string

The unique id of the message

event.fld-val-list.message_request_id

string

The unique id of the message request

event.fld-val-list.sender_id_id

string

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

The alias name for the sender_id address (if any). Default value is sender_id_id.

event.fld-val-list.mt_price

decimal

The cost for this MT message

event.fld-val-list.mo_price

decimal

The cost for this MO message

event.fld-val-list.fragments_count

integer

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

True - if the message has any attachments

False – If there are no attachments

event.fld-val-list.attachment_ids

string

Attachment IDs (comma separated) which are associated with this message.

event.fld-val-list.application_id

integer

Unique ID of the application that has created the resource

event.fld-val-list.message_body

string

This is the body of the message

 

 

Field

Type

Description

event.fld-val-list.message_body_truncated

boolean

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

New state of message request. DELIVERED indicates the operator has sent the message to the mobile successfully.

event.fld-val-list.previous_state

string

State of message request before the new state.

event.fld-val-list.reason_code

string

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

The description of the reason_code. If reason_code = 200, then reason_description is set to “SUCCESS”

event.fld-val-list.number_type

string

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

For MO messages this is the carrier id (Optional).

event.fld-val-list.carrier_name

string

For MO messages this is the carrier name (Optional).

event.fld-val-list.external_message_request_id

string

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

Unique id of the event

 

 

4.    Optional information

 

4.1 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\"}"

 

  1. Through the “Send message” option in the SCG Voice & Messaging console: Check the Verify Number check box as shown here:

Untitled.jpg

 

 

 

4.2 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.

 

 

4.2 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"

}

 

 

5.    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"

}

 

 

 

Was this article helpful?
0 out of 0 found this helpful

0 Comments

Please sign in to leave a comment.