post https://messageapi.vibesapps.com/MessageApi/mt/messages
To send a message to a mobile device, you’ll need to use the POST method with this API, which will allow you to define the destination of the message, the source, the body of the message, and other key details. Upon receiving the call, our system will respond with a unique messageID and a few other details.
All Vibes calls and responses are written in XML.
Remember that to make a call to any of Vibes’ APIs, you’ll need to include Authentication and all required headers.
Example of a Call
To start, here’s an example of a call. The required elements are detailed below.
POST
<?xml version="1.0" encoding="UTF-8"?>
<mtMessage submitterMessageId="239487234987234" splitLongMessage="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>
Elements and Attributes of a Call
Required
mtMessage
This is the main wrapper for your submit request.
| Attribute Name | Description | Data Type | Required? | Default |
|---|---|---|---|---|
submitterMessageId | Use this attribute to define your own ID for a message for future reference purposes. The identifier must be 40 characters or less. | String | No | |
alternateDelivery | Available for v3.1+ only. Set this to true if you would like a message to use an alternate message delivery mechanism if the message from the short code fails.Note: To use this feature, a long code must be assigned to the short code prior to sending any messages. | Boolean | No | False |
splitLongMessage | This flag determines whether any messages greater than 160 characters be split into multiple messages. For those carriers that support concatenated messages , the message may appear as a single message up to 900 characters. Read more about message splitting here. | Boolean | No | False |
destination
This element defines the destination to deliver the outgoing message.
| Attribute Name | Description | Data Type | Required? | Default |
|---|---|---|---|---|
carrier | The carrier network the Mobile Phone is on. If it is not specified, the system will query for the correct carrier. | String | No | |
address | The mobile device number (MDN) to deliver the message to. This must be specified in e.164 international format with a leading +. | String | Yes |
source
| Attribute Name | Description | Data Type | Required? | Default |
|---|---|---|---|---|
address | Your identifying short, long, or alpha code, which will appear to the receiver as the sender of the message. If you are using a long code, do not include the leading +. | String | Yes | |
type | The type of number of the sender. - If sending from a short or long code, the value should be SC. - If sending from an international alpha code, the value should be ANC. | String | No | SC |
text
This element defines the text of the message you’d like to send. The message must be encoded in XML. If splitLongMessage is NOT set to True in mtMessage, then the message must be 160 characters or less.
Optional
Each of the following elements are optional.
receiptOption
This element indicates the receipt notifications that should be sent as a callback for this message.
Available values are as follows:
NONE- send no notifications.ERROR- send only error notifications (includes error deliver receipts).ALL- send all notifications (includes DLRs).SMSC_ERROR- send only error notifications that come from the carrier (next Hop) upon send (does not include delivery receipts).SMSC_ALL- send only notifications that from the carrier (next Hop) upon send (does not include delivery receipts).
| Attribute Name | Description |
|---|---|
callbackUrl | This attribute defines the URL that all receipt notifications should be delivered to. If the receiptOption value is NONE, the value of this attribute will be ignored. The characters must be encoded in XML. |
transaction
This element references the message (if any) that started this conversation. If this MT message is an alert, this element should be omitted.
| Attribute Name | Description | Data Type | Required for this element? | Default |
|---|---|---|---|---|
id | The value of the transaction ID provided with the MO message that started this conversation. The value may be up to 40 characters. | String | Yes | N/A |
companyId
The Company ID this message is being sent for.
Response
mtMessageRsp is the main wrapper for a response.
| Attribute Name | Description | Data Type |
|---|---|---|
messageId | The Vibes identifier for the message submitted. | String |
submitterMessageId | If submitterMessageId was set in your request, it may be repeated in the response. | String |
carrier | The carrier code of the network the message receiver’s Mobile Phone is on. If a carrier is submitted with the request the same is returned, otherwise the carrier that is queried is returned. | String |
splitLongMessage | If splitLongMessage is set to True on the request, this may be repeated in the response. | Boolean |
Reference Table
The reference tables below contain the same information as above, but in a quick-reference table form.
Request
| Element | Attribute Name | Description | Data Type | Required? | Default |
|---|---|---|---|---|---|
mtMessage | The main wrapper element around the submit request. | Yes | |||
submitterMessageId | Use this attribute to define your own ID for a message for future reference purposes. The identifier must be 40 characters or less. | String | No | ||
alternateDelivery | Available for v3.1+ only. Set this to “ true” if you would like a message to use the alternate message delivery mechanism if the message from the short code fails.Note: To use this feature, a long code must be assigned to the short code prior to sending any messages. | Boolean | No | False | |
splitLongMessage | This flag determines whether any messages greater than 160 characters be split into multiple messages. Note: If the carrier supports concatenated messages, it will appear as a single message to the end user. | Boolean | No | False | |
destination | This element defines the destination to deliver the outgoing message. | Yes | |||
carrier | The carrier network the Mobile Phone is on. If it is not specified, the system will query for the correct carrier. | String | No | ||
address | The mobile device number (MDN) to deliver the message to. This must be specified in e.164 international format with a leading +. | String | Yes | ||
~~type~~ | |||||
source | This element defines what mobile device number is the sender of the message. | Yes | |||
address | Your identifying short, long, or alpha code, which will appear to the receiver as the sender of the message. If you are using a long code, do not include the leading +. | String | Yes | ||
type | The type of number of the sender. - If sending from a short or long code, the value should be SC. - If sending from an international alpha code, the value should be ANC. | String | No | SC | |
text | The text of the message you’d like to send. The characters must be encoded in XML. Must be 160 characters or less if the splitLongMessage is NOT set to True, and 900 characters or less if splitLongMessage is set to True (unencoded). | String | Yes | ||
receiptOption | This element indicates the receipt notifications that should be sent as a callback for this message. Available values are as follows: - NONE - send no notifications.- ERROR - send only error notifications (includes error DLRs).- ALL - send all notifications (includes DLRs).- SMSC_ERROR - send only error notifications that come from the carrier (next Hop) upon send (does not include DLRs).- SMSC_ALL - send only notifications that from the carrier (next Hop) upon send (does not include DLRs). | String | No | NONE | |
callbackUrl | This attribute defines the URL that all receipt notifications should be delivered to. If the receiptOption value is NONE, the value of this attribute will be ignored. The characters must be encoded in XML. | ||||
transaction | This element references the message (if any) that started this conversation. If this MT message is an alert, this element should be omitted. | No | |||
id | The value of the transaction ID provided with the MO message that started this conversation. The value may be up to 40 characters. | String | Yes | ||
companyId | The Company ID this message is being sent for. | Long | No |
Response
| Element | Attribute Name | Description | Data Type | Required? |
|---|---|---|---|---|
mtMessageRsp | The main wrapper element around the Submit response. | Yes | ||
messageId | The Vibes identifier for the message submitted. | String | Yes | |
submitterMessageId | If submitterMessageId was set in your request, it may be repeated in the response. | String | No | |
carrier | The carrier code of the network the message receiver’s Mobile Phone is on. If a carrier is submitted with the request the same is returned, otherwise the carrier that is queried is returned. | String | Yes | |
splitLongMessage | If splitLongMessage is set to True on the request, this may be repeated in the response. | Boolean | No |
Example success response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<mtMessageRsp submitterMessageId="AnyValue" messageId="e9efe523-aa57-4fdb-8f57-f15a4b06c91e" splitLongMessage="true"/>
Example failure response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error code="1031" description="Unable to resolve Carrier for MDN: 5125551212, Reason Unsupported MDN: 15125551212" retriable="false"/>