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.
| Attribute | Description | Data Type |
|---|---|---|
messageId | A unique identifier for each message, provided by Vibes. | String |
submitterMessageId | If you defined your own message ID to identify the message when you sent your request, it will be repeated here. | String |
fwdToMessageId | If 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 |
fwdFromMessageId | If 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 |
receiptDate | Date 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.
| Attributes | Description |
|---|---|
description | This 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. |
errorCode | If the message fails, this element contains the error code that describes the specific failure reason. See HTTP Error and Status Codes for more info. |
internalErrorCode | If 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.
| Attribute | Description | Data Type |
|---|---|---|
isMultipart | If the original message was multipart, this will be set to true. | Boolean |
noOfParts | The total number of parts the original message got split into. | String |
partNumber | The numerical order of this message. For example, the first message sent will be 1, the second will be 2, and so on. | String |
originalMessageId | If 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
| Element | Attribute | Description | Data Type |
|---|---|---|---|
mtMessageResponse | Main wrapper element indicating that this is a mtMessage Response. | ||
messageId | A unique identifier for each message, provided by Vibes. | String | |
submitterMessageId | If you defined your own message ID to identify the message when you sent your request, it will be repeated here. | String | |
fwdToMessageId | If 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 | |
fwdFromMessageId | If 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 | |
receiptDate | Date the response was received in standard XML format. | String | |
type | The 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 | |
status | Element that has the status of the mtMessage. | ||
isError | Boolean on whether the status is an error. | Boolean | |
description | This 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 | |
errorCode | If 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 | |
internalErrorCode | If 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 | |
multipart | The 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. | ||
isMultipart | If the original message was multipart, this will be set to true. | Boolean | |
noOfParts | The total number of parts the original message got split into. | String | |
partNumber | The numerical order of this message. For example, the first message sent will be 1, the second will be 2, and so on. | String | |
originalMessageId | If 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 |