Zoho Books: Estimates/Quotes: Accept & Decline Buttons on Template

: Joel Lipman; Zoho; 04 November 2024; Hits: 756

What?
An article on adding an accept and decline button on the estimate (aka Quote) notification template within ZohoBooks.

Why?
The use-case is simply that my client wants to make it easier for their customers to accept or decline a quote. Sure there's a portal and you can probably do it from there but this is a one-click accept or decline then done.

One of the biggest hurdles here, which may sound trivial, was the response when an end customer clicks on either the accept or decline button. Using ZohoFlow or other Zoho app for a webhook response, would result in the end customer suddenly downloading a JSON file. Looked a bit suspicious. The code below opens a new tab in their web-browser displaying a plain output message.

How?
So there are 2 caveats to this solution: 1 is that you will need ZohoCRM. I've tried using the "Incoming Webhooks" feature of ZohoBooks but realised the word "Incoming" is the operative word as the response cannot be configured in ZohoBooks like we need to in this solution; namely the webhook response needs to have a header and a body.

The 2nd caveat is a concern around security. It is difficult to guess a customer's Zoho ID; some might say almost impossible. To use other fields that could be sent via the URL as a verification to be checked at the webhook endpoint would be good as well; but I couldn't spend time finding fields that can be 'placeheld', other than what the interface offers, into the template.

the CRM webhook API function
So let's do my favorite method of creating a REST API function in CRM

Login to ZohoCRM > Setup > Functions > New Function
Give it a function name, I'm calling mine fn_ZohoBooks_Estimates_AcceptDecline with the parameters: p_Intent (string), p_QuoteRef (string), p_CxID (string)
The display name I'm giving it is Fn - ZohoBooks - Estimates - Accept/Decline
It's a standalone function

I'll give it the following code (amend the org ID and connection name):

copy raw

//
// initialize
b_ValidResponse = false;
v_EstimateID = "-";
v_OrgId = "123456789";
v_Output = "Unable to process request";
//
// evaluate
v_Intent = ifnull(input.p_Intent,"-");
v_QuoteRef = ifnull(input.p_QuoteRef,"-");
v_CustomerID = ifnull(input.p_CxID,"-");
//
// Search ZohoBooks estimates for the quote reference and validate by the contact Zoho ID
if(v_QuoteRef != "-")
{
	r_SearchResults = zoho.books.getRecords("estimates",v_OrgId,"estimate_number=" + v_QuoteRef,"my_books_connection");
	if(r_SearchResults.get("code") == 0)
	{
		l_SearchResults = r_SearchResults.get("estimates");
		for each  m_Estimate in l_SearchResults
		{
			if(m_Estimate.get("estimate_number").equalsIgnoreCase(v_QuoteRef))
			{
				if(m_Estimate.get("customer_id") == v_CustomerID)
				{
					v_EstimateID = m_Estimate.get("estimate_id");
				}
			}
		}
	}
}
//
// accept or decline
if(v_EstimateID != "-")
{
	if(v_Intent == "Accept")
	{
        b_ValidResponse = true;
		//
		// Mark the estimate as accepted
		r_Accept = invokeurl
		[
			url :"https://www.zohoapis.com/books/v3/estimates/" + v_EstimateID + "/status/accepted?organization_id=" + v_OrgId
			type :POST
			connection:"my_books_connection"
		];
		v_OutputResponse = "Thank you for accepting your quote!  We'll be in touch soon to finalize the next steps and get everything ready.";
	}
	else if(v_Intent == "Decline")
	{
        b_ValidResponse = true;
		//
		// Mark the estimate as declined
		r_Decline = invokeurl
		[
			url :"https://www.zohoapis.com/books/v3/estimates/" + v_EstimateID + "/status/declined?organization_id=" + v_OrgId
			type :POST
			connection:"my_books_connection"
		];
		v_OutputResponse = "We're sorry to see you decline the quote, but we're here if you change your mind.";
	}
}
//
// push a response so when clicked, it loads up a page in a browser (redirect from a zoho page)
if(b_ValidResponse)
{
    //
    // generate HTML page when clicked (please amend the following variables)
    v_CompanyName = "Joel Lipman Ltd";
    v_CompanyStrapline = "The One and Only";
    v_CompanyURL = "https://www.joellipman.com";
    v_LogoURL = v_CompanyURL + "/images/logos/logo.png";
    //
    // create a HTML message to display
	v_BodyHTML = "<html><head><title>";
	v_BodyHTML = v_BodyHTML + v_CompanyName + "</title><script>window.history.pushState({},'','/thank-you');</script>";
	v_BodyHTML = v_BodyHTML + "<link rel=\"preconnect\" href=\"https://fonts.googleapis.com\" /><link rel=\"preconnect\" href=\"https://fonts.gstatic.com\" crossorigin /><link href=\"https://fonts.googleapis.com/css2?family=Poppins:ital,wght@0,100;1,100&display=swap\" rel=\"stylesheet\" /><style>body{font-family:'Poppins', sans-serif;}</style></head><body><div style=\"display:flex;flex-wrap:wrap;justify-content:center;align-content:center;height:100%;width:100%;\"><center><a href=\"";
	v_BodyHTML = v_BodyHTML + v_CompanyURL + "\"><img src=\"" + v_LogoURL;
	v_BodyHTML = v_BodyHTML + "\" style=\"max-width:215px;border:0;\" /></a><br /><span>" + v_CompanyStrapline + "</span><br /><h2 style=\"font-weight:100;max-width:400px;\">" + v_OutputResponse + "</h1></center></div></body></html>";    
    //
    // output to new browser tab
	m_Response = Map();
	m_Response.put("Content-Type","text/html");
	m_Response.put("status_code",200);
	m_Header = Map();
	m_Header.put("Content-Disposition","inline;");
	m_Response.put("headers",m_Header);
	m_Response.put("body",v_BodyHTML);
}
else
{
    //
    // could put a 403 but it's if there was an invalid request.  Here we're not really responding with anything
	m_Response = Map();
	m_Response.put("status_code",200);
}
//
// return webhook response
return {"crmAPIResponse":m_Response};

//
// initialize
b_ValidResponse = false;
v_EstimateID = "-";
v_OrgId = "123456789";
v_Output = "Unable to process request";
//
// evaluate
v_Intent = ifnull(input.p_Intent,"-");
v_QuoteRef = ifnull(input.p_QuoteRef,"-");
v_CustomerID = ifnull(input.p_CxID,"-");
//
// Search ZohoBooks estimates for the quote reference and validate by the contact Zoho ID
if(v_QuoteRef != "-")
{
r_SearchResults = zoho.books.getRecords("estimates",v_OrgId,"estimate_number=" + v_QuoteRef,"my_books_connection");
if(r_SearchResults.get("code") == 0)
{
l_SearchResults = r_SearchResults.get("estimates");
for each m_Estimate in l_SearchResults
{
if(m_Estimate.get("estimate_number").equalsIgnoreCase(v_QuoteRef))
{
if(m_Estimate.get("customer_id") == v_CustomerID)
{
v_EstimateID = m_Estimate.get("estimate_id");
}
}
}
}
}
//
// accept or decline
if(v_EstimateID != "-")
{
if(v_Intent == "Accept")
{
b_ValidResponse = true;
//
// Mark the estimate as accepted
r_Accept = invokeUrl
[
url :"https://www.zohoapis.com/books/v3/estimates/" + v_EstimateID + "/status/accepted?organization_id=" + v_OrgId
type :POST
connection:"my_books_connection"
];
v_OutputResponse = "Thank you for accepting your quote! We'll be in touch soon to finalize the next steps and get everything ready.";
}
else if(v_Intent == "Decline")
{
b_ValidResponse = true;
//
// Mark the estimate as declined
r_Decline = invokeUrl
[
url :"https://www.zohoapis.com/books/v3/estimates/" + v_EstimateID + "/status/declined?organization_id=" + v_OrgId
type :POST
connection:"my_books_connection"
];
v_OutputResponse = "We're sorry to see you decline the quote, but we're here if you change your mind.";
}
}
//
// push a response so when clicked, it loads up a page in a browser (redirect from a zoho page)
if(b_ValidResponse)
{
//
// generate HTML page when clicked (please amend the following variables)
v_CompanyName = "Joel Lipman Ltd";
v_CompanyStrapline = "The One and Only";
v_CompanyURL = "https://www.joellipman.com";
v_LogoURL = v_CompanyURL + "/images/logos/logo.png";
//
// create a HTML message to display
v_BodyHTML = "<html><head><title>";
v_BodyHTML = v_BodyHTML + v_CompanyName + "</title><script>window.history.pushState({},'','/thank-you');</script>";
v_BodyHTML = v_BodyHTML + "<link rel=\"preconnect\" href=\"https://fonts.googleapis.com\" /><link rel=\"preconnect\" href=\"https://fonts.gstatic.com\" crossorigin /><link href=\"https://fonts.googleapis.com/css2?family=Poppins:ital,wght@0,100;1,100&display=swap\" rel=\"stylesheet\" /><style>body{font-family:'Poppins', sans-serif;}</style></head><body><div style=\"display:flex;flex-wrap:wrap;justify-content:center;align-content:center;height:100%;width:100%;\"><center><a href=\"";
v_BodyHTML = v_BodyHTML + v_CompanyURL + "\"><img src=\"" + v_LogoURL;
v_BodyHTML = v_BodyHTML + "\" style=\"max-width:215px;border:0;\" /></a><br /><span>" + v_CompanyStrapline + "</span><br /><h2 style=\"font-weight:100;max-width:400px;\">" + v_OutputResponse + "</h1></center></div></body></html>";
//
// output to new browser tab
m_Response = Map();
m_Response.put("Content-Type","text/html");
m_Response.put("status_code",200);
m_Header = Map();
m_Header.put("Content-Disposition","inline;");
m_Response.put("headers",m_Header);
m_Response.put("body",v_BodyHTML);
}
else
{
//
// could put a 403 but it's if there was an invalid request. Here we're not really responding with anything
m_Response = Map();
m_Response.put("status_code",200);
}
//
// return webhook response
return {"crmAPIResponse":m_Response};

Once saved, I'll hover the mouse over it and click on the ellipsis to select REST API option. Then make a note of the URL.

the ZohoBooks Estimate Template
Now you need to add a couple of buttons to the estimate template in ZohoBooks

Login to ZohoBooks > Settings > Email Notifications > Estimate Notification
Many ways to add a button but here's how I do it (requires some basic HTML/CSS knowledge):
1. Place the cursor where you want the button and give it some text, I'm going to start with Accept Quote
2. Then click on the link icon and give it the link noted from the URL made earlier (the one to the CRM REST API function):
  copyrawstyler
```
// should be something like
<my_rest_api_function_url>&p_Intent=Accept&p_QuoteRef=%EstimateNumber%&p_CxID=%CustomerID%
```
  1. // should be something like
  2. <my_rest_api_function_url>&p_Intent=Accept&p_QuoteRef=%EstimateNumber%&p_CxID=%CustomerID%
  Then press OK to save the link
3. Now click on the HTML icon, and find your link, then add the necessary CSS to make it look like a button (I'll tend to repeat what was done to the default "View Estimate" button).
Repeat this to place the decline button, ensuring you change the link's p_Intent value to Decline:
copyrawstyler
```
// should be something like
<my_rest_api_function_url>&p_Intent=Decline&p_QuoteRef=%EstimateNumber%&p_CxID=%CustomerID%
```
1. // should be something like
2. <my_rest_api_function_url>&p_Intent=Decline&p_QuoteRef=%EstimateNumber%&p_CxID=%CustomerID%

When the end customer clicks on either button in their email (at least in a web-based email client such as outlook or Gmail), they should get something like the following: