Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 66 Next »




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