Custom Call Webhooks
Introduction
Marketing Edge Custom Webhooks build upon the standard call webhook functionality by allowing for the payload of the webhook to be defined according to the needs of the client or external system rather than requiring that a system accept the default webhook payload for calls.
Custom Webhooks allow you to register endpoints to receive HTTP requests with Call Data that has been defined in the webhook template. You can create new webhook template and webhook configuration through configuring them within the Marketing Edge portal. Note that this requires Administrator access.
Custom Webhook Template Configuration
Creating a webhook template will consist of assigning a unique Name, that will be referenced when associating the template to a webhook configuration, selecting a content type and specifying the message body. When specifying the message body, it is expected that the format will match the selected content type, but there is also a handy verification button that will ensure your payload is properly formatted.
Substitution tokens will be used to specify which Marketing Edge parameters will populate the parameters of the message body with data when sending the webhook, and a searchable list of all possible parameters will be displayed for reference purposes. See the Appendix for more details on the Marketing Edge parameters that can be assigned to a Custom Webhook.
Custom Webhook Configuration
You can configure webhooks within the client account under the “Settings” -> “Webhooks” menu. You can configure a callback URL that we will send an HTTP POST request to after each call is completed. Additionally, any time a call object is modified within the call log, we will send an HTTP POST request to the given URL as well. This allows you to avoid polling our API endpoints for updates to inbound calls.
Adding a new or editing an existing webhook will present the user with the webhook configuration listing all available Custom Webhook Templates. Public and Private Keys for verifying messages are available as with standard webhooks, and there is also the option of specifying basic authentication credentials that will be passed with every webhook message posted for this webhook configuration
Webhook configurations using Custom Webhook Templates can be configured to be triggers for Call Start, Call End and Call Processed events and the corresponding messages will be sent for ALL calls for ALL numbers within the organization. If the desired behaviour is to only send messages for calls to a subset of the numbers within an organization webhook filters can also be specified for the configured to ensure that messages will only be sent when the configured criteria is satisfied.
Substitution Parameters
When creating a custom webhook template it is essential to understand how to leverage substitution parameters to ensure that the webhook payload is populates with the correct data. See below for details on all of the possible substitution parameters that can be used in defining a custom webhook
| API Parameter | Substitution Parameter | Description |
|---|---|---|
| id | ## call_id## | Unique ID of the phone call |
| call_type_id | ## call_type_id## | Id of call type |
| call_type_id | ## call_type## | Call type name/label |
| number_id | ## number_id## | Id of the tracking number |
| group_id | ## group_id## | Group the call is associated with |
| group_name | ## group_name## | Name of the Group that the call is associated with |
| time_zone_id | ## time_zone_id## | Id of the Time Zone assigned to the Group and in which the call took place |
| time_zone_name | ## time_zone_name## | Name of the Time Zone assigned to the Group and in which the call took place |
| group_owner_id | ## group_owner_id## | Id of group owner for the Group |
| study_name | ## study_name## | Name assigned to the Tacking Number |
| group_owner_name | ## group_owner_name## | Name of the Group Owner associated to the Group |
| billing_group_id | ## billing_group_id## | Id of Billing Group associated to theGroup |
| billing_group_name | ## billing_group_name## | Name of Billing Group associated to theGroup |
| number_pool_id | ## number_pool_id## | Id of the pool of tracking numbers |
| caller_identity | ## caller_identity## | Unique identity value for the caller |
| organization_id | ## organization_id## | global organization identifier of the call |
| answer_status_id | ## call_answer_status_id## | Id of answer status |
| answer_status | ## call_answer_status## | Answer status of the phone call |
| ring_duration | ## call_ring_duration## | Duration in seconds for how long a phone call was ringing before being answered |
| call_duration | ## call_duration## | Duration in seconds of how long the phone calls lasted |
| registered_DNC | ## caller_registered_DNC## | Flag indicating if the caller is on the Do Not Call list |
| tracking_number | ## tracking_number## | Tracking Number that was called |
| caller_number | ## caller_number## | Phone Number of the caller |
| termination_number | ## termination_number## | Phone Number that the call was forwarded |
| caller_details -> caller_type | ## caller_type## | Defines the type of phone number the call came from |
| caller_details -> caller_name | ## caller_name## | Name of the caller |
| caller_details -> caller_address | ## caller_address## | Street address of the caller |
| caller_details -> caller_city | ## caller_city## | City of the caller |
| caller_details -> caller_state | ## caller_state## | State/Province of the caller |
| caller_details -> caller_zip_code | ## caller_zip_code## | ZIP Code/Postal Code of the caller |
| caller_details -> caller_country | ## caller_country## | Two letter country code of the caller |
| caller_details -> caller_latitude | ## caller_latitude## | Latitude of the caller as defined by their Area Code (NPA) and Exchange (NXX) |
| caller_details -> caller_longitude | ## caller_longitude## | Longitude of the caller as defined by their Area Code (NPA) and Exchange (NXX) |
| richdata -> age | ## caller_age## | Age of the caller |
| richdata -> gender | ## caller_gender## | Gender of the caller |
| richdata -> lengthOfResidence | ## caller_lengthOfResidence## | Years at current residence |
| richdata -> income | ## caller_income## | Estimated income of the caller |
| richdata -> married | ## caller_married## | Indicates the marital status of the caller |
| richdata -> dateOfBirth | ## caller_dateOfBirth## | Birth year and month of the caller |
| richdata -> education | ## caller_education## | Highest level of education completed by the caller |
| richdata -> homeOwner | ## caller_homeOwner## | Indicates whether the caller is a homeowner or a renter |
| richdata -> mobileHome | ## caller_mobileHome## | Indicates whether the caller's home is classified as a mobile home |
| richdata -> poolOwner | ## caller_poolOwner## | Indicates whether the caller has a pool at their home |
| richdata -> firePlace | ## caller_firePlace## | Indicates whether the caller has a fire place in their home |
| richdata -> singleParent | ## caller_singleParent## | Indicates whether the caller is a single parent |
| richdata -> hhSenior | ## caller_hhSenior## | Indicates whether there is a senior living at the caller address |
| richdata -> creditCard | ## caller_creditCard## | Indicates whether the caller is a known user of a Credit Card |
| richdata -> wealthNetWorth | ## caller_wealthNetWorth## | Estimated net worth of the caller |
| richdata -> charityDonor | ## caller_charityDonor## | Indicates whether the caller has donated to a charity in the past |
| richdata -> dwellType | ## caller_dwellType## | Type of home that the caller lives in |
| richdata -> marketHomeValue | ## caller_marketHomeValue## | Market value of the caller's home |
| richdata -> presenceOfChildren | ## caller_presenceOfChildren## | Indicates whether the caller has children |
| richdata -> children | ## caller_children## | Indicates the number of children in the caller household |
| richdata -> childAgeRanges | ## caller_childAgeRanges## | Indicates the age ranges of all children present in the caller household |
| richdata -> ethnicity | ## caller_ethnicity## | Indicates whether the caller is identified to be of a particular ethnicity |
| richdata -> vehicleLuxury | ## caller_vehicleLuxury## | Indicates if the caller owns a luxury vehicle |
| richdata -> vehicleSuv | ## caller_vehicleSuv## | Indicates if the caller owns a SUV |
| richdata -> vehicleTruck | ## caller_vehicleTruck## | Indicates if the caller owns a pickup truck |
| richdata -> email | ## caller_email## | Known email address associated with the caller |
| conversation_analytics -> call_record_file | ## call_record_file## | Unique ID of the Call Recording file |
| conversation_analytics -> call_record_redaction | ## call_record_redaction## | True/False flag if redaction was performed on the call recording |
| conversation_analytics -> voice_link | ## call_record_url## | URL to the call recording |
| conversation_analytics -> transcript | ## call_transcript## | Transcription of the call recording |
| dispositions -> lead | ## lead## | Indicator of whether the call was scored as a Lead |
| dispositions -> voicemail | ## voicemail## | Indicator that the call ended with a VoiceMail |
| dispositions -> current_customer | ## current_customer## | Indicator that the call Caller is an existing customer of the Business |
| dispositions -> Telemarketer | ## telemarketer## | Indicator that the call was from a business seeking to sell a product or service |
| dispositions -> employment_inquiry | ## employment_inquiry## | Indicator that the call Caller was seeking employment or verification of employment |
| dispositions -> conversation | ## conversation## | Indicator that a conversation took place on the call between caller and the business |
| dispositions -> opportunity | ## opportunity## | Indicator that there was an opportunity to make a sale/appointment |
| dispositions -> appointment | ## appointment## | Indicator that a sale/appointment was made on the call |
| dispositions -> abandon | ## abandon## | Indicator that the call was abandoned by the Caller |
| dispositions -> no_agent | ## no_agent## | Indicator that the call was answered but there was no response from the Agent |
| dispositions -> no_caller | ## no_caller## | Indicator that the call was answered but there was no response from the Caller |
| attribution_details -> rule_description | ## dni_rule_description## | Description (Name) of the DNI rule that was triggered by the caller |
| attribution_details -> rule_id | ## dni_rule_id## | ID of the DNI rule that was triggered by the caller |
| attribution_details -> session_id | ## dni_session_id## | Unique session id created when a website visitor arrives at a page with DNI |
| attribution_details -> session_identifier | ## dni_session_identifier## | Unique session id created when a website visitor arrives at a page with DNI |
| attribution_details -> utm_campaign | ## utm_campaign## | utm_campaign parameter captured when a user arrives at a site where DNI occurs or mapped to the Number/Pool |
| attribution_details -> utm_term | ## utm_term## | utm_term parameter captured when a user arrives at a site where DNI occurs or mapped to the Number/Pool |
| attribution_details -> utm_source | ## utm_source## | utm_source parameter captured when a user arrives at a site where DNI occurs or mapped to the Number/Pool |
| attribution_details -> utm_medium | ## utm_medium## | utm_medium parameter captured when a user arrives at a site where DNI occurs or mapped to the Number/Pool |
| attribution_details -> utm_content | ## utm_content## | utm_content parameter captured when a user arrives at a site where DNI occurs or mapped to the Number/Pool |
| attribution_details -> gclid | ## gclid## | Google Click ID, parameter passed in the URL with ad clicks, to identify the campaign and other attributes of the click associated with the ad for ad tracking and campaign attribution |
| attribution_details -> wbraid | ## wbraid## | URL parameter to help comply with Apple's policies and help you measure the results of your ads on iOS used for app to web measurement |
| attribution_details -> gbraid | ## gbraid## | URL parameter to help comply with Apple's policies and help you measure the results of your ads on iOS used for web to app measurement |
| attribution_details -> msclkid | ## msclkid## | Microsoft Click ID, parameter passed in the URL with ad clicks, to identify the campaign and other attributes of the click associated with the ad for ad tracking and campaign attribution |
| attribution_details -> landing_page_url | ## landing_page_url## | URL of the landing page that a website user arrives on or mapped to the Number/Pool |
| attribution_details -> referrer_url | ## referrer_url## | URL of the referrer responsible for bringing a user to a webpage with DNI enabled |
| attribution_details -> multisession_flag | ## dni_multisession_flag## | a true/false that indicates whether more than 1 website visitor has seen the same Tracking Number within the match period configured for a Number Pool |
| attribution_details -> ip_address | ## dni_ip_address## | IP Address of the device used by the user of the DNI session |
| attribution_details -> device_longitude | ## dni_device_longitude## | Longitue coordinates of the device used by the user of the DNI session |
| attribution_details -> device_latitude | ## dni_device_latitude## | Latitude coordinates of the device used by the user of the DNI session |
| attribution_details -> page_variables | ## on_page_variables.<variable_name>## | Custom JavaScript variables defined by the customer. <variable_name> must correspond to the On-Page variable name configured as part of a DNI rule. |
| session_tag -> lead_tracking_tag_id | ## lead_tracking_tag_id## | Id of lead tracking tag. |
| session_tag -> lead_tracking_tag_data | ## lead_tracking_tag_data## | Lead tracking tag data. |
| session_tag -> timestamp | ## lead_tracking_timestamp## | Time the lead tracking tag was created |
| conversion_details -> attributed_value | ## conversion_value_total## | Total value of conversions attributed back to the call |
| conversion_details -> attributed_conversions | ## conversion_count## | Number of conversions attributed to the call |
| conversion_details -> conversion_stage | ## conversion_stage## | Percentage representation of consumer purchase journey completed |
| conversion_details -> marchex_conversion_id | ## conversion_id## | Unique ID of Conversion attributed to a Call |
| conversion_details -> transaction_id | ## conversion_transaction_id## | Ingested Identifier provided by User, CRM, or POS |
| conversion_details -> conversion_timestamp | ## conversion_timestamp## | Timestamp of the conversion |
| conversion_details -> conversion_value | ## conversion_value## | Value of the conversion |
| conversion_details -> ingestion_timestamp | ## conversion_ingestion_timestamp## | Timestamp of conversion ingestion by Marchex |
| google_analytics -> tracking_id | ## google_tracking_id## | The tracking ID / web property ID. The format is UA-XXXX-Y. All collected Google Analytics data is associated by this ID. |
| google_analytics -> user_id | ## google_user_id## | This is intended to be a known identifier for a user provided by the site owner/library user |
| google_analytics -> campaign_medium | ## google_campaign_medium## | Specifies the campaign medium. |
| google_analytics -> client_id | ## google_client_id## | This pseudonymously identifies a particular user, device, or browser instance |
| google_analytics -> referrer | ## google_referrer## | Specifies which referral source brought traffic to a website. This value is also used to compute the traffic source |
| google_analytics -> location | ## google_location## | The geographical location of the user. The geographical ID should be a two letter country code or a criteria ID representing a city or region |
| google_analytics -> page | ## google_page## | Full URL of the page on which content resides |
| google_analytics -> screen_resolution | ## google_screen_resolution## | Specifies the screen resolution. |
| google_analytics -> screen_colors | ## google_screen_colors## | Specifies the screen color depth. |
| google_analytics -> viewport_size | ## google_viewport_size## | Specifies the viewable area of the browser / device. |
| google_analytics -> flash_version | ## google_flash_version## | Specifies the flash version. |
| google_analytics -> encoding | ## google_encoding## | Specifies the character set used to encode the page / document. |
| google_analytics -> java_enabled | ## google_java_enabled## | Specifies whether Java was enabled. |
| google_analytics -> language | ## google_language## | Specifies the language |
| google_analytics -> hit_type | ## google_hit_type## | The type of hit. Must be one of 'pageview', 'screenview', 'event', 'transaction', 'item', 'social', 'exception', 'timing'. |
| google_analytics -> google_session_id | ## google_session_id## | Google Session ID |
| adobe_analytics -> channel | ## adobe_channel## | Channel name |
| adobe_analytics -> visitor_id | ## adobe_visitor_id## | Unique value that represents a customer in both the online and offline systems |
| adobe_analytics -> campaign | ## adobe_campaign## | Campaign name |
| adobe_analytics -> page_name | ## adobe_page_name## | Full URL of the page on which content resides |
| adobe_analytics -> routing_keypress | ## call_routing_keypress## | If Key Press routing was enabled for the number, this field will contain the value entered by the consumer |
| adobe_analytics -> segment_name | ## call_routing_segment_name## | Segment name |
| adobe_analytics -> start_time | ## call_start_time## | Time the call was initiated relative to the time zone of the Campaign the Tracking Number is associated with. This time is used when calculating usage for billing purposes |
| adobe_analytics -> answer_time | ## call_answer_time## | Time the call answered relative to the time zone of the Campaign the Tracking Number is associated with. This time is used when calculating usage for billing purposes. |
| adobe_analytics -> end_time | ## call_end_time## | Time the call ended relative to the time zone of the Campaign the Tracking Number is associated with. This time is used when calculating usage for billing purposes. |
| adobe_analytics -> start_time_utc | ## call_start_time_utc## | Time the call was initiated in UTC |
| adobe_analytics -> answer_time_utc | ## call_answer_time_utc## | Time the call was answered in UTC |
| adobe_analytics -> end_time_utc | ## call_end_time_utc## | Time the call ended in UTC |
| adobe_analytics -> status | ## call_status## | Current status of the call |
| call_tags | ## call_tags## | List of all Call tag Ids applied to the call |
| rescue -> opportunity | ## rescue_opportunity## | Identifies the call as a Positive, Negative or Neutral rescue opportunity |
| rescue -> minor_tag | ## rescue_minor_tag## | More granular definition of the opportunity |
| rescue -> outcome | ## rescue_outcome## | Identified the Outcome of the call as Conversation, Opportunity or Appointment |
| rescue -> result | ## rescue_result## | Description of the call results giving details on the contents of the call |
| rescue -> lastUpdate | ## rescue_lastUpdate## | Timestamp of the last update made to the rescue status of the call. |
| number_custom_fields -> number_custom_id | ## number_custom_id## | User defined custom fields for the Number |
| number_custom_fields -> number_custom_field_1 | ## number_custom_field_1## | User defined custom fields for the Number |
| number_custom_fields -> number_custom_field_2 | ## number_custom_field_2## | User defined custom fields for the Number |
| number_custom_fields -> number_custom_field_3 | ## number_custom_field_3## | User defined custom fields for the Number |
| group_custom_fields -> group_custom_id | ## group_custom_id## | User defined custom fields for the Group |
| group_custom_fields -> group_custom_field_1 | ## group_custom_field_1## | User defined custom fields for the Group |
| group_custom_fields -> group_custom_field_2 | ## group_custom_field_2## | User defined custom fields for the Group |
| group_custom_fields -> group_custom_field_3 | ## group_custom_field_3## | User defined custom fields for the Group |
| group_custom_fields -> group_custom_field_4 | ## group_custom_field_4## | User defined custom fields for the Group |
| group_owner_custom_fields -> group_owner_custom_field_1 | ## group_owner_custom_field_1## | User defined custom fields for the Group Owner |
| group_owner_custom_fields -> group_owner_custom_field_2 | ## group_owner_custom_field_2## | User defined custom fields for the Group Owner |
Updated 8 months ago