Using Real-Time Routing Webhooks to Include Invoca Data With Third-Party Call Routing

Query a third-party system before a call connects, so its response can route the call or add Marketing Data — using a Real-Time Routing webhook.

​

Step 1: Create your Real-Time Routing webhook

• Type: Real-Time Routing
• Name: something that makes clear what data you’re sending and to which system.
• URL and Action: find your other system’s endpoint URL in its API documentation, then choose POST or GET as needed.
• Format: JSON or XML. JSON supports an extra feature XML doesn’t (see below) — check your other system’s documentation for which format it accepts.
• Headers and Body: add any Invoca data you want to pass along. In most cases, you’ll send a caller ID phone number and configure your other system to respond with routing information.
• Data Mapping: unique to Real-Time Routing webhooks — lets you take data from your other system’s response and capture it in Invoca as Marketing Data, for routing and reporting.

• Bundle Destination Ids: Invoca-generated campaign IDs.
• Bundle Destination Ids from Network: IDs you’ve assigned to the campaign, often to match an external system.

​

Step 2: Set up your third-party system to receive data from Invoca

• destination_numbers (required): a list of destination numbers in E.164 format, separated by commas (for example, ["+15551234567", "+15557654321"]).
• number_labels (optional): names for each number, as strings (for example, ["Santa Barbara regional call center", "Denver regional call center"]).
• call_acceptance (optional): whether agents can accept or reject the call before answering, as a boolean.
• timeout (optional): seconds to wait before dialing the next destination, as an integer.
• distribution_method (optional): InOrder, Random, or Weighted.
• destination_weights (optional): relative weight per destination if using “Weighted,” as integers matching the order of destination_numbers (for example, [3, 1]). See “How to Improve Answer Rates by Forwarding Phone Calls to a Group of Numbers” for more.
• simultaneous_calls (optional): how many destinations to dial concurrently, as an integer.
• destination_total_limit (optional): for “Random” or “Weighted” distribution, the total destinations to try before moving on, as an integer.

​

Additional formatting guidelines

• To reference nested values, use dot notation: path.to.response_key.
• You can add an extension or internal IVR keypress to destination_phone_number using “x” followed by keypresses, and a comma for a 1-second pause (for example, +18055551234x5,,145).
• Invoca monitors whether Real-Time Webhooks fire correctly. If a webhook doesn’t respond, responds outside the time limit, or returns invalid data, Invoca treats it as a failed response (see Step 4).

​

Sample webhook responses

{
  "destination_campaign_id": 1234,
  "destination_campaign_id_from_network": "paidsearch1",
  "destination_phone_number": "+15551234567"
}

{
  "ring_group": {
    "destination_numbers": ["+15551234567", "+15557654321"],
    "number_labels": ["Santa Barbara regional call center", "Denver regional call center"],
    "destination_weights": [3, 1],
    "call_acceptance": true,
    "timeout": 6,
    "distribution_method": "Weighted",
    "simultaneous_calls": 2,
    "destination_total_limit": 5
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<bundled_ids>
  <bundled_destination_id>1</bundled_destination_id>
  <bundled_destination_id>2</bundled_destination_id>
</bundled_ids>

{"destination_ids":["1234", "5678"]}

<?xml version="1.0" encoding="UTF-8"?>
<destination_phone_number>+18055551234</destination_phone_number>

{"phone_number":"+13033301230"}

{
  "calling": [
    {"phone_number":"+13033301230"}
  ]
}

{"destination_campaign_id":1234,"phone_number":"+13033301230"}

​

Step 3: Testing your Real-Time Routing webhook

​

Step 4: Add Real-Time Routing to your call treatment tree

​

Step 5: View and audit Real-Time Routing activity in your reports

• {Phone Number}: the number your system returned and the call was routed to (may include an extension).
• (blank): no webhook fired for this call.
• “Empty Response”: the webhook fired but returned an empty response.
• “Incorrect Response” (with troubleshooting details): the webhook fired but returned invalid data.
• “Response not received in time”: the webhook fired but timed out before Invoca received a response.
• {Campaign ID}: for bundled campaigns, the campaign ID your system returned.
• “No Eligible Destination Campaign”: the call didn’t qualify for any bundle destination (due to hours, location, etc.), so no webhook request was sent.

​

Where to go next

• How to Create, Edit, or Clone an Invoca Webhook
• Using Real-Time Routing Webhooks: XML Format
• Using Real-Time Routing Webhooks: Nested Variables