...
Internal Webhooks: Use any of the pre-made internal functions. Use this when you need to use any of the commonly used functions.
Webhook Widget: Call any external API using dynamic data and configurable structure. Use this when you want to integrate and use any external API
Flow End Webhook: Call the default external webhook for any flow. Use this when you need to push flow details on a particular webhook.
Status title To be deprecated
1. Internal Webhook
Custom webhooks are internal webhooks which can be used to pass on the data in between the flow execution.
Using webhook widget, you can simply invoke any configured internal webhook in between the flow and call any specific method to push some data.
You do not need to bother about the request body or need to specify the variables that needs to be passed. You can simply follow the 2 below steps to invoke any webhook in between the flow.
List of Internal Webhook
You can use any of the following internal functions. How to configure them is listed below.
1. Initiate Outbound Flow
Using this webhook, you can request to initiate any Outbound Flow of your account using it's API.
URL : http://192.168.1.42:3000/centraloutboundwebhook-v1/prod/
Method : createOutbound
Request :
...
Flow Variable
...
Example
...
Description
...
$flow.syskey.apiVersion
...
1.0
...
Outbound Flow Version
...
$flow.syskey.securityID
...
<64 Character UUID>
...
Security ID
...
$flow.syskey.flowID
...
<8 Chacter UUID>
...
Flow ID
...
$flow.syskey.clientID
...
123123123
...
Client Identifier
...
$flow.syskey.delayMinutes
...
0
...
When to start the Outbound Flow from current system time.
...
$flow.syskey.contactNumbers
...
91997974 6666
...
Customer Numbers
Response :
...
Flow Variable
...
Value
...
$flow.key.obdResponseCode
...
200
...
$flow.key.obdReqID
...
Request ID
...
$flow.key.obdPhononUUID
...
Phonon UUID
2. shortURL
Using this webhook, you can shorten a long URL to a short URL.
URL: https://s.phonon.in/UrlShortner/phonon/shortUrl
Method: POST
Headers:
...
Headers
...
Title
...
Content-Type
...
application/json
...
Accept
...
application/json
Request:
| Code Block |
|---|
{
"custToken": "abcd1234",
"longUrl": "https://google.co.in"
} |
custToken is static at "abcd1234"
Response:
| Code Block |
|---|
{
"shortUrl": "https://s.phonon.in/BEK4YYnx"
} |
You can have your custom domain. Contact Support to help you with that.
3. updateUserPreferences
Using this webhook, you can update $user.key Flow Variables without requiring a Make Call widget. Great for usage in Email and SMS flows. Note: This will become an inert feature of $user.key flow variables soon resulting this to be obsolete.
URL: http://192.168.50.21:3000/centraloutboundwebhook-v1/test/
Method : POST
Request :
...
Flow Variable
...
Example
...
Details
...
$user.syskey.contactNumber
...
8000374XXX
...
Enter the unique ID of the Customer such as it's phone number.
...
$user.syskey.accountID
...
163
...
Account ID of the Central Account where the flow is
...
$user.key.XXXX...
...
Value
...
You can save or get any value
Response :
4. updatePauseStatusForCLI - Change Break Status of a Direct Dial Agent
Using this webhook, you can change the break status of a Direct Dial Agent. While the Direct Dial Agent is on break, s/he will not be considered for any calls allotment. For example, if your Dialer DID is 91806880080, you can create an Inbound Flow with the same DID with this webhook. DID Agents can call on the Inbound number to change their pause status anytime (or you can toggle it automatically).
Notes:
In the Dialer Flow, you can get the Agent CLI using
$call.agent.dnis.numberor for Inbound Flow =>$call.cli.number
URL: http://192.168.60.15:3000/centraloutboundwebhook-v1/prod/
Method: POST
Request :
...
Flow Variable
...
Example
...
Description
...
$flow.key.pause
...
true
...
Set the Direct Dial Agent Pause Status to be true. Mandatory
...
Content
...
false
...
Set the Direct Dial Agent Pause Status to be false. Mandatory
...
$flow.key.cli
...
9879964805
...
CLI of the Direct Dial Agent. With or Without Country CodeMandatory
...
Content
...
919879964805
...
Content
Response :
...
Flow Variable
...
Example
...
Description
...
$flow.key.cli_pause_update
...
true
...
The Direct Dial was successfully paused / unpaused
...
Content
...
false
...
The Direct Dial was could not be paused / unpaused
Step 1 : Configure Internal Webhook
First step is to configure a webhook(to which the details will be send). To configure a webhook, you can follow the below steps -
Go to Advanced → Webhook page
Click on ‘add webhook’
Select the method as ‘Post’
Enter or paste the URL of the internal webhook that you need to call/invoke from the list below
Select ‘none’ in the authentication method
Select the body type as ‘None’ and click on save button.
Step 2 : Save Variable (Optional)
If you want to provide any parameters then first you can store that parameter in any flow variable using operation widget (General Assignment Method). This step is completely optional.
Step 3 : Select configurations
In the webhook widget, you need to perform following configurations -
Select URL : Once you have configured the webhook, you will be able to see that URL in the webhook widget. Select the URL of the webhook that you need to invoke.
Enter Method : Enter the name of the method that you need to call
Select Parameters : Select the parameters that you want to pass. Query parameters are the type of variables that will be passed based on the method selected. You can select multiple parameters.
Call : All the variables of ‘call type’ ($call.cli, $call.state, $call.start etc)
$flow.key : All the variable of type ‘$flow.key’ ($flow.key.<keyname>) will be passed
$user.key : All the user key variables will be passed ($user.key.<keyname>) will be passed. To know more about variables, you can click here.
Document API : You can use this area to document your API that is you can explain or provide some insights of the purpose of this webhook call/API. This is an optional field.
Note :
Make sure your HTTP usage is enabled for your account. If not, then you can send a mail to request for the same on support@phonon.io
Make sure to whitelist your IP in the whitelist section of your account
Once any specific method is called, the values will be appeared in the specified response variables.
Custom Webhook Widget
| Info |
|---|
Use this when you want to call any external API with predefined structure. All Flow Variables will work in any section of the widget. |
Introduction
This webhook widget is use to call any external API using dynamic data and configurable structure. You can use this when you want to integrate and use any external API in between or at the end of the flow execution.
Step 1: Add Webhook Widget
In the flow designer select the webhook widget and add to the designer screen and connect with the appropriate widget. Now double click on the widget to open the configurations -
Now the select the ‘custom’ option in the URL
Step 2: Configure Request
After you select the custom option, you need to configure the webhook/API request. To configure the request, you need to following configurations -
Method : You need to select the method based on the action you need to perform in the API request. The methods supported are GET, POST, PATCH, DELETE, PUT, OPTION, HEAD.
Authentication : The authentication method that is required to perform the action on the URL. You can select ‘none’ if there is no authentication required or you can select ‘basic’ and provide username and password for authentication.
Headers : Some APIs require you to send particular headers along with sending request, typically to provide additional metadata about the operation you are performing. So by clicking on ‘add headers’ and you can provide headers that are necessary by providing its key and value. You can add multiple headers and mark them as mandatory as well (if required).
Body Type : The type of the body in which the request will be send. It can be none, JSON or XML.
Body : Here you need to provide the request body, according to the body type selected
Query Parameters : Query parameters are appended at the end of the URL. They are extensions of the URL that are used to help define specific content or actions based on the data being passed. You can add multiple query parameters by clicking on ‘add query parameter’ and also mark them as mandatory by selecting the checkbox. You can provide the key and value of the query parameter in their respective text box.
| Info |
|---|
|
Step 3 : Configure Response
Once the request is configured, you need to configure the response of that request in webhook widget. In order to configure response, follow below steps -
Response Type : Select the type of the response that you will be receiving from API call. The response type can be JSON or XML.
Object Mapping : You can directly save a particular value from the response data in a Flow Variable. To store a response value in a Flow Variable, click on the '➕' button.
In the ‘Save In’ column, enter the Flow Variable in which you want to save the response value.
In ‘Object Map’, enter the path of the response value you want to save. To get the path for:
'JSON' Response Type : When the response type is JSON, in order to find the path of the object you can visit http://jsonpathfinder.com.
On this page, you can paste your JSON response and on the right side, click on the object whose path you need to find.
You will be able to see the path at the top right corner.
Copy that path and paste in the ‘object map’ area.
Replace ‘X' with 'data’
To know more, you can refer to the help section of the widget.
You can mark any response object as ‘mandatory’, by selecting the checkbox.
‘XML’ Response Type: When the response type is XML, you need to put the XML Path of the response value. Unfortunately, there is no simple online tool that you can use to get that value. You can read about XML Path here and test your path with sample data here. If you need more help, contact our Tech Support Team to help you with the path at support@phonon.io
Step 4 : Other Configurations
After the response parameters are configured, you can configure some additional configurations as follows -
Wait for response : Enable if you want to wait for the response of your request. You can play hold music meanwhile by enabling ‘enable hold music’. The maximum response wait time is ‘60 seconds’.
Persist Response : Enable if you want to retain the value of flow variables after the flow execution is completed.
Error code Flow Variables : Once the execution of webhook widget is over, you will be able to get some of the values in the specified flow variables which are as follows -
On Success -
...
Flow Variable
...
Description
...
Example Value
...
$flow.key.response_status
...
API call Success or Failure status
...
SUCCESS
...
$flow.key.response_status_code
...
Status Code for response(2XX)
...
200
...
$flow.key.response_duration
...
Duration in seconds for the API to return data
...
0.11
...
$flow.key.response_raw
...
Raw response received from server, null if empty
...
$flow.key.response_error
...
If API resulted in error, Boolean true or false
...
false
b. On Failure -
...
Flow Variable
...
Description
...
Example Value
...
$flow.key.response_status
...
API call Success or Failure status
...
FAILED
...
$flow.key.response_status_code
...
Status Code for response
...
401, 200
...
$flow.key.response_status_type
...
Type of error, based on status code
...
Redirection
...
$flow.key.response_duration
...
Duration in seconds for the API to return data
...
0.11
...
$flow.key.response_raw
...
Raw response received from server, null if empty
...
{...}
...
$flow.key.response_error
...
If API resulted in error, Boolean true or false
...
true
...
$flow.key.error_reason
...
Reason for failure
...
SERVER_ERROR
Once the execution of the webhook widget is completed, according to the response the flow will move forward. That is for success response, it will move in ‘line 0’ and for failure response, it will move in ‘line 1’.
Flow End Webhook
On flow complete webhooks are used when you want to push/send all the flow details to the default webhook once the flow gets completed.
In order to send the details on flow complete, you need to follow below steps -
Step 1 : Configure webhook
First step is to configure a webhook(to which the details will be send) and set it as ‘default webhook’. To configure a webhook, you can follow below steps -
Go to Advanced → Webhook page
Click on ‘add webhook’
Select the method as ‘Post’
Enter or paste your external webhook URL and click on ‘check button’.
Once you see a green tick beside check button, select the authentication method.
None : If there is no authentication required
Basic : If username and password is required
Select the body type as ‘None’.
Enable ‘Is default webhook' and click on save button.
Step 2 : Enable webhook in flow
Open the ‘Details section’ of the flow for which you want to send details to the webhook.
Enable ‘webhook for the flow’ and done. After ever execution of this flow, all the flow details will be send to the default webhook in the predefined format.
Predefined Format :
...
To know about all internal webhooks, you can click here.
Step 0: Enable HTTP Support
Make sure that http service is enabled for your account. If it is not enabled, then you can send a mail to request for the same on support@phonon.io
Step 1 : Configure Internal Webhook
First step is to configure a webhook(to which the details will be send). To configure a webhook, you can follow the below steps -
Go to Advanced → Webhook page
Click on ‘Add Webhook’
Select the method as ‘Post’
Enter or paste the URL of the internal webhook that you need to call/invoke from the above list
Select ‘None’ in the authentication method
Select the body type as ‘None’ and click on save button.
...
| Note |
|---|
If ‘HTTP Support’ is not enabled in your account, you’ll be able to see a ‘Check’ button beside the URL field. You will not be able to use the Internal Webhooks in such case. Please follow the instructions in Step 0 as stated. |
Step 2 : Save Variable (Optional)
If you want to provide any additional parameters then first you can store that parameter in any flow variable using operation widget (General Assignment Method) and then that variable can be parsed. This step is completely optional.
Step 3 : Select configurations
In the webhook widget, you need to perform following configurations -
Select URL : Once you have configured the webhook, you will be able to see that URL in the webhook widget. Select the URL of the webhook that you need to invoke.
Enter Method : Enter the name of the method that you need to call. Method name is the heading name in the list above.
Select Parameters : Select the parameters that you want to pass. Query parameters are the type of variables that will be passed based on the method selected. You can select multiple parameters.
Call : All the variables of ‘call type’ ($call.cli, $call.state, $call.start etc)
$flow.key : All the variable of type ‘$flow.key’ ($flow.key.<keyname>) will be passed
$user.key : All the user key variables will be passed ($user.key.<keyname>) will be passed. To know more about variables, you can click here.
Document your API (Notes) :
It is a place to write any information about the webhook, such as expected request, expected response, meaning of response, etc.
Max 1000 characters are allowed
...
Step 4 : Other Configurations
After the 1st tab(request), 2nd tab would be ‘response’ in which no configurations are needed. On the 3rd tab, you will be able to perform following configurations -
Wait for response : Enable if you want to wait for the response of your request. You can play hold music meanwhile by enabling ‘Enable hold music’. The maximum response wait time is ‘60 seconds’.
Persist Response : Enable if you want to retain the value of flow variables after the flow execution is completed. Use this only if you need to save the data and use it later, example as a UDF in Reports.
Note :
Once any specific method is called, the values will be appeared in the specified response variables.
2. Custom Webhook Widget
This webhook widget is use to call any external API using dynamic data with predefined structure. You can use this when you want to integrate and use any external API in between or at the end of the flow execution. In order to configure a ‘custom API’, you can follow below steps -
| Info |
|---|
The external API will be called from out hosted premise. If you need to whitelist our IPs, head over here and whitelist the IPs in BLR section. (Example: 103.141.42.0/24). These IPs may also change once we move to AWS. You’ll be notified 30 days before. |
Step 1: Add Webhook Widget
In the flow designer select the webhook widget and add to the designer screen and connect with the appropriate widget. Now double click on the widget to open the configurations -
Now the select the ‘custom’ option in the URL
Step 2: Configure Request
After you select the custom option, you need to configure the webhook/API request. To configure the request, you need to following configurations -
URL : Enter or paste the URL endpoint of the API request. The URL must start with https. If HTTP service is enabled for the account, then you will be able to use http URLs.
Method : You need to select the method based on the action you need to perform in the API request. The methods supported are GET, POST, PATCH, DELETE, PUT, OPTION, HEAD.
Authentication : The authentication method that is required to perform the action on the URL. You can select ‘none’ if there is no authentication required or you can select ‘basic’ and provide username and password for authentication.
Headers : Some APIs require you to send particular headers along with sending request, typically to provide additional metadata about the operation you are performing. So by clicking on ‘add headers’ and you can provide headers that are necessary by providing its key and value. You can add multiple headers and mark them as mandatory as well (if required). You can remove any header by clicking on the ‘delete icon’.
Body Type : The type of the body in which the request will be send. It can be none, JSON, XML or form data.
Body : Here you need to provide the request body, according to the body type selected
Query Parameters : Query parameters are appended at the end of the URL. They are extensions of the URL that are used to help define specific content or actions based on the data being passed. You can add multiple query parameters by clicking on ‘add query parameter’ and also mark them as mandatory by selecting the checkbox. You can provide the key and value of the query parameter in their respective text box. You can remove any parameter by clicking on the ‘delete icon’.
Document your API (Notes) :
A place to write any information about the webhook, such as expected request, expected response, meaning of response, etc.
Wyswig Summernote Editor without Image and Video capabilities (Only text):
Collapsible
Max 1000 characters are allowed
| Info |
|---|
Marking mandatory
Flow Variables Supported
|
...
Step 3 : Configure Response
You can extract the value you need from the response you've received from your API call and map it to any flow variable
Response Type : Select the type of the response that you will be receiving from API call. The response type can be JSON or XML.
Object Mapping : You can directly save a particular value from the response data in a Flow Variable. To store a response value in a Flow Variable, click on the '➕' button.
In the ‘Save In’ column, enter the Flow Variable in which you want to save the response value.
In ‘Object Map’, enter the path of the response value you want to save. To get the path for:
'JSON' Response Type : When the response type is JSON, in order to find the path of the object you can visit http://jsonpathfinder.com.
On this page, you can paste your JSON response and on the right side, click on the object whose path you need to find.
You will be able to see the path at the top right corner.
Copy that path and paste in the ‘object map’ area.
Replace ‘
x.' from that path with 'data.’. Example: Replacex.glossarywithdata.glossaryYou can mark any response object as ‘mandatory’, by selecting the checkbox.
| Info |
|---|
Array De-serialisation
Example:
|
...
‘XML’ Response Type: When the response type is XML, you need to put the XML Path of the response value. To find out the XML Path, use this Online tool: XMLToolBox to get the XML Path. You can read about XML Path here and test your path with sample data XMLToolBox. If you need more help, contact our Tech Support Team to help you with the path at support@phonon.io
Step 4 : Other Configurations
After the response parameters are configured, you can configure some additional configurations as follows -
Wait for response : Enable if you want to wait for the response of your request. You can play hold music meanwhile by enabling ‘Enable hold music’. The maximum response wait time is ‘60 seconds’.
Persist Response : Enable if you want to retain the value of flow variables after the flow execution is completed. Use this only if you need to save the data and use it later, example as a UDF in Reports.
Flow Variables : Once the execution of webhook widget is over, you will be able to get some of the values in the specified flow variables. There is a collapsible menu under success and failed section. You can click on that to know about these specified flow variables in the widget. The flow variables are as follows -
On Success -
Flow Variable | Description | Example Value |
|---|---|---|
$flow.key.response_status | API call Success or Failure status | SUCCESS |
$flow.key.response_status_code | Status Code for response(2XX) | 200, 401 etc |
$flow.key.response_duration | Duration in seconds for the API to return data | 0.11 |
$flow.key.response_raw | Raw response received from server, null if empty | {...} |
$flow.key.response_error | If API resulted in error, Boolean true or false | false |
b. On Failure -
Flow Variable | Description | Example Value |
|---|---|---|
$flow.key.response_status | API call Success or Failure status | FAILED |
$flow.key.response_status_code | Status Code for response | 401, 200 etc |
$flow.key.response_status_type | Type of error, based on status code |
|
$flow.key.response_duration | Duration in seconds for the API to return data | 0.11 |
$flow.key.response_raw | Raw response received from server, null if empty | {...} |
$flow.key.response_error | If API resulted in error, Boolean true or false. True if error occured | true |
$flow.key.error_reason | Reason for failure |
|
| Info |
|---|
Moving Forward : Once the execution of the webhook widget is completed, according to the response the flow will move forward in that direction, that is
|
3. Flow End Webhook
On flow complete webhooks are used when you want to push/send all the flow details to the default webhook once the flow gets completed.
In order to send the details on flow complete, you need to follow below steps -
Step 1 : Configure webhook
First step is to configure a webhook(to which the details will be send) and set it as ‘default webhook’. To configure a webhook, you can follow below steps -
Go to Advanced → Webhook page
Click on ‘Add Webhook’
Select the method as ‘Post’
Enter or paste the URL of the webhook that you need to push the details to
Select the authentication method
None : If no authentication is required
Basic : If username and password is required. If you have selected this option, you need to provide the username and the password for the URL.
Select the body type as ‘None’
Set the “Default Webhook” switch on. This will set this webhook to be used by all Flow End Webhook calls.
...
Step 2 : Enable webhook in flow
Open the ‘Details section’ of the flow for which you want to send details to the webhook.
Enable ‘webhook for the flow’ and done. After ever execution of this flow, all the flow details will be send to the default webhook in the predefined format.
| Info |
|---|
If you see the switch is disabled, check if the webhook is properly configured and set as default. You can see if the status in “Webhook for Account is” is “Not Configured” then click on Configure Webhook to configure it. |
...
Predefined Format for single call leg flow :
| Code Block |
|---|
{
"callDetails": [
{
"calleeNumber": "Phone number of the callee",
"connectTime": "Timestamp of call when started",
"didNumber": "DID used in call",
"duration": "Total Call duration in seconds",
"endTime": "Timestamp of call when ended",
"hangupCause": "Hangup cause code of the call",
"incoming": True if the call was incoming false otherwise,
"startTime": "Timestamp of call when started"
}
],
"keys": [
{
"name": "$flow.key.variable1",
"value": "value of variable"
},
{
"name": "$flow.key.variable2",
"value": "value of variable"
} // This will be repeated for all the variables passed during the call
],
"phonon-uuid": "Phonon uuid of the call",
"recordingUrls": [
{
"recordedFileName": "file name of the recording",
"recordedFilePublicPath": "URL of the recording, where it is stored"
}
]
} |
Predefined Format for flow with two call legs, i.e customer and agent call legs in outbound multicast flow :
Please note:
callDetails: [Array of each call leg.calleeType: Agent for agent leg, and VISITOR for customer leg.duration: Duration of the leg in millisecondshangupCause: Why was the call disconnected. 16 is normal clearing.
keys: Array of each flow variable set in the flowname: name of the flow variablevalue: value of the flow variable
phonon-uuid: Unique identifier of the whole call
| Code Block | ||
|---|---|---|
| ||
{ "callDetails": [ { "calleeNumber": "919879072567", "calleeType": "VISITOR", "cdrId": "f1ca3a63-7eb7-4a8d-b50c-fbbdd3807034##pbx-9", "connectTime": "2022-01-17T18:07:28.889+05:30", "didNumber": "912243690284", "duration": "15962", "endTime": "2022-01-17T18:07:44.851+05:30", "hangupCause": "16", "incoming": false, "remoteHangup": false, "startTime": "2022-01-17T18:07:21.952+05:30" }, { "calleeNumber": "919822003887", "calleeType": "AGENT", "cdrId": "f7d646de-44af-4037-8722-2346fb11de86##pbx-9", "connectTime": "2022-01-17T18: 07: 40.142+05: 30", "didNumber": "912243690284", "duration": "4670", "endTime": "2022-01-17T18: 07: 44.812+05: 30", "hangupCause": "16", "remoteHangup": true, "startTime": "2022-01-17T18: 07: 31.153+05: 30" } ], "keys": [ { "name": "$flow.key.variable2customernum", "value": "value of variable919822003887" } // This will be repeated for all the variables passed during the call, { ], "phonon-uuidname": "Phonon uuid of the call$flow.key.leadid", "recordingUrlsvalue": [ "HFC123" }, { "recordedFileNamename": "file name of the recording","$flow.key.empid", "value": "IIFL123" }, { "recordedFilePublicPathname": "URL of the recording, where it is stored" } ] "$flow.key.isTTSUsed", "value": true } ], "phonon-uuid": "9d34878d-01a0-45ba-b5d6-6b097ae17611" } |
Outcome : Everytime the flow is executed, all the flow details (as mentioned in the format) will be send sent to the default webhook selected.
...
If you want to send some additional data at the end of the flow in some different format, then you can use a webhook widget after ‘on flow complete’ widget.
This functionality will be modified in the near future.
...
FAQs
...
Question | Answer | |
|---|---|---|
| 1 | Is it possible to change the Hold Music in Webhook Widget? | No. The Hold Music is the default hold music. |
| 2 | “Enable Webhook for Flow” is disabled. | Default Webhook is not configured. Please follow all the steps from the guide again. |