Skip to end of metadata
Go to start of metadata

Last updated: Monday, November 28, 2022

Note

This feature is currently in progress with additional functionality coming soon. Reach out to your account rep to coordinate an implementation plan.


An Event-Triggered Callback can be returned after an Event is sent to Vibes. In order to determine whether or not your event succeeded or failed, you will need to understand the components of an Event Processed Callback and register to receive those callbacks.

Note: Events are primarily used for API-Triggered Messages. For more information on Events and their uses, please see our Event-Triggered Messages integration scenario.

Callback Flow

Routing Success

If the Event that was received and the action is processing, you will see a success callback such as the one below.

{
  "event_id":"3a083a69-2064-430a-8ab6-72f163692ed2",
  "callback_type":"event_processed",
  "event_date":"2022-08-15T20:02:36Z",
  "event_processed":{
     "event_id":"3b0e5871-d8b5-4393-b275-07ca0541c8de",
     "event_type":"day_of_delivery",
     "event_data":{
        "first_name":"Bob",
        "external_person_id":"abcd12345",
        "delivery_time":"5:00 PM",
        "order_url":"https://example.com/orders/12345"
     },
     "debug_data":{
        "field":"CUST_SYSTEM"
     },
     "action":{
        "type":"routing",
        "status":"processing",
        "status_reason":"accepted_by_event_triggered_message",
        "resource_url": "/companies/:company_key/mobiledb/event_triggered_messages/:event_triggered_message_id"
     }
  }
}

Potential Routing Failures

No Route Rules

This indicates that the system was not able to find an action in the system like an Event-Triggered Message to send the received Event to.

{
  "event_id":"fddbf770-f987-4928-91be-6b19c994562f",
  "callback_type":"event_processed",
  "event_date":"2022-08-15T20:38:42Z",
  "event_processed":{
     "event_id":"5e9cabf7-228c-4f6e-944e-57b7728bc899",
     "event_type":"day_of_delivery",
     "event_data":{
        "first_name":"Bob",
        "external_person_id":"abcd12345",
        "delivery_time":"5:00 PM",
        "order_url":"https://example.com/orders/12345"
     },
     "debug_data":{
        "field":"CUST_SYSTEM"
     },
     "action":{
        "type":"routing",
        "status":"failed",
        "status_reason":"event_routing_failed",
        "failure":{
           "reason":"no_route_rules_found_for_event"
        }
     }
  }
}

Person Doesn’t Belong To Associated Subscription List

This failure occurs if the person that is referenced in the Event doesn’t belong to the subscription list that is associated to the Event-Triggered Message.

{
  "event_id":"4a6dcfcf-16be-474d-b87f-ee64a08f6dab",
  "callback_type":"event_processed",
  "event_date":"2022-08-15T20:20:02Z",
  "event_processed":{
     "event_id":"3b0e5871-d8b5-4393-b275-07ca0541c8de",
     "event_type":"day_of_delivery",
     "event_data":{
        "first_name":"Bob",
        "external_person_id":"abcd12345",
        "delivery_time":"5:00 PM",
        "order_url":"https://example.com/orders/12345"
     },
     "debug_data":{
        "field":"CUST_SYSTEM"
     },
     "action":{
        "type":"routing",
        "status":"failed",
        "status_reason":"event_routing_failed",
        "failure":{
           "reason":"no_routes_accepted_event",
           "errors":[
              {
                 "error":"Event-Triggered Message subscription requirements are not met",
                 "resource_url": "/companies/:company_key/mobiledb/event_triggered_messages/:event_triggered_message_id"
              }
           ]
        }
     }
  }
}


Person Not Found

This failure occurs when the person that is referenced in the Event is not found.

{
  "event_id":"4a6dcfcf-16be-474d-b87f-ee64a08f6dab",
  "callback_type":"event_processed",
  "event_date":"2022-08-15T20:20:02Z",
  "event_processed":{
     "event_id":"3b0e5871-d8b5-4393-b275-07ca0541c8de",
     "event_type":"day_of_delivery",
     "event_data":{
        "first_name":"Bob",
        "external_person_id":"abcd12345",
        "delivery_time":"5:00 PM",
        "order_url":"https://example.com/orders/12345"
     },
     "debug_data":{
        "field":"CUST_SYSTEM"
     },
     "action":{
        "type":"routing",
        "status":"failed",
        "status_reason":"event_routing_failed",
        "failure":{
           "reason":"no_routes_accepted_event",
           "errors":[
              {
                 "error":"Person is not found",
                 "resource_url": "/companies/:company_key/mobiledb/event_triggered_messages/:event_triggered_message_id"
              }
           ]
        }
     }
  }
}

Carrier Not Supported

This failure occurs when the MDN referenced in the Event cannot be reached. This may be because the number is a landline, or it is on an unsupported carrier. 

{
  "event_id":"4a6dcfcf-16be-474d-b87f-ee64a08f6dab",
  "callback_type":"event_processed",
  "event_date":"2022-08-15T20:20:02Z",
  "event_processed":{
     "event_id":"3b0e5871-d8b5-4393-b275-07ca0541c8de",
     "event_type":"et127_no_incentive_codes",
     "event_data":{
        "mdn": "+18609740638",
        "something": "some value"
     },
     "action":{
        "type":"send_message",
        "status":"failed",
        "status_reason":"event_message_action_failed",
        "failure":{
           "reason":"PermanentLookupFailureError",
           "errors":[
              {
                 "error":"Carrier Lookup for +18609740638 failed with error null is not a mobile phone number or its carrier [null] is currently not supported",
                 "resource_url": "/companies/zY5VnE7r/mobiledb/event_triggered_messages/276"
              }
           ]
 
        }
     }
  }
}

Potential Processing Failures

No Incentive Codes

If the destination Event-Triggered Message is using an Incentive Pool and there are no incentive codes remaining to be used, you will receive this failure message.

{
  "event_id":"4a6dcfcf-16be-474d-b87f-ee64a08f6dab",
  "callback_type":"event_processed",
  "event_date":"2022-08-15T20:20:02Z",
  "event_processed":{
     "event_id":"3b0e5871-d8b5-4393-b275-07ca0541c8de",
     "event_type":"day_of_delivery",
     "event_data":{
        "first_name":"Bob",
        "external_person_id":"abcd12345",
        "delivery_time":"5:00 PM",
        "order_url":"https://example.com/orders/12345"
     },
     "debug_data":{
        "field":"CUST_SYSTEM"
     },
     "action":{
        "type":"send_message",
        "status":"failed",
        "status_reason":"event_message_action_failed",
        "failure":{
           "reason":"NoAvailableCodes",
           "errors":[
              {
                 "error":"The referenced incentive pool is out of codes.",
                 "resource_url": "/companies/:company_key/mobiledb/event_triggered_messages/:event_triggered_message_id"
              }
           ]

        }
     }
  }
}

Unexpected Error

When some unexpected error has occurred during the Event-Triggered Message, you may receive this code.

{
  "event_id":"4a6dcfcf-16be-474d-b87f-ee64a08f6dab",
  "callback_type":"event_processed",
  "event_date":"2022-08-15T20:20:02Z",
  "event_processed":{
     "event_id":"3b0e5871-d8b5-4393-b275-07ca0541c8de",
     "event_type":"day_of_delivery",
     "event_data":{
        "first_name":"Bob",
        "external_person_id":"abcd12345",
        "delivery_time":"5:00 PM",
        "order_url":"https://example.com/orders/12345"
     },
     "debug_data":{
        "field":"CUST_SYSTEM"
     },
     "action":{
        "type":"send_message",
        "status":"failed",
        "status_reason":"UnexpectedError",
        "failure":{
           "reason":"UnexpectedError",
           "errors":[
              {
                 "error":"Reason for unexpected error.",
                 "resource_url": "/companies/:company_key/mobiledb/event_triggered_messages/:event_triggered_message_id"
              }
           ]

        }
     }
  }
}

Potential Processing Callbacks

SMS Message Queued To Be Sent To Carrier

You will receive this callback when an SMS message was successfully generated for an Event-Triggered Message and the message is queued to be sent to the carrier.

Note: The event_data and debug_data from the original Event will currently not be returned in the callback. This information is being worked on being provided in a future update.

{
   "event_id":"4a6dcfcf-16be-474d-b87f-ee64a08f6dab",
   "callback_type":"event_processed",
   "event_type":"event_processed",
   "event_date":"2022-08-15T20:20:02Z",
   "event_processed":{
      "event_id":"4810008e-800d-460c-94f2-a5d60a70f058",
      "event_type":"day_of_delivery",
      "event_data":{
         "first_name":"Bob",
         "external_person_id":"abcd12345",
         "delivery_time":"5:00 PM",
         "order_url":"https://example.com/orders/12345"
      },
      "debug_data":{
         "field":"CUST_SYSTEM"
      },
      "action":{
         "type":"send_message",
         "status":"processing",
         "status_reason":"queued",
         "message_type":"sms",
         "sms":{
            "source":{
               "resource_url":"/companies/:company_key/mobiledb/event_triggered_messages/:event_triggered_message_id"
            },
            "person":{
               "person_key":"w2e2127r-w413-841w-8t40-480b85dc6t3e",
               "resource_url":"/companies/:company_key/mobiledb/persons/w2e2127r-w413-841w-8t40-480b85dc6t3e"
            }
         }
      }
   }
}

Elements & Attributes of a Call

FieldProvided OnDescriptionValues
event_id
Success/FailureUnique Event ID for the callback event.
event_date
Success/FailureWhen the event occurred.

ISO-8601


YYYY-MM-DDTHH:MM:SSZ
callback_type
Success/Failure

The callback type that was registered for.

Will always be

 event_processed
event_type
Success/Failure

The event_type that was sent in the original Event.


event_date
Success/Failure

The event_data that was sent in the original Event.


debug_data
Success/FailureThe debug_data that was sent in the original Event.
action
Success/Failure

An object describing the details of the success or failure of the actions that were taken during the processing of the Event that was sent in to Public API.


action.type
Success/Failure


routing

send_message
action.status
Success/Failure

Indication whether the action related to the Event is in a processing state, failed or succeeded.

success

failed

processing
action.status_reason
Success/FailureIndicates the reason for the action status.
action.message_type
Processing/FailureIndication of what type of message is being referenced.
sms
action.sms.source.resource_url
Processing/Failure (SMS)The path to the resource that generated the message.
action.sms.person.person_key
Processing/Failure (SMS)The person key identifier for the person that was associated to the message that was generated.
action.sms.person.resource_url
Processing/Failure (SMS)The path to the person resource that was associated to the message that was generated.
failure
Failure

If a failure has occurred, this object will containing failure information for the action being described, including reason and error(s).


Additional Resources

  • No labels