Last Updated: Wednesday, March 16, 2022
POST - /MessageApi/mt/messages
Invoking this method will queue a Mobile Terminated (MT) message for delivery to a single recipient. The requester will receive a synchronous response containing the assigned messageId. Delivery status can be configured as a callback or it can be requested manually through another Application Program Interface (API) method.
Topics in this Section
XML Request Example
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>
Upon validating the request, the server will respond with appropriate information. If the server responds with an HTTP Server code of anything other than 200, then there was a system error that occurred, and the request should be attempted again. Otherwise, the server response will be the XML that indicates success or failure of the request.
Successful Response Example
<mtMessageRsp messageId="b75fccf3-8f06-4d8f-a282-d1886a4792a2" submitterMessageId="239487234987234" carrier="102" splitLongMessage="true"/>
Request Header Descriptions
Header | Description | Required |
---|---|---|
Content-Type | text/xml | Yes |
Request Element Descriptions
Element | Attribute Name | Description | Data Type | Required | Default |
---|---|---|---|---|---|
mtMessage | The main wrapper element around the submit request. | Yes | |||
submitterMessageId | A client-definable identifier for a message. This will be stored on the message for reference purposes, and must be 40 characters or less. | String | No | ||
alternateDelivery | A Boolean flag, used to request that a message use an Alternate Message Delivery mechanism if the message from the Shortcode fails. Note: To use this feature, a Longcode must be assigned to the Shortcode prior to sending any messages. | Boolean | No | False | |
splitLongMessage | A Boolean flag, used to request that any messages greater than 160 characters be split into multiple messages. | Boolean | No | False | |
destination | This element defines the destination to deliver the MT message. | Yes | |||
carrier | The carrier network the Mobile Phone is on. For replies, the carrier should be the same as the carrier on the original Mobile Originated (MO) message. If it is not specified, the system will query for the correct carrier. | String | No | ||
address | The deliverable address to deliver the message to. This must be specified in e.164 international format with a leading +. | String | Yes | ||
type | The address type for delivery. Currently, the only supported type is MDN for cellular telephone. | String | No | MDN | |
source | This element defines the source (Originating) account for the MT message. | Yes | |||
address | The source address/number that originated the MT request. | String | Yes | ||
type | The originating address type. | String | No | SC | |
text | This defines the message text to be delivered in the message. The characters must be XML encoded. 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 through the client's callback URL for this message.
| 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 XML encoded. | ||||
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 Descriptions
Element | Attribute Name | Description | Data Type | Required | Default |
---|---|---|---|---|---|
mtMessageRsp | The main wrapper element around the Submit response. | Yes | |||
messageId | The Vibes identifier for the message submitted. | String | Yes | ||
submitterMessageId | The client-definable identifier for the message that was sent with the request. This attribute will be set if it was set on the request. | String | No | ||
carrier | The carrier network the 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 | A Boolean flag confirming that the splitLongMessage is set to True on the request. This will only be set if it was set to True on the request. | Boolean | No |