API Reference

Version Features

v3.2

v3.2 includes all features of v3.1, with the addition of:

Long Message Element

The longMessageInfo element is now available for incoming HTTP messages. If a message sent to your endpoint is longer than a standard text message, it may be split into multiple parts. In this case, the request from Vibes will include the longMessageInfo element.

Learn more on our Receive Messages page.

V3.1

Alternate Message Delivery

Alternate Message Delivery allows a customer to request certain messages to be delivered via a second method (via a long code or alternate short code) if the message fails to be delivered on the original short code.

This is useful for user scenarios in which it is essential to get an important, timely message to a consumer without delay, such as for messages related to monitoring or alerts, two-factor authentication, and account verification. Once set up on your account, it is enabled on a per message basis.

Please note that if this method is used, the consumer will receive a text from an alternative phone number than the one they might expect. However, in these scenarios, the value of delivering the messages often outweighs any potential confusion from the message originating from an alternative long code.

📘

Alternate Message Delivery is currently not supported for concatenated messages.

Configuration

To utilize this service, a customer will need to request it through their Account Service Representative. Alternative long or short codes will be acquired for their use and associated with their current code(s). From that point on, a customer can indicate any message submitted through the 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>

Message Flow

In the case when alternate delivery is requested, and the original message fails delivery at the carrier, a delivery receipt 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 delivery receipt 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 delivery receipt page for your connection method for details.

Callback Changes

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 outgoing message succeeds or fails, and if it failed, another callback 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 outgoing 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. See in used in the example below.

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 outgoing message will include a different attribute in the root element: OriginalMessageID. This is the unique identifier of the original outgoing 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>

Message Splitting & Multi-Part Messages

Vibes' Connect platform now allows API callers to submit SMS messages up to 900 characters in length. These messages will automatically split into multiple SMS messages and, for carriers that support it, Message Concatenation will be utilized so the message will appear as one large message on the device.

Implementation

This feature will be available for all API users and is enabled by setting a flag when a message is submitted. If that flag is set on a message and the message text exceeds the carrier length of a single SMS, it will be automatically split into multiple SMS messages.

Once the original message is split, each SMS message segment will be individually recorded, tracked, and billed as separate message. In addition, each of the SMS messages will be associated back to the original large message for reference.

The actual splitting logic varies based on each carrier's support for concatenated messaging, their specific implementation of concatenated messaging, and payload. Here are the specifics:

  • For carriers that support concatenated messaging, the original message will be split into specific SMS messages at the maximum concatenated SMS length for the carrier. This can be less than the maximum length of an SMS message, based on the carrier's rules and implementation on concatenated messages.
  • For carriers that do not support concatenated messaging, the message will be split by Vibes. The system will break messages on a word boundary when possible. However, if splitting a message on a word boundary would cause an extra message to be generated, then it will be split at the maximum character length to avoid the extra message.

🚧

Extra charges may apply

If your large SMS message is split into multiple messages for delivery, you will be billed for additional messages. If you would not like to incur extra charges, we recommend setting splitLongMessage to false.

v3.0

In Version 3.0, we’ve made several changes to the MessageAPI, primarily to support International Messaging. As part of the changes necessary for international numbers, additional requested items/features that require new XML attributes have also been added to provide more robust Application Program Interfaces (APIs).

International Support Changes

  • International format: All MDNs are now required to be in the International E.164 format, which is a +, followed by the country code, followed by the dial-able number. For example, +18475551212, where 1 is the code for North America. This includes parameters in the XML body, as well as cases when the URL contains an MDN.
  • Ten-character restriction removed: MDNs are no longer restricted or enforced to be 10 characters. MDNs can be up to 15 digits in length plus the '+' sign. Future validation checks may be put in place to ensure the correct number of digits for certain countries, but those would not change the API specifications.

Carrier in Message Responses

Carrier is now included in outgoing message responses. This is especially useful in cases when the carrier was not specified and was looked up by the API. This applies to the submitMtMessage response.