API Reference

Subscription Callbacks

These callbacks are triggered in response to changes in data associated with the Subscription API. To receive callbacks, please make sure your endpoint is compatible with our endpoint specifications.

🚧

Before you register...

Set up your endpoint before sending any callback configurations. Do not use a "fake" URL to test the configuration, as this will result in errors.

Available Callbacks

MDN formats in callback events are determined by the API version used when creating and altering the callbacks. If Version 2 is used, MDNs will be represented in the E.164 international format. Otherwise, MDNs will be represented without a country code.

Subscription Added Callback

This callback is triggered when a person has been added to a subscription list.

Callback configuration

When registering for this callback, your request body should look something like the below example.:

{
   "callback_type":"subscription_added",
   "subscription_added":{
         "list_id":"YOUR_SUBSCRIPTION_LIST_ID"
  },
  "destination":{
     "url":"YOUR_DESTINATION_URL_W_HTTPS", /*Do not use a "fake" URL (such as google.com).*/
     "method":"POST",
     "content_type":"application/json"
  }
}

Callback body

The callback body contains the metadata about the subscription that was added.

{
   "event_id":"AB234SDFD234",
   "callback_type":"subscription_added",
   "event_type":"subscription_added", //deprecated
   "event_date":"2017-03-15T15:42:23Z",
   "subscription":{
      "person":{
         "id":"ABC123",
         "external_id":"ex1234",
         "external_person_id":"ex1234",
         "person_key":"c5235a1-e243-42z7-979c-7f6234kl21b60",
         "url":"/companies/:company_key/mobiledb/persons/ABC123",
         "mobile_phone":{
           "mdn":"+1999999999"
         }
      },
      "subscription_list":{
         "id":"1234",
         "url":"/companies/:company_key/mobiledb/subscription_lists/1234"
      },
      "opt_in_date":"2017-01-15T15:34:52Z"
   }
}

Subscription Removed Callback

This callback is triggered whenever a subscription has been removed from a person.

Callback configuration

When registering for this callback, your request body should look something like the below example.

{
   "callback_type":"subscription_removed",
   "subscription_removed":{
         "list_id":"YOUR_SUBSCRIPTION_LIST_ID"
  },
  "destination":{
     "url":"YOUR_DESTINATION_URL_W_HTTPS", /*Do not use a "fake" URL (such as google.com).*/
     "method":"POST",
     "content_type":"application/json"
  }
}

Callback body

The callback body contains data about the subscription that was removed and an opt_out_reason.

{
   "event_id":"AB234SDFD234",
   "callback_type":"subscription_removed",
   "event_type":"subscription_removed", //deprecated
   "event_date":"2017-03-15T15:42:23Z",
   "subscription":{
      "person":{
         "id":"ABC123",
         "external_id":"ex1234",
         "external_person_id":"ex1234",
         "person_key":"c5235a1-e243-42z7-979c-7f6234kl21b60",
         "url":"/companies/:company_key/mobiledb/persons/ABC123",
         "mobile_phone":{
           "mdn":"+1999999999"
         }
      },
      "subscription_list":{
         "id":"1234",
         "url":"/companies/:company_key/mobiledb/subscription_lists/1234"
      },
      "opt_in_date":"2017-01-15T15:34:52Z",
      "opt_out_date":"2017-02-18T15:34:52+0000",
      "opt_out_reason":"user_opt_out"
   }
}

Opt_out_reason values

Opt-out reasonDescription
disconnectThe device associated with the subscription was disconnected
list_archivedThe list associated with the subscription was archived
bulk_opt_outThe subscriber was included in a bulk opt-out file
failed_at_carrierAn error from the carrier was received when attempting to deliver an SMS to the device
obsolete_carrierDevice was on a carrier that is no longer supported by Vibes
platform_opt_outThe subscription was removed manually using the Vibes Platform
keyword_opt_outThe subscription was removed after receiving a STOP keyword from the device
api_opt_outThe subscription was removed via the Subscription API
user_opt_outDefault when no other reason is specified.
button_opt_outOpted out via the "subscriptions" tab in the Campaign Manager UI

Vibes may add additional opt_out_reason options in the future.

Additional Resources