Event ID 32: Failed Message Webhook

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": "[phone]",
    "role": "enduser",
    "optStatus": true,
    "optStatusDetail": "OPTED_IN"
  },
  "primaryContact": {
    "id": "aa8ce494-af6e-4313-bd3b-82e3ba04dab9",
    "first": "James",
    "last": "Zimmerman",
    "email": "[e-mail]",
    "role": "operator"
  },
  "createTime": "2025-04-10T20:18:59.096Z",
  "creationSource": "PublicApi",
  "referenceId": "auto-nw-1323412345e3",
  "roleType": "claimant",
  "privacy": "public",
  "marleyNumber": "[phone]",
  "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. open close	enum	true	"state": "open"
caseType		The type of Hi Marley Case. case claim policy	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": "[phone]"
	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"
primaryContact	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"
	email	The email of the person assigned to the Hi Marley case.	string	false	"email": "[e-mail]"
	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. public private-redacted	enum	true	"privacy": "public"
marleyNumber		The assigned phone number from an organization pool used to conduct messaging for the current case.	string	true	"marleyNumber": "[phone]"
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. text image file	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. mobile marley	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. operator enduser	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 [e-mail] 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 [e-mail] 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.