Skip to main content

Message Send Failure

Overview

·Event key:
message.send_failure

This event enables real-time tracking of message delivery failures, including error details and failure reasons. Use it to implement retry logic, alert support teams, update communication logs, trigger alternative delivery methods, and maintain accurate delivery status tracking for troubleshooting and compliance.

When This Event Triggers

This event fires when an outbound message (SMS or email) sent through the Partner API fails to be delivered. This event specifically tracks messages sent via the "Household Communication" feature, which allows external systems to send messages to residents through Funnel's communication platform. The event fires in the following scenario:

  • SMS Delivery Failed — When a text message sent via the Partner API fails to be delivered, as reported by Twilio (the SMS provider). The system receives a status callback from Twilio indicating the message could not be delivered to the recipient's phone. Common reasons for failure include invalid phone numbers, carrier blocking, the recipient's phone being unreachable, or the message being flagged as spam.

Important notes about this event:

  • This event only fires for messages created through the Partner API's Household Communication endpoint. Messages sent directly by leasing agents through the CRM interface do not trigger this webhook.
  • The event includes an error message that describes why the delivery failed. For SMS failures, this includes the specific Twilio error code and a human-readable description of the problem.
  • Some error codes are intentionally ignored and won't trigger this event (such as certain transient errors that don't indicate a real delivery problem).

The event payload includes:

  • The internal message ID
  • The renter (client) ID who was supposed to receive the message
  • The renter person ID (the specific person on the client record)
  • The PMS identifier for the renter (if available)
  • Either the phone number (for SMS) or email address (for email) that was targeted
  • An error message describing why the delivery failed

This event is useful for external systems that send messages through the Partner API and need to be notified when their messages fail to reach residents, allowing them to take corrective action such as updating contact information or trying an alternative communication method.

Event Payload

Example payloadJSON200 · application/json
{
"id": "8cc87045-bbbb-4a16-a882-454044e6762a",
"event": "message.send_failure",
"timestamp": "2024-10-09T13:49:31.658518+00:00",
"data": {
  "message_id": 12345,
  "renter_id": 67890,
  "renter_person_id": 54321,
  "pms_identifier": "t1234",
  "phone": "+1234567890",
  "email": "renter@example.com",
  "error_message": "Invalid phone number format"
}
}