Message Response

When a message is submitted, the server responds with the submit status of the message destinations. This information is stored in the data section of the response.

Information stored in a message response data include message reference, validation, destination status, etc.

The API allows multiple message definitions, each with its own destinations, to be submitted in single request batch. As a result of this, message response data contains information stored as an array of message submit status. An example is shown as follows.

JSON
XML

{
    "handshake" : {
        "id" : 0,
        "label" : "HSHK_OK"
    },
    "data": {
        "batch" : "cfa19ba67f94fbd6b19c067b0c87ed4f",
        "category": 1,
        "delivery": false,
        "destinations": [
            {
                "id" : "093841e5-578a-41f4-5f5f-2f3910886c12",
                "to" : "233246314915",
                "status" : {
                    "id" : 2105,
                    "label" : "DS_PENDING_ENROUTE"
                }
            },
            {
                "id" : "4abfa3bd-93f9-b8a1-4bbd-78725ca3e488",
                "to" : "233242053072",
                "status" : {
                    "id" : 2105,
                    "label" : "DS_PENDING_ENROUTE"
                }
            }
        ]
    }
}

<response>
    <handshake>
        <id>key</id>
        <label>HSHK_OK</label>
    </handshake>
    <data>
        <batch>cfa19ba67f94fbd6b19c067b0c87ed4f</batch>
        <category>1</category>
        <delivery>false</delivery>
        <destinations>
            <item>
                <id>093841e5-578a-41f4-5f5f-2f3910886c12</id>
                <to>233241234567</to>
                <status>
                    <id>2105</status>
                    <label>DS_PENDING_ENROUTE</label>
                </status>
            </item>
            <item>
                <id>4abfa3bd-93f9-b8a1-4bbd-78725ca3e488</id>
                <to>233501234567</to>
                <status>
                    <id>2105</status>
                    <label>DS_PENDING_ENROUTE</label>
                </status>
            </item>
        </destinations>
    </data>
</response>

Observe that the data section contains an array of messages. In this case, there is information for only a single message object. The message object contains information such as reference, validation, and destinations.

Reference

Each message definition that is composed and submitted in a request is assigned an identifier which can be used to reference that particular message. The value of the identifier assigned to the message is set as reference in the message response data. The message reference can, for example, be used to request for the delivery status of all destinations added to the message.

Validation

The validation section of the message response data indicates the validation status for a single message definition. A message validation label MV_OK with an id value of 1302 indicates that the message passed validation. Any other value indicates that the message did not pass validation. The message validation identifiers and their meaning can be referenced from Message Validation page.

Delivery

The value set to delivery indicates whether the response is for message delivery report or not. When a message is submitted, the server replies with a submit status and givies information such as message validation status as well as the destinations to which messages will be submitted.

delivery is always set to false for a message submit response to indicte that it is not a message delivery report. For responses to message delivery requests, delivery will always be set to true. This is discussed under the section on Reporting.

Destinations

The destinations section of the message response data contains an array of destination objects. Each destination object has the phone number set as to, an identifier assigned to the destination set as messageId, and the status of the destination as an object set as status.

The status object contains an id which indicates the submit status of the destination, and a label which describes the status of the destination. The message destination status identifiers and description can be referenced from the Destination Status page.