Guides

Appointment reminders with Zoho Bookings

With these steps, Atendia calls each person to remind them of the appointment they booked in Zoho Bookings. You paste two texts into Zoho and create three workflows. The rest happens on its own. Atendia does not read your calendar: Zoho asks for each call.

Before you start

  • A Zoho Bookings plan that runs custom functions. Zoho's help says custom workflows are in the Premium plan. Zoho's trial period lets you use them.
  • An Atendia agent with a number, to make the reminder calls.
  • A «Read and calls» key just for this, named «Zoho Bookings». Create it in the console, in «Settings» → «API keys» → «New API key». Copy the key when the console shows it: it appears only once.
  • The agent's id. Open the agent's page in the console: the id is the part of the address after /agents/.

The text to paste

There are two texts. Both have the same two spaces to fill, in square brackets. Replace each one with your value: delete the square brackets too, and keep the quotes.

  • [paste the key here]: the «Zoho Bookings» key, copied when the console showed it. It appears only once. If you lost it, create a new key and revoke the old one.
  • [paste the agent id here]: the part of the agent page's address after /agents/.
  • Paste the key only in [paste the key here], in both texts.

If the «Copy» button does not copy, select the whole text and copy it by hand.

Text 1: ask for the reminder

For the reminder workflow, the one that runs before the appointment («Appointment started», «Before»).

deluge
// Atendia: asks for the reminder call of this booking.
chaveAtendia = "[paste the key here]";
agente = "[paste the agent id here]";
telefone = ifnull(bookingInfo.get("customer_contact_no"),"").trim();
if(telefone == "")
{
	info "Atendia: booking with no phone, no call asked for.";
}
else
{
	marcacao = bookingInfo.get("booking_id").replaceAll("#","");
	inicio = bookingInfo.get("iso_start_time");
	nome = ifnull(bookingInfo.get("customer_name"),"").replaceAll("[^\p{L} '-]","").trim();
	if(nome.length() > 60)
	{
		nome = nome.subString(0,60);
	}
	variaveis = Map();
	variaveis.put("nome",nome);
	variaveis.put("data_consulta",bookingInfo.get("start_time"));
	corpo = Map();
	corpo.put("agentId",agente);
	corpo.put("phoneNumber",telefone);
	corpo.put("reference","zoho-" + marcacao);
	corpo.put("notAfter",inicio);
	corpo.put("dynamicVariables",variaveis);
	cabecalhos = Map();
	cabecalhos.put("Content-Type","application/json");
	cabecalhos.put("x-api-key",chaveAtendia);
	cabecalhos.put("Idempotency-Key","zoho-" + marcacao + "-" + inicio);
	resposta = invokeurl
	[
		url :"https://api.atendia.pt/api/v1/outbound-calls"
		type :POST
		parameters:corpo.toString()
		headers:cabecalhos
		detailed:true
	];
	codigo = resposta.get("responseCode");
	if(codigo == 200 || codigo == 201)
	{
		info "Atendia: call asked for (" + codigo + ").";
	}
	else
	{
		info "Atendia: ERROR " + codigo + " " + resposta.get("responseText");
	}
}

Text 2: cancel

For the «Canceled» and «Rescheduled» workflows. It is the same text in both.

deluge
// Atendia: cancels the calls of this booking that have not ended.
chaveAtendia = "[paste the key here]";
agente = "[paste the agent id here]";
marcacao = bookingInfo.get("booking_id").replaceAll("#","");
cabecalhos = Map();
cabecalhos.put("x-api-key",chaveAtendia);
procura = invokeurl
[
	url :"https://api.atendia.pt/api/v1/outbound-calls?limit=100&agentId=" + agente + "&reference=" + encodeUrl("zoho-" + marcacao)
	type :GET
	headers:cabecalhos
	detailed:true
];
if(procura.get("responseCode") != 200)
{
	info "Atendia: ERROR in the search " + procura.get("responseCode") + " " + procura.get("responseText");
}
else
{
	chamadas = procura.get("responseText").toString().toMap().get("data").get("items");
	for each chamada in chamadas
	{
		estado = chamada.get("status");
		if(estado == "SCHEDULED" || estado == "IN_PROGRESS")
		{
			id = chamada.get("outboundId");
			resposta = invokeurl
			[
				url :"https://api.atendia.pt/api/v1/outbound-calls/" + id + "/cancel"
				type :POST
				headers:cabecalhos
				detailed:true
			];
			codigo = resposta.get("responseCode");
			emCurso = false;
			if(codigo == 400)
			{
				detalhes = ifnull(resposta.get("responseText").toString().toMap().get("details"),Map());
				if(detalhes.get("furtherAttempts") == false)
				{
					emCurso = true;
				}
			}
			if(codigo == 200)
			{
				info "Atendia: cancelled " + id + ".";
			}
			else if(codigo == 404)
			{
				info "Atendia: not found " + id + ".";
			}
			else if(emCurso)
			{
				info "Atendia: in progress, ends with no more attempts: " + id + ".";
			}
			else
			{
				info "Atendia: ERROR " + id + " " + codigo + " " + resposta.get("responseText");
			}
		}
	}
}

The steps in Zoho

Zoho Bookings can show its menus in Portuguese or in English. Where we could not check the English name, the step gives the Portuguese name in quotes, with a translation. You create three workflows: the reminder, «Canceled» and «Rescheduled».

  1. In Zoho Bookings, switch to your workspace: «COMUTAR ÁREAS DE TRABALHO» (switch workspaces) → your workspace. The workflows do not show in «O meu espaço» (my space).
  2. Open «Workflows», in the side bar, and the «Fluxos de trabalho personalizados» tab (custom workflows). There, click «Criar fluxo de trabalho» (create workflow) and, on the templates screen, «Criar novo fluxo de trabalho» (create a new workflow).
  3. Reminder workflow: in «Trigger When», choose «Appointment started». In «Occurrence», choose «Before», a number and minutes or hours. That is how early the reminder comes.
  4. In «Perform Action», choose «Execute custom functions».
  5. Click «Customize», paste text 1 with your two values and click «Save».
  6. Click «Create Workflow». Without customizing the template, Zoho refuses to create the workflow.
  7. Create a second workflow: in «Trigger When», «Canceled»; in «Occurrence», «Immediately»; the same action, with text 2.
  8. Create a third workflow like the second, with «Rescheduled» in «Trigger When».
  9. To change a text later, reload the page and open the workflow from the list. The editor Zoho reopens on its own after «Create Workflow» does not save changes.

The cancel text is always needed. When an appointment is cancelled or rescheduled, the call may already exist: waiting for a new attempt, a booked callback, or in progress. Without this workflow, it leaves anyway. On a reschedule, the reminder workflow runs only at the new time and asks for a new call.

Test

  1. Make a test booking for your own mobile phone, with the appointment close, so the reminder comes a few minutes later. The booking must be made before the reminder time.
  2. Careful: «Execute» does what the text does, for real. On text 1, it asks for a real call. On text 2, «Execute» cancels the real calls of that booking that have not ended. Use only the test booking. To avoid waiting, open the function of text 1 and click «Execute». Zoho asks for the Booking ID: it is the booking code without the «#», for example AT-00007. With the «#», Zoho answers «Forneça uma id de marcação válida» (give a valid booking id). The info lines show in «Mensagens de registo» (log messages).
  3. «Execute» runs the saved version of the function, not the text open in the editor. Always save before testing.
  4. In the console, look for the reference zoho- and the booking code in the call history. There should be one line.
  5. Reschedule the appointment. The reminder workflow does not run at the old time: it runs only at the new time, and a new line appears.
  6. Cancel the appointment. If a call was still to leave, it is cancelled. If the reminder had not run yet, there is no call at all, and that is right.
What the texts do and the agent options

What the texts do

  • They call the phone as Zoho stores it: +351 and the number, with no spaces. Zoho stores it that way even if you type it with spaces.
  • They set «do not call after» (notAfter) to the appointment time. The call never leaves after the appointment starts.
  • They give the call the reference zoho- and the booking code, without the «#». Zoho writes the code as #AT-00007; the reference becomes zoho-AT-00007. You find the call in the history by it.
  • They send a repeated-request mark (Idempotency-Key) made of the booking code and the appointment time. The same Zoho notice, repeated, does not create two calls. A rescheduled appointment has another time, so it is not mixed up with the old one.
  • They send two variables: nome, the person's name, and data_consulta, the appointment date and time, as Zoho writes them. Use them in the agent's instructions. The text does not send the service name: it can tell the reason for the appointment, which is health data.
  • A booking with no phone asks for no call.
  • Neither does a booking made after the reminder time: Zoho does not run the workflow. The person has just booked.
  • The cancel text finds the calls by the exact reference and by the agent. It cancels only those that have not ended: the «Scheduled» ones and the one in progress. A call that no longer exists (404) counts as done. The one in progress ends normally, with no more attempts and no callback, and also counts as done.
  • Each Atendia answer goes into an info line. Only «Execute» in the Zoho editor shows those lines (see «What a failure looks like»).

How to cancel a call through the API

Agent options that help with reminders

They are not needed, but they help. The second one is already in the text. The others are in the console, in «Outbound rules», on the agent's page.

  • The agent's calling hours: a reminder asked for outside them waits for the next opening. Learn more
  • «Do not call after»: the text sets it at the appointment time. A waiting call never leaves after that time; if it passes, the call becomes «Failed». Learn more
  • «New attempt»: if nobody answers, Atendia calls again later, always before the deadline. Learn more
  • Voicemail: the agent can leave a message. Do not put the reason for the appointment or any other health data in it. Learn more
  • «Call me later»: the person asks to be called later, and the callback is booked, always before the deadline. Learn more

The Builder helps you write the instructions of a reminder agent. Do not put the reason for the appointment or any other health data in them.

The Builder

What a failure looks like

Zoho's audit log says the workflow was «executado» (executed) even when Atendia refuses the request (401, 403). Zoho does not show the failure. You see the failure in two places:

  • In «Execute» in the function editor: the log messages show the code, for example Atendia: ERROR 401.
  • In Atendia's call history: with no line carrying the booking's reference, Zoho did not reach Atendia.

Common errors

  • Wrong or revoked key: 401 UNAUTHORIZED.
  • «Read only» key: 403 API_KEY_CANNOT_CALL. Create a «Read and calls» key.
  • Wrong agent: the id is not an agent of this account. Copy it again from the address of the agent's page.
  • Phone with no country code: type the phone in Zoho with the country chosen.
  • Text changed for the same booking: the repeated request with different data gets 409 IDEMPOTENCY_KEY_REUSED.
  • A «Failed» line in the history shows the reason.
  • A cancelled call shows as «Cancelled» (FAILED, reason cancelled).
  • If the appointment time passes while the call waits, it no longer leaves: it shows as «Failed», with the reason «Past the deadline» (FAILED, reason deadline_passed).

All the refusal codes · All the failure reasons

Undo

  1. In Zoho, turn off (or delete) the three workflows: the reminder, «Canceled» and «Rescheduled».
  2. In the console, revoke the «Zoho Bookings» key in «API keys». If calls are still to leave, the console asks whether to cancel or keep them.

Warnings

  • The key is written in Zoho. Whoever administers Zoho can see it.
  • A «Read and calls» key asks for calls, paid from the account's credit. It also reads the account's data: the call history and transcripts, the agents' settings and billing. That is why you use a key just for Zoho.
  • When someone who administered Zoho leaves the company, change the key: create a new one, paste it into the three workflows and revoke the old one.
  • Revoking the key stops the reminders, with no warning. Check the call history now and then.
  • Two bookings for the same phone give two calls.
  • A calls key of the account can cancel any call asked for by a key of that account. The text is what filters by the agent and the reference: do not take that filter out.
  • An appointment rescheduled back to its old time, up to 24 hours after the old call ended, reuses the old request: no new call leaves. An appointment rescheduled to inside the reminder lead time gets no reminder: Zoho does not run the workflow.
  • The name (nome) is typed by whoever books, on Zoho's public page. That is why text 1 cleans it: it keeps only letters, spaces, hyphens and apostrophes, up to 60 characters.