On occasion, you may want to query our APIs for data on a previous send or specific mobile number. In this article, you'll learn how to gain meta information using URL calls.

Skip to a specific section:

Retrieve all available information on a previous call
Retrieve system responses on a previous send
Retrieve information about a message that was split into multiple parts
Retrieve carrier information for a mobile number

Retrieve All Available Info

Using this GET method, you can retrieve information about previous messages you've sent to a handset, which you can use for informational purposes or to troubleshoot a specific issue.

To perform this call, you'll need the specific messageID for the message you'd like information on. The messageID is returned when you successfully submit a message.

📘
Asynchronous processing
Our system processes asynchronously, meaning your message is not guaranteed to be available and retrievable until after the response callback has been made. Additionally, this call should be used only to retrieve a specific message for informational purposes.

🚧
Do not use for data retrieval
This API should not be used for mass message data retrieval. If information is needed on multiple MT message status, please see our Callbacks article.

Request

Below is an example of the URL request for this information.

https://messageapi.vibesapps.com/MessageApi/mt/messages/b75fccf3-8f06-4d8f-a282-d1886a4792a2

Response

Below is an example of the response you might get to the above request. The relevant elements are defined below.

<mtMessage submitterMessageId="239487234987234"
    messageId="b75fccf3-8f06-4d8f-a282-d1886a4792a2" 
    submitDate="2011-04-19T15:10:08.320-05:00" isMultipart="true" noOfParts="2" partNumber="1" originalMessageId="b75fccf3-8f06-4d8f-a282-d1886a4792a2">
    <destination carrier="102" address="+12995551234" type="MDN" />
    <source address="98765" type="SC" />
    <text>123857AB12</text>
    <receiptOption>ERROR</receiptOption>
</mtMessage>

mtMessage is the main wrapper element for the response to this response. The attributes are displayed in a table below. For more information about the other elements and attributes not defined here, see our article on sending an SMS message

Attribute Name	Description	Data Type
`isMultipart`	Only present if equal to `True`, which indicates the message was split into multiple parts.	Boolean
`noOfParts`	Only present if `isMultipart="true".` This string indicates the number of parts the message was split into.	String
`partNumber`	Only present if `isMultipart="true".` This string indicates the number of this message's part.	String
`originalMessageId`	Only present if `isMultipart="true".` This string indicates the `messageId` for the original message that was split.	String

Reference Table

The reference tables below contain the same information as above, but in a quick-reference table form.

To send a message to a mobile device, you'll need to use the POST method with this API, which will allow you to define the destination of the message, the source, the body of the message, and other key details. Upon receiving the call, our system will respond with a unique messageID and a few other details.

All Vibes calls and responses are written in XML.

Remember that to make a call to any of Vibes' APIs, you'll need to include Authentication and all required headers.

Example of a Call

To start, here's an example of a call. The required elements are detailed below.

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>

Elements and Attributes of a Call

Required

mtMessage

This is the main wrapper for your submit request.

Attribute Name	Description	Data Type	Required?	Default
`submitterMessageId`	Use this attribute to define your own ID for a message for future reference purposes. The identifier must be 40 characters or less.	String	No
`splitLongMessage`	This flag determines whether any messages greater than 160 characters be split into multiple messages. For those carriers that support concatenated messages, the message may appear as a single message up to 900 characters. Read more about message splitting here.	Boolean	No	False

destination

This element defines the destination to deliver the outgoing message.

Attribute Name	Description	Data Type	Required?	Default
`carrier`	The carrier network the Mobile Phone is on. If it is not specified, the system will query for the correct carrier.	String	No
`address`	The mobile device number (MDN) to deliver the message to. This must be specified in e.164 international format with a leading +.	String	Yes

source

Attribute Name	Description	Data Type	Required?	Default
`address`	Your identifying short, long, or alpha code, which will appear to the receiver as the sender of the message. If you are using a long code, do not include the leading +.	String	Yes
`type`	The type of number of the sender. If sending from a short or long code, the value should be SC. If sending from an international alpha code, the value should be ANC.	String	No	SC

text

This element defines the text of the message you'd like to send. The message must be encoded in XML. If splitLongMessage is NOT set to True in mtMessage, then the message must be 160 characters or less.

Optional

Each of the following elements are optional.

receiptOption

This element indicates the receipt notifications that should be sent as a callback for this message.

Available values are as follows:

NONE - send no notifications.
ERROR - send only error notifications (includes error deliver receipts).
ALL - send all notifications (includes DLRs).
SMSC_ERROR - send only error notifications that come from the carrier (next Hop) upon send (does not include delivery receipts).
SMSC_ALL - send only notifications that from the carrier (next Hop) upon send (does not include delivery receipts).

Attribute Name	Description	Data Type	Required?	Default
`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 encoded in XML.	String	No

transaction

This element references the message (if any) that started this conversation. If this MT message is an alert, this element should be omitted.

Attribute Name	Description	Data Type	Required?	Default
`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	N/A

companyId

The Company ID this message is being sent for.

Response

mtMessageRsp is the main wrapper for a response.

Attribute Name	Description	Data Type	Required?
`messageId`	The Vibes identifier for the message submitted.	String	Yes
`submitterMessageId`	If `submitterMessageId` was set in your request, it may be repeated in the response.	String	No
`carrier`	The carrier code of the network the message receiver's 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`	If `splitLongMessage` is set to True on the request, this may be repeated in the response.	Boolean	No

Example success response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<mtMessageRsp submitterMessageId="AnyValue" messageId="e9efe523-aa57-4fdb-8f57-f15a4b06c91e" splitLongMessage="true"/>

Example failure response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<error code="1031" description="Unable to resolve Carrier for MDN: 5125551212, Reason Unsupported MDN: 15125551212" retriable="false"/>