If you’d like to receive more information about your submitted message, you may want to opt into receiving a callback from Vibes. A callback is essentially a Vibes-initiated request that is triggered after you submit an outgoing message. It can be requested by adding certain elements to your send a message request.

Prior to requesting a callback, you will need to set up your endpoint. For instructions on endpoint set up, please go here

Outgoing Message Carrier Responses Callback

This callback will attempt to deliver a request to your endpoint that includes the carrier responses that were received after a previous outgoing message. To receive this callback, you will need include the receiptOption tag on the original submission of the outgoing message, and make sure it is set to true.

🚧

Response required

Your endpoint should properly store and record the response and then return a 200 response to acknowledge receipt. Read more about endpoint specifications.

📘

Authorization note

This callback does not support Basic Authorization.

Request

This is an example of the request that will come from Vibes and be delivered to your endpoint. The relevant elements are explained below.

POST
 
<?xml version="1.0" encoding="UTF-8"?>
<mtMessageResponse messageId="865cd3d1-bea6-4a6f-8bac-bae483248a27" 
    submitterMessageId="239487234987234" 
    receiptDate="2011-04-19T15:10:08.320-05:00"> 
    <multipart isMultipart="true" originalMessageId="865cd3d1-bea6-4a6f-8bac-bae483248a27" noOfParts="2" partNumber="1" /> 
    <type>System|Carrier|Handset</type>
    <status isError="true|false">
        <description>Description of status</description>
        <errorCode>100</errorCode>
        <internalErrorCode>255</internalErrorCode>
    </status>
</mtMessageResponse>

Elements of a Request

mtMessageResponse

This is the main wrapper element for this request.

AttributeDescriptionData Type
messageIdA unique identifier for each message, provided by Vibes.String
submitterMessageIdIf you defined your own message ID to identify the message when you sent your request, it will be repeated here.String
fwdToMessageIdIf the original send utilized alternate message delivery (available for v3.1+ only), this attribute may appear in your response. The value will be the unique message ID of the alternate message that was sent when the original message failed.String
fwdFromMessageIdIf your send utilized alternate message delivery (available for v3.1+ only) and the message you requested information on was not the original message, this attribute may appear in your response. The value will be the unique message ID of the original message that was attempted and failed.String
receiptDateDate the response was received in standard XML format.String

type

Delivery receipts are sent at each step of the process. The type element indicates which processing stage generated the delivery receipt. The possible values are as follows:

  • System: The receipt was generated while the message was being routed to the carrier by the Message API system.
  • Carrier: The receipt was generated while submitting the message to the carrier.
  • Handset: The receipt was generated while submitting the message to the handset.

📘

Delivery receipt delays

Carriers make their best efforts to return delivery receipts in a timely manner, but delays may occur. Learn more here.

status

This element contains the attributes that indicates if there was an error when trying to deliver the message. If isError="false", then no error was returned. If isError="true", then an error was returned, and the following attributes and sub-elements maybe displayed.

AttributesDescription
descriptionThis element provides a description of the error if an error is present. If no error is present, it will read MtMessage successfully delivered to Carrier.
errorCodeIf the message fails, this element contains the error code that describes the specific failure reason.

See HTTP Error and Status Codes for more info.
internalErrorCodeIf the message fails due to a Vibes error, this element contains the exact same value as the ERRORCODE element.

If the message fails due to a carrier error, this element contains the exact error code returned by the carrier to Vibes for further research. This value can be communicated to Vibes support for more information.

multipart

The wrapper element that has all information about a message that was split into multiple messages due to length. This element is present only if the request had splitlongmessage set to True, and the length was over 160 characters.

AttributeDescriptionData Type
isMultipartIf the original message was multipart, this will be set to true.Boolean
noOfPartsThe total number of parts the original message got split into.String
partNumberThe numerical order of this message. For example, the first message sent will be 1, the second will be 2, and so on.String
originalMessageIdIf the request’s message was split into multiple parts and this is not the original message, this will display the messageID of the first part of the message.String

Reference Table

ElementAttributeDescriptionData Type
mtMessageResponseMain wrapper element indicating that this is a mtMessage Response.
messageIdA unique identifier for each message, provided by Vibes.String
submitterMessageIdIf you defined your own message ID to identify the message when you sent your request, it will be repeated here.String
fwdToMessageIdIf the original send utilized alternate message delivery (available for v3.1+ only), this attribute may appear in your response. The value will be the unique message ID of the alternate message that was sent when the original message failed.String
fwdFromMessageIdIf your send utilized alternate message delivery (available for v3.1+ only) and the message you requested information on was not the original message, this attribute may appear in your response. The value will be the unique message ID of the original message that was attempted and failed.String
receiptDateDate the response was received in standard XML format.String
typeThe processing stage at which the response was generated. The possible value are as follows:

- System: While the mtMessage was being routed to the carrier by the Message API system.
- Carrier: While submitting the mtMessage to the carrier.
- Handset: While submitting the mtMessage to the handset.
String
statusElement that has the status of the mtMessage.
isErrorBoolean on whether the status is an error.Boolean
descriptionThis element provides a description of the error if an error is present. If no error is present, it will read MtMessage successfully delivered to Carrier.String
errorCodeIf the message fails, this element contains the error code that describes the specific failure reason.

See HTTP Error and Status Codes for more info.
Numeric
internalErrorCodeIf the message fails due to a Vibes error, this element contains the exact same value as the errorCode element.

If the message fails due to a carrier error, this element contains the exact error code returned by the carrier to Vibes for further research. This value can be communicated to Vibes support for more information.
Numeric
multipartThe wrapper element that has all information about multipart message (a long message split into multiple parts).

This element is present if the request had SplitLongMessage set to True, and the original Long message got split into multiple parts.
isMultipartIf the original message was multipart, this will be set to true.Boolean
noOfPartsThe total number of parts the original message got split into.String
partNumberThe numerical order of this message. For example, the first message sent will be 1, the second will be 2, and so on.String
originalMessageIdIf the request’s message was split into multiple parts and this is not the original message, this will display the messageID of the first part of the message.String