Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Changed text max characters from 800 to 900 (as requested by Rahul)

Last Updated:

Lastupdatedate

Livesearch
placeholderSearch the Vibes Developer Wiki
typepage



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.


Panel
borderColor#2B9CD7

Topics in this Section

Page Tree
root@self
startDepth2




XML Request Example


Code Block
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
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

Code Block
<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
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 800 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