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 ParameterSubstitution ParameterDescription
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
conversation_analytics -> call_summary## call_summary##AI generated summary of the call recording that will surface the intent of the caller, products/services discussed, and whether the caller was able to achieve their goal
conversation_analytics -> sentiment_suite -> sentiment_summary## sentiment_summary##A generative description of the caller's overall sentiment
conversation_analytics -> sentiment_suite -> sentiment## sentiment##The caller's overall sentiment on the call
conversation_analytics -> sentiment_suite -> satisfied## satisfied##Was the caller satisfied or not
conversation_analytics -> sentiment_suite -> frustrated## frustrated##Was the caller frustrated or not
conversation_analytics -> sentiment_suite -> frustrated_reason## frustrated_reason##A generative description of what the caller is frustrated about
conversation_analytics -> sentiment_suite -> view_of_business## view_of_business##The caller's view of the business
conversation_analytics -> sentiment_suite -> view_of_business_reason## view_of_business_reason##A generative description of the reason for the callers view of the business
conversation_analytics -> sentiment_suite -> concern_class## concern_class##A generative description of the reason for the caller's negative view
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_20## number_custom_field_1## ... ## number_custom_field_20##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_20## group_custom_field_1## ... ## group_custom_field_20##User defined custom fields for the Group
group_owner_custom_fields -> group_owner_custom_field_1 ... group_owner_custom_field_20## group_owner_custom_field_1## ... ## group_owner_custom_field_20##User defined custom fields for the Group Owner