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 49 Current »




POST - /MessageApi/mt/messageLists

Invoking this method will queue a list of Mobile Terminated (MT) messages for delivery to multiple recipients. The requester will receive a synchronous response containing the assigned listId and a preliminary status of every message in the list. Delivery status can be configured as a callback, or requested manually through another Application Program Interface (API) method.

Topics in this Section



If any part of the request fails due to invalid schema or values, the request (or part of it) will return as an error. If access to the Vibes platform system is lost during the request, all of the messages will be failed to enable easier retries.

A maximum of 100 destinations is supported. Requests over 500KB will be rejected.

HTTP Headers

X-VibesAPI-SubmitterListId: ListId

XML Request Example

POST
X-VibesAPI-SubmitterListId: 234523456252

<?xml version="1.0" encoding="UTF-8"?>
<mtMessageList submitterListId="234523456252" splitLongMessage="true">
	<destination submitterMessageId="234523456252" carrier="102" address="+18475551212" type="MDN" />
	<destination submitterMessageId="234523456253" carrier="103" address="+19475551212" type="MDN" />
	<source address="98765" type="SC" />
	<text>123857AB12</text>
	<receiptOption callbackUrl="http://www.client.com/callback">ERROR</receiptOption>
</mtMessageList>

Success XML Response Example

The response will include a preliminary status for each message in the list. If a submitterMessageId was provided, each status will be referenced by it. This preliminary check includes basic XML validation and carrier provisioning. Any errors that occur after this preliminary check would be discovered via the callback mechanism.

<mtMessageListRsp listId="b75fccf3-8f06-4d8f-a282-d1886a4792a1" submitterListId="234523456252" splitLongMessage="true">
	<results messageId="b75fccf3-8f06-4d8f-a282-d1886a4792a2" submitterMessageId="234523456252" address="+18475551212" carrier="102" code="0" description="Success"/>
	<results messageId="b75fccf3-8f06-4d8f-a282-d1886a4792a3" submitterMessageId="234523456253" address="+19475551212" carrier="103" code="0" description="Success"/>
</mtMessageListRsp>

XML Response with Errors

Depending on the type of error, requests may partially fail or entirely fail.

The request may partially fail if there is an error within a dest element. If part of a request fails, the response XML will return as normal with the assigned listId and include an error code with each destination that failed.

If the entire request fails, no mtMessageListRsp element will be returned. Instead, a single error element will return as specified in Appendix A - API Response Error Codes.

<mtMessageListRsp listId="b75fccf3-8f06-4d8f-a282-d1886a4792a1" submitterListId="234523456252" splitLongMessage="false">
	<results submitterMessageId="234523456252" address="+18475551212" code="1000" description="Error Code Reason" retriable="false" />
	<results submitterMessageId="234523456253" address="+19475551212" code="1000" description="Error Code Reason" retriable="false" />
</mtMessageListRsp>

Request Header Descriptions

Header

Description

Required

Content-Type

Text/XML

Yes

X-VibesAPI-SubmitterListId

A client-definable identifier for a message. This will be stored on the message for reference purposes, and must be 40 characters or less. 
This value has precedence over the submitterListId attribute in the messageList element of the request.

No

Request Element Descriptions

Element

Attribute Name

Description

Data Type

Required

Default

messageList

 

Identifies all of the information content to deliver an MT message.

 

Yes

 

 

submitterListId

A client-definable identifier for a message list. This will be stored on the message list for reference purposes, and must be 40 characters or less. 
If the X-VibesAPI-SubmitterListId header is set, the header value will take precedence over this value.

String

No

 

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

destination

 

This element defines the destination to deliver the MT message.

 

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

 

 

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 Mobile Directory Number (MDN) for 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. Currently, the only supported type is SC for Short Code.

String

No

SC

text

 

This defines the message text to be delivered in the message. The characters must be XML encoded, and must be 160 characters or less (unencoded).

String

Yes

 

receiptOption

 

This element indicates the receipt notifications that should be sent with this message. The currently allowed values are: NONE, ERROR, ALL, SMSC_ERROR, SMSC_ALL.

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.

URL

Yes, unless NONE

 

companyId

 

The Company ID this message is being sent for.

Long

No

 

 

Response Element Descriptions

Element

Attribute Name

Description

Data Type

Required

Default

mtMessageListRsp

 

The main wrapper element around the list response.

 

Yes

 

 listIdThe Vibes identifier for the message list submitted.StringYes 

 

submitterListId

The client-definable identifier for the message list. This attribute will be set if it was set on the request.

String

No

 

 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 
results   Yes 
 messageIdThe Vibes identifier for the message. Yes 
 submitterMessageIdThe client definable identifier for the message that was sent with the request. This attribute will be set if it was set on the request.StringNo 
 addressThe deliverable address the message is being sent to.StringYes 
 codeThe API response code for the message. Refer to Appendix A - API Response Error Codes for the possible values.StringYes 
 descriptionA description of the response.StringYes 
 retriableA Boolean flag that specifies if a failed request can be retried. This is only set for errors.BooleanNo 

 


  • No labels