Medical Center Sending Reminders and Notifications
Story
The ABC Health Center is looking for a solution to introduce automatic voice and text reminders for their patients.
A voice reminder should give the recipient the date of an upcoming appointment and ask them to confirm that date or reschedule it.
If the patient decides to reschedule an appointment, he should be transferred to a Health Center representative. A short text
reminder is a simple form of notification; in this case, the patient receives a text message with the date of an upcoming
appointment.
Overview
Reminders are a popular use case of the CallFire platform, and our API provides different ways of delivering voice or text information to recipients through an individual message or else broadcast as a single message to a number of recipients. This article shows how to use Send Calls and Send Texts APIs to send out individual reminders.
How to Send an Individual Templated Text Message
To send an individual text to a recipient, you should use Send Texts API. You can provide a message template like "Hello ${username} !" and the list of key-value pairs (called recipient's attributes) which will fill in variables in the pattern. Also, you can add to those attributes any client-specific information. In case you have multiple recipients with the same message, you can provide a defaultMessage instead of duplicating it to each recipient.
Note that the default text broadcast sends out text messages from CallFire's shared shortcode 67076.
The following code examples show how to send an individual text through a default broadcast:
[[code-container]] [+curl] request:
#!/usr/bin/env bash
curl -u username:password -H "Content-Type:application/json" -X POST -d '
[
{
"phoneNumber":"12135551100",
"message":"Hello ${contact_name}, you have an appointment with Dr. Andrew tomorrow at 3:00 PM, if you need to reschedule please call (855)-555-4477",
"attributes":
{
"contact_name":"Alice",
"external_user_id":"45450007002"
}
}
]' "https://api.callfire.com/v2/texts"{
"items": [
{
"id": 13413,
"fromNumber": "67076",
"toNumber": "12135551123",
"state": "READY",
"campaignId": 20,
"batchId": 14,
"contact": {
"id": 4096,
"homePhone": "12135551123"
},
"labels": [
"reminders"
],
"attributes": {
"contact_name":"Alice",
"external_user_id":"45450007002"
},
"inbound": false,
"created": 1443403042000,
"modified": 1443403042000,
"message": "Hello Alice, you have an appointment with Dr. Andrew tomorrow at 3:00 PM, if you need to reschedule please call (855)-555-4477"
}
]
}import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.callstexts.model.Text;
import com.callfire.api.client.api.campaigns.model.TextRecipient;
import java.util.Arrays;
import java.util.List;
class ApiClientSample {
public static void main(String[] args) {
CallfireClient client = new CallfireClient("api_login", "api_password");
TextRecipient recipient = new TextRecipient();
recipient.setPhoneNumber("12135551100");
recipient.setMessage("Hello ${contact_name}, you have an appointment with Dr. Andrew "
+ "tomorrow at 3:00 PM, if you need to reschedule please call (855)-555-4477");
// Set custom attribute
recipient.getAttributes().put("external_user_id", "45450007002");
recipient.getAttributes().put("contact_name", "Alice");
List<TextRecipient> recipients = Arrays.asList(recipient);
List<Text> texts = client.textsApi().send(recipients);
}
}using System.Collections.Generic;
using CallfireApiClient;
using CallfireApiClient.Api.CallsTexts.Model;
public class ApiClientSample
{
public static void Main(string[] args)
{
var client = new CallfireClient("api_login", "api_password");
var recipient1 = new TextRecipient
{
Message = "Hello ${contact_name}, you have an appointment with Dr. Andrew "
+ "tomorrow at 3:00 PM, if you need to reschedule please call (855)-555-4477",
PhoneNumber = "12135551100",
// set custom recipient attributes, they are available only to a single Call/Text
// action, do not confuse them with contact fields which are stored with contact
// and are available to each Call/Text where contact is attached to
Attributes = new Dictionary<string, string>
{
{"contact_name", "Alice"},
{"external_user_id", "45450007002"}
}
};
IList<Text> texts = client.TextsApi.Send(new List<TextRecipient> {recipient1});
}
}'strict'
const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');
client.ready(() => {
client.texts.sendTexts({
body: [
{
phoneNumber: '12135551100',
message: 'Hello ${contact_name}, you have an appointment with Dr. Andrew tomorrow at 3:00 PM, if you need to reschedule please call (855)-555-4477',
attributes: {
contact_name: 'Alice',
external_user_id: '45450007002'
}
}
]
})
.then((response) => {
console.log(response.obj);
})
.catch((err) => {
console.log('request error ' + err.data);
});
},
(clientError) => {
console.log('client error ' + clientError);
}
);from callfire.client import CallfireClient
client = CallfireClient('api-login', 'api-password')
response = client.texts.sendTexts(
body=[
{
'phoneNumber': '12135551100',
'message': 'Hello ${contact_name}, you have an appointment with Dr. Andrew tomorrow at 3:00 PM, if you need to reschedule please call (855)-555-4477',
'attributes': {
'contact_name': 'Alice',
'external_user_id': '45450007002'
}
}
]
).result()
# see sample JSON response for this API
# on 'curl' samples tab
print(response)<?php
class ApiClientSample {
public static function main() {
$client = \CallFire\Api\DocumentedClient::createClient("login", "password");
$request = $client->sendTexts();
$body = '[
{
"phoneNumber":"12135551100",
"message":"Hello ${contact_name}, you have an appointment with Dr. Andrew tomorrow at 3:00 PM, if you need to reschedule please call (855)-555-4477",
"attributes":
{
"contact_name":"Alice",
"external_user_id":"45450007002"
}
}
]';
$request->getOperationConfig()->setBodyParameter($body);
$result = $client->request($request);
$json = json_decode($result->getBody());
}
}
ApiClientSample::main();Refer to Send Texts API reference for detailed information about request type, parameters, and responses.
How to Send an Individual Voice Message and Record User's Response
To create a voice reminder for a given use case, you need to prepare an IVR XML dialplan. The term IVR stands for Interactive Voice Response. An IVR provides a more advanced call configuration. You can ask questions through pre-recorded or auto-voice prompts, receive response via a phone pad key-press, and/or transfer to a specific phone number depending on a user's responses. Let's see how an IVR XML dialplan will look like with the following requirements:
- Play a reminder text and ask to press 1 to confirm the appointment time or press 2 to reschedule it.
- If 1, stash 'selected_menu' variable with value = 'confirmed', then play bye message and hang up.
- If 2, stash 'selected_menu' variable with value = 'reschedule', then transfer recipient to another number, e.g. 15550005500
- If any other button is pressed , play an incorrect selection message, then go to 1.
IVR XML dialplan:
<dialplan name="Root">
<menu maxDigits="1" timeout="3500" name="Live">
<play type="tts" voice="female1">
Hello, this is UMM Health Center, you have an appointment with Dr. Andrew
tomorrow at 3:00 PM, please press 1 to confirm the time or press 2 to reschedule
appointment.
</play>
<keypress pressed="1">
<!-- user pressed 1, store this data in 'selected_menu' variable -->
<stash varname="selected_menu">confirmed</stash>
<goto>bye_tts</goto>
</keypress>
<keypress pressed="2">
<!-- user pressed 2, store this data in 'selected_menu' variable -->
<stash varname="selected_menu">reschedule</stash>
<play type="tts" voice="female1">
You will be transferred to our representative to reschedule an appointment. Please wait.
</play>
<transfer callerid="${call.callerid}" musiconhold="blues" mode="ringall">
15550005500
</transfer>
</keypress>
<!-- if pressed key is not specified in menu replay Live menu -->
<keypress pressed="default" name="incorrect_Selection">
<play type="tts" voice="female1">That is not a valid selection. Please try again.</play>
<goto name="replay_Live">Live</goto>
</keypress>
</menu>
<play type="tts" voice="female1" name="bye_tts">
Thank you for your response. Have a good day.
</play>
<hangup name="Hangup"/>
</dialplan>You can find more information about the IVR on CallFire Answers Page also different IVR examples are available on our public Github repository.
Check the CallFire XML page for a detailed description of all IVR tags.
Once you prepare a dialplan, you can use Send Calls API to send an IVR call to a particular recipient or a number of recipients. The recipient can be a simple phone number in E.164 format or, in the case of international numbers, in E.123 format, or a contact already in the CallFire system.
The following code examples show how to send an individual IVR call through the default broadcast:
[[code-container]] [+curl] request:
#!/usr/bin/env bash
curl -u username:password -H "Content-Type:application/json" -X POST -d '
[
{
"phoneNumber":"12135551100",
"attributes":
{
"external_user_id":"45450007002"
},
"dialplanXml":"<dialplan name=\"Root\"> <menu maxDigits=\"1\" timeout=\"3500\" name=\"Live\"> <play type=\"tts\" voice=\"female1\"> Hello, this is UMM Health Center, you have an appointment with Dr. Andrew tomorrow at 3:00 PM, please press 1 to confirm the time or press 2 to reschedule appointment. </play> <keypress pressed=\"1\"> <stash varname=\"selected_menu\">confirmed</stash> <goto>bye_tts</goto> </keypress> <keypress pressed=\"2\"> <stash varname=\"selected_menu\">reschedule</stash> <play type=\"tts\" voice=\"female1\"> You will be transferred to our representative to reschedule an appointment. Please wait. </play> <transfer callerid=\"${call.callerid}\" musiconhold=\"blues\" mode=\"ringall\"> 15550005500 </transfer> </keypress> <keypress pressed=\"default\" name=\"incorrect_Selection\"> <play type=\"tts\" voice=\"female1\">That is not a valid selection. Please try again.</play> <goto name=\"replay_Live\">Live</goto> </keypress> </menu> <play type=\"tts\" voice=\"female1\" name=\"bye_tts\"> Thank you for your response. Have a good day. </play> <hangup name=\"Hangup\"/> </dialplan> "
}
]' "https://api.callfire.com/v2/calls"{
"items": [
{
"id": 13394,
"fromNumber": "12135551189",
"toNumber": "12135551100",
"state": "READY",
"campaignId": 10,
"batchId": 6,
"contact": {
"id": 4096,
"homePhone": "12135551100"
},
"labels": [
"reminders"
],
"attributes": {
"external_user_id":"45450007002"
},
"inbound": false,
"created": 1443373382000,
"modified": 1443373382000,
"agentCall": false
}
]
}import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.callstexts.model.Call;
import com.callfire.api.client.api.callstexts.model.CallRecipient;
import com.callfire.api.client.api.callstexts.model.request.SendCallsRequest;
import java.util.Arrays;
import java.util.List;
class ApiClientSample {
public static void main(String[] args) {
CallfireClient client = new CallfireClient("api_login", "api_password");
CallRecipient r1 = new CallRecipient();
r1.setPhoneNumber("12135551100");
r1.setDialplanXml(buildDialplanXml());
r1.getAttributes().put("external_user_id", "45450007002");
List<CallRecipient> recipients = Arrays.asList(r1);
SendCallsRequest request = new SendCallsRequest().create()
.recipients(recipients)
.build();
List<Call> calls = client.callsApi().send(request);
}
private static String buildDialplanXml() {
return
"<dialplan name=\"Root\"> "
+ " <menu maxDigits=\"1\" timeout=\"3500\" name=\"Live\"> "
+ " <play type=\"tts\" voice=\"female1\"> "
+ " Hello, this is UMM Health Center, you have an appointment with Dr. Andrew "
+ " tomorrow at 3:00 PM, please press 1 to confirm the time or press 2 to reschedule "
+ " appointment. "
+ " </play> "
+ " <keypress pressed=\"1\"> "
+ " <!-- user pressed 1, store this data in 'selected_menu' variable --> "
+ " <stash varname=\"selected_menu\">confirmed</stash> "
+ " <goto>bye_tts</goto> "
+ " </keypress> "
+ " <keypress pressed=\"2\"> "
+ " <!-- user pressed 2, store this data in 'selected_menu' variable --> "
+ " <stash varname=\"selected_menu\">reschedule</stash> "
+ " <play type=\"tts\" voice=\"female1\"> "
+ " You will be transferred to our representative to reschedule an appointment. Please wait."
+ " </play> "
+ " <transfer callerid=\"${call.callerid}\" musiconhold=\"blues\" mode=\"ringall\"> "
+ " 15550005500 "
+ " </transfer> "
+ " </keypress> "
+ " <!-- if pressed key is not specified in menu replay Live menu --> "
+ " <keypress pressed=\"default\" name=\"incorrect_Selection\"> "
+ " <play type=\"tts\" voice=\"female1\">That is not a valid selection. Please try again.</play>"
+ " <goto name=\"replay_Live\">Live</goto> "
+ " </keypress> "
+ "</menu> "
+ "<play type=\"tts\" voice=\"female1\" name=\"bye_tts\"> "
+ " Thank you for your response. Have a good day. "
+ "</play> "
+ "<hangup name=\"Hangup\"/> "
+ "</dialplan> ";
}
}using System.Collections.Generic;
using CallfireApiClient;
using CallfireApiClient.Api.CallsTexts.Model;
using CallfireApiClient.Api.Common.Model.Request;
public class ApiClientSample
{
public static void Main(string[] args)
{
var client = new CallfireClient("api_login", "api_password");
var request = new SendCallsRequest()
{
Recipients = new List<CallRecipient> {
new CallRecipient {
PhoneNumber = "12135551100",
Attributes = new Dictionary<string, string> {
{"external_user_id", "45450007002"}
},
DialplanXml = @"
<dialplan name=""Root"">
<menu maxDigits=""1"" timeout=""3500"" name=""Live"">
<play type=""tts"" voice=""female1"">
Hello, this is UMM Health Center, you have an appointment with Dr. Andrew
tomorrow at 3:00 PM, please press 1 to confirm the time or press 2 to reschedule
appointment.
</play>
<keypress pressed=""1"">
<!-- user pressed 1, store this data in 'selected_menu' variable -->
<stash varname=""selected_menu"">confirmed</stash>
<goto>bye_tts</goto>
</keypress>
<keypress pressed=""2"">
<!-- user pressed 2, store this data in 'selected_menu' variable -->
<stash varname=""selected_menu"">reschedule</stash>
<play type=""tts"" voice=""female1"">
You will be transferred to our representative to reschedule an appointment. Please wait.
</play>
<transfer callerid=""${call.callerid}"" musiconhold=""blues"" mode=""ringall"">
15550005500
</transfer>
</keypress>
<!-- if pressed key is not specified in menu replay Live menu -->
<keypress pressed=""default"" name=""incorrect_Selection"">
<play type=""tts"" voice=""female1"">That is not a valid selection. Please try again.</play>
<goto name=""replay_Live"">Live</goto>
</keypress>
</menu>
<play type=""tts"" voice=""female1"" name=""bye_tts"">
Thank you for your response. Have a good day.
</play>
<hangup name=""Hangup""/>
</dialplan>
"
}
}
};
IList<Call> calls = client.CallsApi.Send(request);
}
}'strict'
const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');
client.ready(() => {
client.calls.sendCalls({
body: [
{
phoneNumber: '12135551100',
attributes: {
external_user_id: '45450007002'
},
dialplanXml: '<dialplan name="Root"> <menu maxDigits="1" timeout="3500" name="Live"> <play type="tts" voice="female1"> Hello, this is UMM Health Center, you have an appointment with Dr. Andrew tomorrow at 3:00 PM, please press 1 to confirm the time or press 2 to reschedule appointment. </play> <keypress pressed="1"> <stash varname="selected_menu">confirmed</stash> <goto>bye_tts</goto> </keypress> <keypress pressed="2"> <stash varname="selected_menu">reschedule</stash> <play type="tts" voice="female1"> You will be transferred to our representative to reschedule an appointment. Please wait. </play> <transfer callerid="${call.callerid}" musiconhold="blues" mode="ringall"> 15550005500 </transfer> </keypress> <keypress pressed="default" name="incorrect_Selection"> <play type="tts" voice="female1">That is not a valid selection. Please try again.</play> <goto name="replay_Live">Live</goto> </keypress> </menu> <play type="tts" voice="female1" name="bye_tts"> Thank you for your response. Have a good day. </play> <hangup name="Hangup"/> </dialplan> '
}
]
})
.then((response) => {
console.log(response.obj);
})
.catch((err) => {
console.log('request error ' + err.data);
});
},
(clientError) => {
console.log('client error ' + clientError);
}
);from callfire.client import CallfireClient
client = CallfireClient('api-login', 'api-password')
response = client.calls.sendCalls(
body=[
{
'phoneNumber': '12135551100',
'attributes': {
'external_user_id': '45450007002'
},
'dialplanXml': '<dialplan name="Root"> <menu maxDigits="1" timeout="3500" name="Live"> <play type="tts" voice="female1"> Hello, this is UMM Health Center, you have an appointment with Dr. Andrew tomorrow at 3:00 PM, please press 1 to confirm the time or press 2 to reschedule appointment. </play> <keypress pressed="1"> <stash varname="selected_menu">confirmed</stash> <goto>bye_tts</goto> </keypress> <keypress pressed="2"> <stash varname="selected_menu">reschedule</stash> <play type="tts" voice="female1"> You will be transferred to our representative to reschedule an appointment. Please wait. </play> <transfer callerid="${call.callerid}" musiconhold="blues" mode="ringall"> 15550005500 </transfer> </keypress> <keypress pressed="default" name="incorrect_Selection"> <play type="tts" voice="female1">That is not a valid selection. Please try again.</play> <goto name="replay_Live">Live</goto> </keypress> </menu> <play type="tts" voice="female1" name="bye_tts"> Thank you for your response. Have a good day. </play> <hangup name="Hangup"/> </dialplan> '
}
]
).result()
# see sample JSON response for this API
# on 'curl' samples tab
print(response)<?php
class ApiClientSample {
public static function main() {
$client = \CallFire\Api\DocumentedClient::createClient("login", "password");
$request = $client->sendCalls();
$body = '[
{
"phoneNumber":"12135551100",
"attributes":
{
"external_user_id":"45450007002"
},
"dialplanXml":"<dialplan name=\"Root\"> <menu maxDigits=\"1\" timeout=\"3500\" name=\"Live\"> <play type=\"tts\" voice=\"female1\"> Hello, this is UMM Health Center, you have an appointment with Dr. Andrew tomorrow at 3:00 PM, please press 1 to confirm the time or press 2 to reschedule appointment. </play> <keypress pressed=\"1\"> <stash varname=\"selected_menu\">confirmed</stash> <goto>bye_tts</goto> </keypress> <keypress pressed=\"2\"> <stash varname=\"selected_menu\">reschedule</stash> <play type=\"tts\" voice=\"female1\"> You will be transferred to our representative to reschedule an appointment. Please wait. </play> <transfer callerid=\"${call.callerid}\" musiconhold=\"blues\" mode=\"ringall\"> 15550005500 </transfer> </keypress> <keypress pressed=\"default\" name=\"incorrect_Selection\"> <play type=\"tts\" voice=\"female1\">That is not a valid selection. Please try again.</play> <goto name=\"replay_Live\">Live</goto> </keypress> </menu> <play type=\"tts\" voice=\"female1\" name=\"bye_tts\"> Thank you for your response. Have a good day. </play> <hangup name=\"Hangup\"/> </dialplan> "
}
]';
$request->getOperationConfig()->setBodyParameter($body);
$result = $client->request($request);
$json = json_decode($result->getBody());
}
}
ApiClientSample::main();Refer to Send Calls API reference for detailed information about request type, parameters, and responses.
Important note. Both Send Texts and Send Calls API use default broadcast to send out outgoing messages. Read more about default broadcasts at Broadcast Messaging page.
How to Find Outbound Texts or Calls
CallFire Calls and Texts API provides several ways to query outbound and inbound actions. Check Individual Messaging guide to find how to query sent and/or received messages.
Another way of receiving information about sent/received calls or texts is to use CallFire Webhooks.
How to set up CallFire Notifications
Webhooks are a system of automated notifications indicating that an event has occurred in the CallFire system. They help you to build a bi-directional integration where your service receives HTTP POST notifications from our platform.
You can use webhooks to push information about Outbound/Inbound Calls and Texts to your service, and push data stored using IVR broadcasts. Check the webhooks guide for more information about CallFire Webhooks.
How to Get Call/Text Statistics from a Broadcast
You can pull particular broadcast statistics, like the number of total actions (Call/Text) made by the platform for a particular campaign, the number of remaining actions, the number of errors, the number of calls by disposition, the call duration, billed amount, etc. The following samples show how to fetch statistics for a default call broadcast:
[[code-container]] [+curl] request:
#!/usr/bin/env bash
curl -u username:password -H "Content-Type:application/json" -X GET "https://api.callfire.com/v2/calls/broadcasts/11646003/stats?begin=1473781817000&end=1473781817000&fields=totalOutboundCount,billedAmount,callsAttempted"{
"totalOutboundCount": 2,
"remainingOutboundCount": 0,
"billedAmount": 1.6667,
"callsAttempted": 1,
"callsPlaced": 1,
"callsDuration": 1,
"billedDuration": 60,
"responseRatePercent": 100,
"callsRemaining": 1,
"callsAwaitingRedial": 0,
"callsLiveAnswer": 1,
"totalCount": 2,
"answeringMachineCount": 0,
"busyCount": 0,
"dialedCount": 1,
"doNotCallCount": 1,
"errorCount": 0,
"liveCount": 1,
"miscCount": 0,
"noAnswerCount": 0,
"transferCount": 0
}import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.campaigns.model.CallBroadcastStats;
import java.util.Calendar;
import java.util.Date;
import java.util.GregorianCalendar;
class ApiClientSample {
public static void main(String[] args) {
CallfireClient client = new CallfireClient("api_login", "api_password");
Date end = new GregorianCalendar(2016, Calendar.SEPTEMBER, 15, 50, 17, 0).getTime();
Date begin = new GregorianCalendar(2016, Calendar.SEPTEMBER, 15, 50, 17, 0).getTime();
// limit returned fields if needed
String fields = "totalOutboundCount,billedAmount,callsAttempted";
CallBroadcastStats stats = client.callBroadcastsApi().getStats(11646003L, fields, begin, end);
}
}using System;
using CallfireApiClient;
public class ApiClientSample
{
public static void Main(string[] args)
{
var client = new CallfireClient("api_login", "api_password");
// limit returned fields if needed
var fields = "totalOutboundCount,billedAmount,callsAttempted";
var begin = new DateTime(2016, 9, 13, 15, 50, 17);
var end = new DateTime(2016, 9, 13, 15, 50, 17);
var stats = client.CallBroadcastsApi.GetStats(11646003, fields, begin, end);
}
}'strict'
const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');
client.ready(() => {
client.calls.getCallBroadcastStats({
id: 11646003,
// filter by time interval
begin: 1473781817000,
// filter by time interval
end: 1473781817000,
// return only specific fields
fields: 'totalOutboundCount,billedAmount,callsAttempted'
})
.then((response) => {
console.log(response.obj);
})
.catch((err) => {
console.log('request error ' + err.data);
});
},
(clientError) => {
console.log('client error ' + clientError);
}
);from callfire.client import CallfireClient
client = CallfireClient('api-login', 'api-password')
response = client.calls.getCallBroadcastStats(
id=11646003,
# filter by time interval
begin=1473781817000,
# filter by time interval
end=1473781817000,
# return only specific fields
fields='totalOutboundCount,billedAmount,callsAttempted'
).result()
# see sample JSON response for this API
# on 'curl' samples tab
print(response)<?php
class ApiClientSample {
public static function main() {
$client = \CallFire\Api\DocumentedClient::createClient("login", "password");
$request = $client->getCallBroadcastStats();
$request->getOperationConfig()->setPathParameters(array("id" => 11646003));
$request->getOperationConfig()->setQueryParameters(array("begin" => 1473781817000,
"end" => 1473781817000,
"fields" => "totalOutboundCount,billedAmount,callsAttempted"));
$result = $client->request($request);
$json = json_decode($result->getBody());
}
}
ApiClientSample::main();See the Get Call Broadcast Stats API for detailed information about request type, parameters, and responses.