Transform API Responses with Formatter in Guided Conversations | Zoho Desk

Formatter (Deluge) in Webhook Block

Not all API responses come in the exact format you want to show to your users, and that’s where Formatter comes in. With Formatter, you can use Deluge scripting to transform your raw API response into clean, user-friendly content that fits your use case perfectly.
 
Let’s say your API returns a complex object or sends data with field names that aren’t helpful to your chatbot audience. Maybe the date format looks like this: 2025-06-02T10:45:00Z; but you want it to display as “2 June 2025, 10:45 AM.” Or perhaps your API returns a ticket object with ticket_subject and ticket_id, but you want to display something more readable like Issue #2034 - Payment failed.

Learn more about webhooks: Introduction to Webhook Block in GC 
​

What is Formatter?

Formatter is a feature inside the Webhook Block of Guided Conversations. After your webhook pulls in data from an API, Formatter lets you modify that data before passing it on in the conversation.
You can:
  1. Change field names to make them more meaningful
  2. Reformat date and time values
  3. Merge values from multiple fields
  4. Extract specific items from nested JSON
  5. Loop through lists to create summaries or readable content
 All of this is done using Deluge. Even if you’re not a professional developer, Deluge makes these transformations easy to implement. 
 


Why Formatter is useful  

Think of Formatter as your data-cleaning assistant.
Here’s why it matters:
  1. Makes API responses more readable for end users
  2. Avoids confusing terms like “ticket_id” or “cust_name”
  3. Helps structure content to match your tone or formatting
  4. Lets you show only what’s important and hide the rest
  5. Works seamlessly with other parts of the Guided Conversation flow 
 In short, Formatter helps you speak your user’s language, not your system’s. 
 

Example Use Cases   

Reformatting Date and Time

API Response:

 { 
   "order_date": "2025-06-02T10:45:00Z" 
 } 

Goal: Display it as "2 June 2025, 10:45 AM"

Formatter Code:

 formatted_date = order_date.toDateTime("yyyy-MM-dd'T'HH:mm:ss'Z'").toString("d MMMM yyyy, h:mm a"); 
 return {"formatted_date": formatted_date};   

Bot Response:

Your order was placed on 2 June 2025, 10:45 AM.

Use the return keyword to pass values to the next block. Info is for debugging only. Returning a string wraps it in a list, so return a map for cleaner handling.  
Renaming Fields

API Response:

 { 
   "cust_name": "Talaash Thedal" 
 }  

Goal: Rename "cust_name" to "Customer Name"
 

Formatter Code:

 customer_name = cust_name; 
 return {"customer_name": customer_name}; 

Bot Response:

Customer Name: Talaash Thedal
 
Renaming field keys in Formatter doesn’t affect variable names in other blocks. Only webhook-mapped variables can be referenced directly in the conversation flow. 
Merging Field Values

API Response:

 { 
   "ticket_id": "2034", 
   "ticket_subject": "Payment failed" 
 } 

Goal: Show as “Issue #2034 - Payment failed”

 

Formatter Code: 

 issue_summary = "Issue #" + ticket_id + " - " + ticket_subject; 
 return {"issue_summary": issue_summary}; 

  

Bot Response:

Issue #2034 - Payment failed

Extracting from Nested Objects

API Response: 

 { 
   "user": { 
     "details": { 
       "contact": { 
         "email": "aarav@example.com" 
       } 
     } 
   } 
 } 

Goal: Get just the user’s email

 

Formatter Code:

 email_id = user.get("details").get("contact").get("email"); 
 return {"email_id": email_id}; 

Bot Response:

Contact Email: talaash@gmail.com

Looping through Arrays

​API Response: 

 { 
   "recent_orders": [ 
     { "order_id": "123", "status": "Delivered" }, 
     { "order_id": "124", "status": "Processing" } 
   ] 
 } 

Goal: Show a list like:

  • Order #123 - Delivered

  • Order #124 - Processing

 

Formatter Code:

 orders = recent_orders; 
 summary = ""; 
 for each order in orders 
 { 
   summary += "Order #" + order.get("order_id") + " - " + order.get("status") + "\n"; 
 } 
 return {"order_summary": summary};   
 

Bot Response:

  • Order #123 - Delivered

  • Order #124 - Processing

   

Extracting specific items from Nested JSON   

Let’s say your API returns a list of departments, but you only want to display the default ones.

​
Extract from Nested JSON
Extract from Nested JSON
Let’s say your API returns a list of departments, but you only want to display the default ones.
 
API Response
 { 
   "data": [ 
     { 
       "name": "Support", 
       "isDefault": false 
     }, 
     { 
       "name": "Sales", 
       "isDefault": true 
     } 
   ] 
 } 

Goal: Extract only the departments where "isDefault": true

Formatter Code:
 // Create an empty collection to store departments that match our condition 

 result = Collection();   
 // Get the list of all departments from the response data 
 allDepartments = response.get("data");   
 // Go through each department one by one from the list 
 for each department in allDepartments 

 
{ 
     // Check if this department is marked as the 'default' department 
     isDefault = department.get("isDefault");   
     // If the department is the default one, add it to our result collection 
     if(isDefault == true) 
     { 
         result.insert(department); 
     } 
 }  
 
 // Return the final list of default departments 
 return result; 

Bot response
Default Department: Sales

You can use this returned result in the next block to extract a specific field-like name from the department object.
 

Tips

  1. Always check the structure of your API’s JSON response; it helps to know what you’re working with.
  2. Use the info statement in Deluge to debug your code and preview values.
  3. Use Formatter right after the Webhook block so the response is ready for the next message block.
  4. Combine Formatter with Conditions and Variables to build powerful, dynamic conversations.
​
Learn more about webhooks: Introduction to Webhook Block in GC