There are user scenarios where it is very valuable to get an important, timely message to a consumer without delay. Specific cases could include monitoring or alerting texts, PINs and two-factor authentication requests or password reset validations. In these scenarios, messages failing at the shortcode level should not preclude delivery of the message, with the preference being that the text message is sent through an alternate mechanism (Long Code). The value of delivering the messages outweighs any potential confusion from the message originating from a Long Code.
Vibes' Alternate Delivery feature meets this need by automatically attempting message failures via an alternately configured long code for these messages when the delivery fails at the carrier. The failures can include direct carrier failures as well as Delivery Receipt failures reported by a carrier.
|Note: Alternate Message Delivery is currently not supported for concatenated messages.|
In order to utilize this service, a customer will need to request it through their account service representative. A Long Code(s) will be acquired for their use and associated with their Short Code(s). From that point on, a customer can indicate any message submitted through the Application Program Interface (API) for alternateDelivery on the API call, and the feature will be enabled for that message.
XML Request Example
POST <?xml version="1.0" encoding="UTF-8"?> <mtMessage submitterMessageId="239487234987234" alternateDelivery="true"> <destination carrier="102" address="+18475551212" type="MDN" /> <source address="98765" type="SC" /> <text>123857AB12</text> <receiptOption callbackUrl="http://www.client.com/callback" >ERROR</receiptOption> <transaction id="6439376297230"/> </mtMessage>
The following diagram outlines the various Delivery Receipt (DLR) callbacks that will be returned (if requested) for a message request.
In the case when alternate delivery is requested, and the original message fails delivery at the carrier, a DLR will be returned for the original message indicating the failure along with the alternateMessageID that was created for the alternate. Both the original Message and the alternate Message will have the same submitterMessageID for customer reference. Another DLR will be returned for the alternate message which will also indicate the original messageUID for reference.
Message Status Changes
To support alternate message delivery, a new message status is added called Forwarded. This status will apply to any original messages that failed carrier delivery and had an alternate message created. Please see the specific DLR page for your connection method for details.
If alternate message delivery is applied, you may receive extra callbacks if you include intermediate callbacks in your request. You will also get extra information within the callback XML.
If you request intermediate callbacks, you will receive a callback when the original Mobile Terminated (MT) message succeeds or fails, and if it failed, when the alternate message succeeds or fails.
If you request only final callbacks, then you will only receive a callback when the original message succeeds, or the alternate message succeeds or fails.
Callbacks for the original MT message will include a new attribute in the root element: forwardedMessageId. This is the unique identifier of the alternate message generated due to the failure.
POST <?xml version="1.0" encoding="UTF-8"?> <mtMessageResponse messageId="865cd3d1-bea6-4a6f-8bac-bae483248a27" submitterMessageId="239487234987234" fwdToMessageId="734cd3d1-bea6-4a6f-8bac-bae985345a27" receiptDate="2011-04-19T15:10:08.320-05:00"> <type>Carrier</type> <status isError="true"> <description>Description of status</description> <errorCode>100</errorCode> <internalErrorCode>255</internalErrorCode> </status> </mtMessageResponse>
Callbacks for the alternate MT message will include a different attribute in the root element: originalMessageId. This is the unique identifier of the original MT message submitted to the API.
POST <?xml version="1.0" encoding="UTF-8"?> <mtMessageResponse messageId="734cd3d1-bea6-4a6f-8bac-bae985345a27" submitterMessageId="239487234987234" fwdFromMessageId="865cd3d1-bea6-4a6f-8bac-bae483248a27" receiptDate="2011-04-19T15:10:08.320-05:00"> <type>Carrier</type> <status isError="false"> <description>Success</description> </status> </mtMessageResponse>