Description
The Failed Message Webhook notifies carriers when an SMS text message to a policyholder fails delivery in an external system integrated with Hi Marley. The payload includes message-specific metadata to identify the failed message, enabling adjusters working in an external claims application to determine if and when a resend is needed.
Note: Hi Marley users should not expect to see delivery failures often. Our platform has been built to ensure that our users experience highly reliable messaging experience with a 99.5% successful delivery rate. The likely cause of failed messages are related to the end-user device or telecom service issues.
Tale of Contents:
- Registering Webhook
- Request Payloads
- Example Payload Triggered by Failed Message
- Payload Fields Breakdown
- Error Code Details:
Registering Webhook
Use the following payloads to subscribe to send case data on case closure webhook using the POST /webhooks/register endpoint
Request Payloads
Note: The Headers array is a optional set of values that can be used to attach specific static headers to each webhook response for any purpose (e.g indicating the type of event, carrier authentication of payload with a token)
{
"EVENT_ID": 32,
"HTTP_POST_ADDRESS": "https://mywebaddress.com/messages",
"HEADERS": {
"key": "value",
"key1": "value1"
}
}
Example Payload Triggered by Failed Message
Headers
content-type application/json
accept application/json
requestid <auto-gen id>
Eventid 32
Eventname MESSAGE_STATUS_UPDATED
<other subscribed headers>
{
"caseData": {
"id": "f7766017-7aba-4f15-9d0c-dcf9bd029c75",
"archived": false,
"claimNumber": "auto-nw-1323412345e3",
"dateOfLoss": "2023-04-01T08:33:39.048Z",
"policyNumber": "Vc93rw213872",
"brand": "Lovable Insurance"
},
"state": "open",
"caseType": "claim",
"customer": {
"id": "c5f5a26e-f3e4-4951-b9e0-a1c1347b220e",
"first": "JeanLuc",
"last": "Picard",
"email": "",
"mobile": "+17745715015",
"role": "enduser",
"optStatus": true,
"optStatusDetail": "OPTED_IN"
},
"primaryContact": {
"id": "aa8ce494-af6e-4313-bd3b-82e3ba04dab9",
"first": "James",
"last": "Zimmerman",
"email": "james.zimmerman@himarley.com",
"role": "operator"
},
"createTime": "2025-04-10T20:18:59.096Z",
"creationSource": "PublicApi",
"referenceId": "auto-nw-1323412345e3",
"roleType": "claimant",
"privacy": "public",
"marleyNumber": "+17622165564",
"languagePreference": "pt",
"secondaryOperators": [],
"messages": [
{
"id": "d8de423f-b75a-4645-a854-57262d368b61",
"type": "text",
"formatting": "standard",
"data": "This is just a test!",
"channelSource": "marley",
"author": {
"_id": "aa8ce494-af6e-4313-bd3b-82e3ba04dab9",
"profile": {
"firstName": "James",
"lastName": "Zimmerman"
},
"role": "operator"
},
"messageClassifications": {
"isRedacted": false
},
"createdAt": "2025-10-03T17:02:34.353Z",
"dateFormatted": "10-03-2025",
"timeFormatted": "1:02:34 PM EDT",
"channel": "TEXT",
"deliveryStatus": "failed",
"errorCode": 21617
}
]
}
Payload Fields Breakdown
Property |
Elements |
Description |
Type |
Required |
Example |
caseData |
id |
The case identifier for the Hi Marley Case. |
string |
true |
"id": "364ef9bb-fae5-4e2a-a746-cdca465a9c00" |
archived |
Indicates if case is closed. |
string |
true |
"archived": false |
|
claimNumber |
Fields associated to claim/policy record. |
string |
true (only claim caseType) |
"claimNumber": "0002383632" |
|
dateOfLoss |
string |
false |
"dateOfLoss": "2022-05-25T16:00:00.000Z" |
||
policyNumber |
string |
true (only policy caseType) |
"policyNumber": "Vc93rw213872" |
||
brand |
Subsidiary/Underwriter associated with case |
string |
true (only if brands are in-use) |
"brand": "TestBrand1" |
|
state |
|
The current status of the case state.
|
enum |
true |
"state": "open" |
caseType |
|
The type of Hi Marley Case.
|
enum |
true |
"caseType": "case" |
customer |
id |
The identifier generated and assigned to the customer. |
string |
true |
"id": "75f2b888-dca1-4596-9cad-325d1f8a6e54"
|
first |
The customers given name. |
string |
true |
"first": "Tom"
|
|
last |
The customers surname. |
string |
true |
"last": "Riddle"
|
|
mobile |
The customers mobile number. |
string |
true |
"mobile": "+14345321629" |
|
role |
The role of the customer. |
enum |
true |
"role": "enduer" |
|
optStatus |
The contact opt status. |
boolean |
true |
"optStatus: true |
|
OptStatusDetial |
Additional opt status details. |
enum |
true |
"optStatus": "OPTED_IN" |
|
|
id |
The identifier of the person assigned to the Hi Marley case. |
string |
false |
"id": "18576b89-cd47-4dae-82d0-35ac08ec6387" |
first |
The first name of the person assigned to the Hi Marley case. |
string |
false |
"first": "Joe" |
|
last |
The last name of the person assigned to the Hi Marley case. |
string |
false |
"last": "Loop" |
|
The email of the person assigned to the Hi Marley case. |
string |
false |
"email": "joe.loop@insuranceco.com" |
||
role |
The role of the person assigned to the Hi Marley case. |
string |
false |
"role": "operator" |
|
createTime |
|
The time of the case creation. |
smalldatetime |
true |
"createTime": "2022-08-15T20:26:25.076Z"
|
creationSource |
|
Indicates where HM Case was created (webApp, PublicAPI) |
enum |
true |
"creationSource": "PublicApi" |
referenceId |
|
The case reference identifier for the Hi Marley Case. |
string |
true |
"referenceId": "114aeb44-ea25-4643-a950-f5363865076b"
|
roleType |
|
The role in the claim process. |
enum |
false |
"roleType": "claimant" |
privacy |
|
The case privacy status.
|
enum |
true |
"privacy": "public" |
marleyNumber |
|
The assigned phone number from an organization pool used to conduct messaging for the current case. |
string |
true |
"marleyNumber": "+15047663063" |
languagePreference |
|
The preferred language for the current Hi Marley case. |
enum |
true |
"languagePreference": "en" |
secondaryOperators |
|
If case includes a secondaryOperator, includes operator profile |
array |
false |
"secondaryOperators": [] |
messages |
id |
Message ID of the flagged message |
string |
true |
"id": "33184205-24e5-4995-b3d7-601118fbd8ea" |
type |
Type of message that was flagged. In most cases text will be flagged for needs attention.
|
enum |
true |
"type": "text" |
|
data |
The text/string of the message that Needs Attention. |
string |
true |
"data": "i want to talk to my lawyer" |
|
channelSource |
The source of the inbound message.
|
enum |
true |
"channelSource": "mobile" |
|
author.id |
The identifier of the message author. |
string |
true |
"_id": "75f2b888-dca1-4596-9cad-325d1f8a6e54" |
|
author.role |
The role of the message author. Only endusers (customers) messages are flagged.
|
enum |
true |
"role": "enduser" |
|
author.profile.firstName |
The authors first name. |
string |
true |
"firstName": "Tom" |
|
author.profile.lastName |
The authors surname/last name. |
string |
true |
"lastName": "Riddle" |
|
createdAt |
|
The date and time of the message creation. |
smalldatetime |
true |
"createdAt": "2022-08-25T14:19:17.110Z" |
dateFormatted |
|
The formatted date of the message creation. |
date |
true |
"dateFormatted": "08-25-2022" |
timeFormatted |
|
The formatted time of the message creation. |
time |
true |
"timeFormatted": "10:19:17 AM EDT" |
channel |
|
The communication channel. |
enum |
true |
"channel": "TEXT" |
deliveryStatus |
|
The status of SMS delivery. |
enum |
true |
"deliveryStatus": "failed" |
errorCode |
|
Corresponding Error Code provided by our SMS provider. |
string |
true |
"errorCode": 21617 |
Error Code Details:
The "errorCode" field contains a numeric identifier that Hi Marley Support can reference when troubleshooting with our SMS provider. Many error codes include supplementary information that explains why an SMS was not delivered and may indicate recommended next steps. If additional clarification is needed on a particular error, please contact support@himarley.com for assistance.
Error Groupings |
Related Codes |
Additional Details |
Next Best Action |
A2P 10DLC Errors |
30033 30034 30035 30023 30022 |
These errors are related to issues with the registered mobile number that Hi Marley operates on behalf of our insurance carrier customers. This will be very unlikely to happen in a production scenario but we will be ready to resolve immediately as it occurs. |
Any errors referencing this should be brought to support@himarley.com immediately. |
Content Size too large |
30019 21617 |
This will generally occur if the message exceeds 1400 characters. While we provide a character count, translated messages may exceed that limit based on the language selected especially if it has a non-latin character set (like Chinese). |
Manually retry with the original message broken into 2 or 3 parts. |
Destination handset issues |
30005 30003 30006 |
Causes include a range of issues from temporary ones like signal strength to permanent issues like number is no longer active. |
Retry sending the message. If the error continues the contact may no longer be reachable at that mobile number. We recommend reaching out through other channels to update their mobile number. |
Telecom Message Filtering |
30007 |
Telecom Carriers will filter messages that seem to be spam. In the case of Hi Marley, when this occurs it is likely an error on the Telecoms end and might not have a clear pattern or reason. Our monitoring will alert us to this error immediately and we will look to get it corrected. |
You can attempt messaging after some time but please feel free to contact us or your internal support about this issue and we will happily provide updates. |
Comments
0 comments
Please sign in to leave a comment.