What are webhooks?

Sending JSON webhooks is an efficient way to transfer data from one application to another in real-time. This process involves the use of a webhook URL, which is provided by the receiving application (Convolo in this case), and acts as a phone number that the other application can call when an event occurs. The data is then sent over the web from the application where the event originally occurred, to the receiving application that handles the data. This data is known as the “payload” and is usually sent in either JSON or XML format.

How to send data with webhooks to trigger a Speed To Lead™ call ?

Our webhook expands on ways you can connect with your leads by turning webforms, shopping carts, or anything you want into an opportunity to be the first to lead.

Now let’s look at some code examples of sending a JSON webhook to Convolo:

1. Save Convolo’s request URL and choose if you prefer to submit a GET or POST request.

https://app.convolo.ai/rest/v1/ext/add_call_api/

2. Add keys and values according to the examples below. More info on how to find your personal widget key and API key can be found here → How to get a Widget Key? and How to get an API Key?

👇 JSON Header for POST method

Key	Value
Content-Type	application/json

👇 JSON Body for POST method and minimum required fields

Key	Value
widget_key	%WIDGET_KEY%
api_key	%API_KEY%
lc_number	+1234567890

👇 Example: Combined JSON object for POST method and minimum required fields

'headers': { 
      'Content-Type': 'application/json', 
}, 

 'body':  { 
  'widget_key': '%WIDGET_KEY%', // Widget key 
  'api_key': '%API_KEY%', // API key 
  'lc_number': '+1234567890' // leads's phone number 
}

👇 Example: GET method and minimum required fields

https://app.convolo.ai/rest/v1/ext/add_call_api/?widget_key={WIDGET_KEY}&api_key={API_KEY}&lc_number={number}

3. Now, you should have all that it takes to trigger a call to Convolo. But, you can submit additional data from form fields as needed by including optional custom parameters (you can find out more about custom parameters in our dedicated article here):

 "headers'": {
   "Content-Type": "application/json",
 },

 "body": {
     "widget_key": "%WIDGET_KEY%",
     "api_key": "%API_KEY%", 
     "lc_number": "+1234567890" 
     "lc_param_name": "John Doe", // lead's name
     "lc_param_email": "[email protected]", // lead's email
     "lc_param_message": "Hello, world!", // Message
     "lc_number_2": "+1234567892" // optional lead's second phone number
     "country": "UK" // two letter ISO country code used for local number format conversion, if needed
}

4. If you followed all the steps correctly, you should have a powerful API request ready to impress your leads. Great work! 🎉

Pass agent’s info into the webhook [optional]

Agents can also be defined using our webhook, meaning that you can send calls to a specific agent or even agents who are not defined in the call queue in the Convolo Dashboard.

In order to trigger a call at agents phone number, you just need to add the custom parameters such as "lc_param_agent01name" and "lc_param_agent01phone". Then just fill the values with the contact information from your agent(s) as shown below.

"lc_param_agent01name": "James Smith", "lc_param_agent01phone":"+1234567890"

lc_param_agent<replace this with your number of choice>name - custom agent name (e.g. lc_param_agent01name)

lc_param_agent<use the same number you set in the above field>phone - custom agent phone (e.g. lc_param_agent01phone). Phone numbers can be with trailing zero or without.

Example

To connect John Doe (a lead) with James, Anna or Ahmad (agents), we need to list information of the lead and the agents in the following format.

 "headers'": {
   "Content-Type": "application/json",
 },

 "body": {
     "widget_key": "%WIDGET_KEY%",
     "api_key": "%API_KEY%", 
     "lc_number": "+1234567890" 
     "lc_param_name": "John Doe", // lead's name
     "lc_param_email": "[email protected]", // lead's email
     "lc_param_message": "Hello, world!", // Message
     "lc_number_2": "+1234567892" // optional lead's second phone number
     "country": "US"
     "lc_param_agent01name": "James Smith",   // Agent 1
     "lc_param_agent01phone":"+1234567890"
     "lc_param_agent02name": "Anna Williams", // Agent 2 
     "lc_param_agent02phone":"+44234567890"
     "lc_param_agent03name": "Ahmad Khaled",  // Agent 3
     "lc_param_agent03phone":"+97123567890"

}

Then we need to define how the calls will be distributed among James, Anna and Ahmad. Call distribution among the agents can be defined inside of the Dashboard under a section called "Call Routing". In the screenshot below you can find all the call distribution types available by the Convolo system.

If you have any questions, please email us at [email protected]