submitMtMessage

Last Updated: Tuesday, November 8, 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.

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.	Boolean	No	False
	splitLongMessage	A Boolean flag, used to request that any messages greater than 160 characters be split into multiple messages. For those carriers that support concatenation, the message may appear as a single message up to 900 characters. Read more on message splitting here.	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. 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 (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 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
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