The webhook block is one of the three action blocks available in Guided Conversations. This block enables the conversation flow to interact with Zoho Desk processes or other Zoho services or third-party services. The webhook block uses APIs from Zoho or third-party services to make this interaction possible. Therefore, any data that can be accessed or any action that can be performed using APIs can be included in a conversation flow through webhook blocks.
Business Scenario
Let's say John is visiting the Zylker website to request a zPad replacement, as his screen is broken. Because he has already purchased a Zylker product, the Webhook block will try to retrieve his name or email address from the database using API calls. If he is already a contact in their business account, the bot will create a ticket for John and submit his ticket ID as confirmation. If John is not a contact, then it will go ahead and create a contact and then create a ticket ID for John. The webhook block here helps in finding out if John is an existing customer or not, and if yes, it will fetch all his details and ease the process of ticket creation.
Adding a Webhook Block
To add a webhook block to a flow, perform the following steps:
- Go to Setup > Self Service > Guided Conversations.
- Select the Flow in which you want to add the Webhook block.
- On the Guided Conversations builder, click the Add Block button ( ).
The Add Block panel will appear on the right. - On this panel, click Action Blocks and select Webhook.
- In the Webhook block panel that appears, enter the following details:
- Block name: Enter a name for the block. For example: 'Fetch Contact'
- Method: Choose an API call method from the list.
- Get: Fetches resources from existing contacts.
- Patch: Makes partial changes to be applied to an existing resource.
- Post: Creates or updates an existing resource.
- Put: Modifies a singular resource which is already a part of resources.
- Delete: Deletes an existing resource.
After this API is executed, the URL in the webhook stops receiving event information.
- Enter the REST API URL of the third-party application in the URL to notify the field.
- In the Query Params field, click and enter the parameters to sort or filter the resources criteria. For example: @email
- When you choose an API call, you must enter the header, which is the organization ID or the portal ID. This has to be passed as the Header value.
The API call will perform its action from this portal ID.
- In the Body section, select JSON or File Upload to add fields or upload files respectively.
- Do the following if you choose JSON:
- Mandatory variables: Add those you see marked mandatory in the API document. These are the fields that are available in the third-party or Zoho Services portal and those that need to be mapped by the GC component. To enter a variable value, you must enter a variable and type @, and then choose a variable from the pick-list
- Custom fields: Include any custom field available in the third-party or Zoho Services portal to the Body section, if required.
- Do the following if you choose File Upload:
- Enter the Key and the Value for the file to be uploaded.
- Click Save.
- Choose one of the following to create a Connection with the Desk portal.
- Pick Your Service: To create a connection from existing services
- Custom Service: To choose to create a completely new connection
Notes on request body parameters:
- The option to send data via the request's body is unavailable for GET requests.
- It is important that the value you declare in the body section be the information that you get from the user. Otherwise, you must define a starting value for the variable in the body section. The @ symbol for a variable indicates that the information is retrieved from the user via chatbot, which means a block for that variable is created in the GC.
- All other values in orange are static values, which you are not going to retrieve from the user. These values indicate that you are directly going to pass these values to be posted as the actual values for the particular fields or variables.
Pick your Service
To create a connection from existing services, perform the following steps:
- Refer to steps 1 to 9 under Adding a webhook block and continue from there.
- Click the Add button besides the Connections label.
The DRE page will open on a new tab. - Under Pick Your Service, choose from the already available third-party services with Zoho, or you can choose one of Zoho services itself.
- Enter a name for the connection and the connection link.
Note: You may need to choose the scopes applicable to the service, when prompted. - Click Create and Connect.
- Click Accept to allow your organization/portal to connect with the workflow.
The connection summary page will display, as shown below.
- In the Connections section of the Webhook Block panel, click Refresh to populate the connection name in the drop-down list.
- From the Pick Your Service drop-down list, select the connection name.
- In the Response section, click Status Code and do the following:
- Enter the expected status code, which you can get from the API document.
The variable corresponding to the status code will be auto- generated. - Enter the response value field which includes the bot variable, response value, type, and data type.
- Click the Plus icon ( ) to add additional bot variables, if necessary.
- Click Save.
Click Add New Response to add another status code and their corresponding bot variables.
- Set a time for Request Timeout. Default time out is 8 seconds.
- Click Save on the webhook block.
- Click Save Draft on the flow to save your settings.
- Click the Preview button to check if the flow is working.
You can copy or delete the webhook block by clicking the respective button on the upper-right side of the block.
Custom Service
To create a completely new connection, perform the following steps: