Skip to end of metadata
Go to start of metadata

Last Updated: Thursday, July 18, 2019



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. 

Note: Positive acknowledgement of a message only means that the message is accepted and queued for delivery, and does not mean that the message was delivered to the recipient successfully.

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.
BooleanNoFalse

splitLongMessageA Boolean flag, used to request that any messages greater than 160 characters be split into multiple messages.BooleanNoFalse

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. 
If sending to a Shortcode, the value should be SC.
If sending to an international Alphacode, the value should be ANC. 

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.  
The currently allowed 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 upon send (does not include DLRs).
  • SMSC_ALL - send only notifications that from the carrier 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 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



messageIdThe Vibes identifier for the message submitted.StringYes


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



carrierThe 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.StringYes

splitLongMessageA 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.BooleanNo
  • No labels