Individual Text and Voice Messaging
Overview
CallFire provides a simple way to deliver an individual text and voice message to 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 (in this case you should provide a contact ID in recipient object).
Sending Individual Text Message
To send a text message (SMS) you should use Send Texts API which allows you to send an individual message to up to 1000 recipients at a time, and attach a media file (different types of media content are supported e.g. bmp, png, jpeg pictures, mp3, wav, mp4 video and audio) to the message.
If you provide a list of recipients with plain phone numbers, please make sure all numbers are correct otherwise the API will return an error if one of the passed phone numbers is bad.
API returns a list of Text objects representing a text message to each recipient, you can use Find Texts or Get Text methods to query particular text records.
The code samples below show how to send different text message to 2 recipients at a time. If you are going to send the same message to all recipients you can specify it once in defaultMessage parameter. Do not duplicate each recipient or use Broadcast Messaging if you need to send a message to a huge number of recipients.
[[code-container]] [+curl] request:
#!/usr/bin/env bash
curl -u username:password -H "Content-Type:application/json" -X POST -d '
[
{
"phoneNumber":"12135551122",
"message":"Hello World!"
},
{
"contactId":122460000043
},
{
"phoneNumber":"12135558090",
"attributes":
{
"custom_external_id": 30005044,
"custom_name": "Alice"
},
"message": "Hello, ${custom_name}!"
}
]' "https://api.callfire.com/v2/texts?campaignId=4050600003&defaultMessage=Hello!"{
"items": [
{
"id": 13413,
"fromNumber": "67076",
"toNumber": "12135551100",
"state": "READY",
"campaignId": 20,
"batchId": 14,
"contact": {
"id": 4096,
"homePhone": "12135551100"
},
"inbound": false,
"created": 1443403042000,
"modified": 1443403042000,
"message": "Hello World!"
},
{
"id": 13414,
"fromNumber": "67076",
"toNumber": "12135551101",
"state": "READY",
"campaignId": 20,
"batchId": 14,
"contact": {
"id": 4097,
"homePhone": "12135551101"
},
"inbound": false,
"created": 1443403044000,
"modified": 1443403044000,
"message": "Testing 1 2 3"
}
]
}import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.callstexts.model.Text;
import com.callfire.api.client.api.callstexts.model.request.SendTextsRequest;
import com.callfire.api.client.api.campaigns.model.TextRecipient;
import java.util.Arrays;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
class ApiClientSample {
public static void main(String[] args) {
CallfireClient client = new CallfireClient("api_login", "api_password");
TextRecipient r1 = new TextRecipient();
r1.setPhoneNumber("12135551122");
r1.setMessage("Hello World!");
TextRecipient r2 = new TextRecipient();
r2.setContactId(122460000043L);
TextRecipient r3 = new TextRecipient();
r1.setPhoneNumber("12135558090");
r1.setMessage("Hello World!");
Map<String,String> attrs = new HashMap<>();
attrs.put("custom_external_id", "30005044");
attrs.put("custom_name", "Alice");
r3.setAttributes(attrs);
r3.setMessage("Hello, ${custom_name}!");
List<TextRecipient> recipients = Arrays.asList(r1, r2, r3);
SendTextsRequest request = SendTextsRequest.create()
.recipients(recipients)
.campaignId(4050600003L)
.defaultMessage("Hello!")
.build();
List<Text> texts = client.textsApi().send(request);
}
}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 recipient1 = new TextRecipient
{
Message = "Hello World!",
PhoneNumber = "12135551122"
};
var recipient2 = new TextRecipient
{
ContactId = 122460000043
};
var recipient3 = new TextRecipient
{
PhoneNumber = "12135558090",
Attributes = new Dictionary<string, string>
{
{"custom_external_id", "30005044"},
{"custom_name", "Alice"}
},
Message = "Hello, ${custom_name}!"
};
var recipients = new List<TextRecipient> {recipient1, recipient2, recipient3};
var request = new SendTextsRequest
{
Recipients = recipients,
CampaignId = 4050600003,
DefaultMessage = "Hello!"
};
IList<Text> texts = client.TextsApi.Send(request);
}
}'strict'
const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');
client.ready(() => {
client.texts.sendTexts({
// default message for recipients w/o TextRecipient.message field
defaultMessage: 'Hello!',
// specify a campaignId to send texts through a previously created campaign
// campaignId: 4050600003
body: [
{
phoneNumber: '12135551122',
message: 'Hello World!'
},
// use an existing contact in CallFire account
{contactId: 122460000043},
{
phoneNumber: '12135558090',
attributes: {
custom_external_id: 30005044,
custom_name: 'Alice'
},
message: 'Hello, ${custom_name}!'
},
]
})
.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(
# default message for recipients w/o TextRecipient.message field
defaultMessage='Hello!',
# specify a campaignId to send texts through a previously created campaign
# campaignId: 4050600003
body=[
{
'phoneNumber': '12135551122',
'message': 'Hello World!'
},
# use an existing contact in CallFire account
{'contactId': 122460000043},
{
'phoneNumber': '12135558090',
'attributes': {
'custom_external_id': 30005044,
'custom_name': 'Alice'
},
'message': 'Hello, ${custom_name}!'
},
]
).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();
$request->getOperationConfig()->setQueryParameters(array("campaignId" => 4050600003,
"defaultMessage" => "Hello!"));
$body = '[
{
"phoneNumber":"12135551122",
"message":"Hello World!"
},
{
"contactId":122460000043
},
{
"phoneNumber":"12135558090",
"attributes":
{
"custom_external_id": 30005044,
"custom_name": "Alice"
},
"message": "Hello, ${custom_name}!"
}
]';
$request->getOperationConfig()->setBodyParameter($body);
$result = $client->request($request);
$json = json_decode($result->getBody());
}
}
ApiClientSample::main();See the Send Texts API for detailed information about accepted parameters and responses.
Limitation. Send Texts API supports up to 1000 recipients per request.
Sending Individual Voice Message
CallFire provides two options to send a voice message:
- using pre-recorded sound files
- using IVR dialplan
The Send Calls API is used in both cases and accepts a list of CallRecipient objects, each of them contains the following fields:
[
{
// set phone number or existing contact ID
"phoneNumber": "string",
"contactId": 0,
// user defined attributes
"attributes": {},
// if you are sending a voice call with pre-recorded message one of the fields below is required,
// you can specify a text which will be turned to voice or specify existing sound ID
"liveMessage": "string",
"liveMessageSoundId": 0,
"machineMessage": "string",
"machineMessageSoundId": 0,
"transferMessage": "string",
"transferMessageSoundId": 0,
"transferDigit": "string",
"transferNumber": "string",
"voice": "string",
// in case of IVR call you should specify only dialplanXml, you do not need to specify the fields for pre-recorded call
"dialplanXml": "string"
}
]
For the call with pre-recorded sounds you should specify a text message which will be turned to voice or specify an existing sound ID, you can find instructions on how to upload or record a sound on Sound Library page.
With IVR call you have advanced configuration options (repeating the played message, adding an interactive menu, etc.) if this case you only need to specify a CallRecipient.dialplanXml property, please make sure that XML is properly encoded before sending otherwise you'll receive 400 Bad Request response.
Voice message with pre-recorded sounds
To send a simple voice call you should specify one of following fields:
[
{
// you can set a text-to-speech message which will be played upon live answer, or if answering machine is detected,
// or the call is transferred
"liveMessage": "string",
"machineMessage": "string",
"transferMessage": "string",
// or you can spcify previously uploaded or recorded sound from CallFire Sound Library
"liveMessageSoundId": 0,
"transferMessageSoundId": 0,
"machineMessageSoundId": 0,
// if transfer message or sound is set the following fields are required
"transferDigit": "string",
"transferNumber": "string",
// optional, set text-to-speech voice, available values: MALE1, FEMALE1, FEMALE2, SPANISH1, FRENCHCANADIAN1
"voice": "string"
}
]
If you have more than one recipient and they have the same sounds you can specify them once using default properties and do not duplicate those parameters for each recipient object.
string defaultLiveMessage
string defaultMachineMessage
number defaultLiveMessageSoundId
number defaultMachineMessageSoundId
string defaultVoice
The following code samples show how to send a voice message to two recipients, CallRecipient.liveMessage will be played if call is answered by a person, if answering machine is detected then CallRecipient.machineMessage will be played.
[[code-container]] [+curl] request:
#!/usr/bin/env bash
curl -u username:password -H "Content-Type:application/json" -X POST -d '
[
{
"phoneNumber":"12135551100",
"liveMessage":"Hello, Alice, this is message for live answer",
"machineMessage":"Hello, Alice, this is message for answering machine"
},
{
"phoneNumber":"12135551101",
"liveMessage":"Hello, Bob, this is message for live answer",
"machineMessage":"Hello, Bob, this is message for answering machine"
}
]' "https://api.callfire.com/v2/calls"{
"items": [
{
"id": 13394,
"fromNumber": "12135551189",
"toNumber": "12135551100",
"state": "READY",
"campaignId": 10,
"batchId": 6,
"contact": {
"id": 4096,
"homePhone": "12135551100"
},
"inbound": false,
"created": 1443373382000,
"modified": 1443373382000,
"agentCall": false
},
{
"id": 13395,
"fromNumber": "12135551189",
"toNumber": "12135551101",
"state": "READY",
"campaignId": 10,
"batchId": 6,
"contact": {
"id": 4097,
"homePhone": "12135551101"
},
"inbound": false,
"created": 1443373386000,
"modified": 1443373386000,
"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 com.callfire.api.client.api.campaigns.model.Voice;
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.setLiveMessage("Hello, Alice, this is message for live answer");
r1.setMachineMessage("Hello, Alice, this is message for answering machine");
CallRecipient r2 = new CallRecipient();
r2.setPhoneNumber("''12135551101''");
r2.setLiveMessage("Hello, Bob, this is message for live answer");
r2.setMachineMessage("Hello, Bob, this is message for answering machine");
List<CallRecipient> recipients = Arrays.asList(r1, r2);
SendCallsRequest request = new SendCallsRequest().create()
.recipients(recipients)
.build();
List<Call> calls = client.callsApi().send(request);
}
}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 request = new SendCallsRequest()
{
Recipients = new List<CallRecipient>
{
new CallRecipient
{
PhoneNumber = "12135551100",
LiveMessage = "Hello, Alice, this is message for live answer",
MachineMessage = "Hello, Alice, this is message for answering machine"
},
new CallRecipient
{
PhoneNumber = "12135551101",
LiveMessage = "Hello, Bob, this is message for live answer",
MachineMessage = "Hello, Bob, this is message for answering machine"
}
}
};
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',
liveMessage: 'Hello, Alice, this is message for live answer',
machineMessage: 'Hello, Alice, this is message for answering machine'
},
{
phoneNumber: '12135551101',
liveMessage: 'Hello, Bob, this is message for live answer',
machineMessage: 'Hello, Bob, this is message for answering machine'
}
]
})
.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',
'liveMessage': 'Hello, Alice, this is message for live answer',
'machineMessage': 'Hello, Alice, this is message for answering machine'
},
{
'phoneNumber': '12135551101',
'liveMessage': 'Hello, Bob, this is message for live answer',
'machineMessage': 'Hello, Bob, this is message for answering machine'
}
]
).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",
"liveMessage":"Hello, Alice, this is message for live answer",
"machineMessage":"Hello, Alice, this is message for answering machine"
},
{
"phoneNumber":"12135551101",
"liveMessage":"Hello, Bob, this is message for live answer",
"machineMessage":"Hello, Bob, this is message for answering machine"
}
]';
$request->getOperationConfig()->setBodyParameter($body);
$result = $client->request($request);
$json = json_decode($result->getBody());
}
}
ApiClientSample::main();Voice message with IVR dialplan
The term IVR stands for Interactive Voice Response. An IVR allows you to ask questions through pre-recorded or text-to-speech prompts, and receive responses via phone key presses. The CallFire IVR setup uses an XML-based definition. Read more about IVRs at CallFire XML page.
The next XML sample represents a CallFire IVR dialplan which does the following:
- detects if the call is answered by a human or an answering machine, then plays a message or hangs up the phone.
- once the message is played, waits for user input before a given timeout (in our case 3500 milliseconds).
- if users presses "1," repeats the voice message, otherwise hangs up the phone.
<dialplan name="Root">
<!-- answering machine detection -->
<amd>
<!-- if call is answered by human go to live menu -->
<live>
<goto>live</goto>
</live>
<!-- hangup if answering machine detected -->
<machine>
<goto>hangup</goto>
</machine>
</amd>
<menu maxDigits="1" timeout="3500" name="live">
<!-- play a text message -->
<play type="tts" voice="female1" name="play_msg">Hello, ${contact.firstName}, this is CallFire IVR message.</play>
<!-- user has pressed 1, repeat starting from menu entry -->
<keypress pressed="1">
<goto>live</goto>
</keypress>
<!-- nothing is pressed for a 3500 milliseconds, hang up the phone -->
<keypress pressed="timeout">
<hangup/>
</keypress>
</menu>
<hangup name="hangup"/>
</dialplan>You can find more information about the IVR at CallFire Answers Page and different IVR examples are available on our public Github repository.
Check the CallFire XML page for a detailed description of all IVR tags.
Please note that if you are sending an IVR call you should set only CallRecipient.dialplanXml parameter along with recipient's phone number or contact ID.
The examples below show how to send an IVR call with the given dialplan:
[[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\"> <amd> <live> <goto>live</goto> </live> <machine> <goto>hangup</goto> </machine> </amd> <menu maxDigits=\"1\" timeout=\"3500\" name=\"live\"> <play type=\"tts\" voice=\"female1\" name=\"play_msg\">Hello, ${contact.firstName}, this is CallFire IVR message.</play> <keypress pressed=\"1\"> <goto>live</goto> </keypress> <keypress pressed=\"timeout\"> <hangup/> </keypress> </menu> <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"
},
"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.HashMap;
import java.util.List;
import java.util.Map;
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\"> "
+ "<!-- answering machine detection --> "
+ "<amd> "
+ " <!-- if call is answered by human go to live menu --> "
+ " <live> "
+ " <goto name=\"live\">Live</goto> "
+ " </live> "
+ " <!-- hangup if answering machine detected --> "
+ " <machine> "
+ " <goto>hangup</goto> "
+ " </machine> "
+ "</amd> "
+ " <menu maxDigits=\"1\" timeout=\"3500\" name=\"live\"> "
+ " <!-- play text message with secure code --> "
+ " <play type=\"tts\" voice=\"female1\" name=\"play_code\">Hello, ${contact.firstName}, this is CallFire IVR message.</play>"
+ " <keypress pressed=\"1\"> "
+ " <goto>live</goto> "
+ " </keypress> "
+ " <keypress pressed=\"timeout\"> "
+ " <hangup/> "
+ " </keypress> "
+ " </menu> "
+ " <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"">
<!-- answering machine detection -->
<amd>
<!-- if call is answered by human go to live menu -->
<live>
<goto>live</goto>
</live>
<!-- hangup if answering machine detected -->
<machine>
<goto>hangup</goto>
</machine>
</amd>
<menu maxDigits=""1"" timeout=""3500"" name=""live"">
<!-- play text message with secure code -->
<play type=""tts"" voice=""female1"" name=""play_code"">Hello, ${contact.firstName}, this is CallFire IVR message.</play>
<keypress pressed=""1"">
<goto>live</goto>
</keypress>
<keypress pressed=""timeout"">
<hangup/>
</keypress>
</menu>
<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\"> <amd> <live> <goto>live</goto> </live> <machine> <goto>hangup</goto> </machine> </amd> <menu maxDigits=\"1\" timeout=\"3500\" name=\"live\"> <play type=\"tts\" voice=\"female1\" name=\"play_msg\">Hello, ${contact.firstName}, this is CallFire IVR message.</play> <keypress pressed=\"1\"> <goto>live</goto> </keypress> <keypress pressed=\"timeout\"> <hangup/> </keypress> </menu> <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\"> <amd> <live> <goto>live</goto> </live> <machine> <goto>hangup</goto> </machine> </amd> <menu maxDigits=\"1\" timeout=\"3500\" name=\"live\"> <play type=\"tts\" voice=\"female1\" name=\"play_msg\">Hello, ${contact.firstName}, this is CallFire IVR message.</play> <keypress pressed=\"1\"> <goto>live</goto> </keypress> <keypress pressed=\"timeout\"> <hangup/> </keypress> </menu> <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\"> <amd> <live> <goto>live</goto> </live> <machine> <goto>hangup</goto> </machine> </amd> <menu maxDigits=\"1\" timeout=\"3500\" name=\"live\"> <play type=\"tts\" voice=\"female1\" name=\"play_msg\">Hello, ${contact.firstName}, this is CallFire IVR message.</play> <keypress pressed=\"1\"> <goto>live</goto> </keypress> <keypress pressed=\"timeout\"> <hangup/> </keypress> </menu> <hangup name=\"hangup\"/> </dialplan> "
}
]';
$request->getOperationConfig()->setBodyParameter($body);
$result = $client->request($request);
$json = json_decode($result->getBody());
}
}
ApiClientSample::main();See Send Calls API for detailed information about accepted parameters and responses.
Limitation. Send Calls API supports up to 10 recipients per request.
Default Broadcast
Both Send Texts and Send Calls API use default broadcast to send out outgoing messages. CallFire allows you to specify a campaignId to send out a message through a non-default broadcast with your custom configuration. In case you need to change a fromNumber, group outgoing messages by some tag, etc. you need to create a broadcast with the necessary configuration and invoke Send API with campaignId parameter. Read more about 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. You can use Find Calls or Find Texts methods to search outbound/inbound actions. All find() methods support pagination and the limiting of returned data. More information can be found at docs page
The following examples show how to find all texts sent via the Send Texts API operation between 2015-12-01 and 2015-12-10 through the campaign with id = 10, with a label 'reminders', and will return the first page with 10 records.
[[code-container]] [+curl] request:
#!/usr/bin/env bash
curl -u "username:password" -H "Content-Type:application/json" -X GET "https://api.callfire.com/v2/texts?campaignId=13&label=reminders&intervalBegin=1448920800000&intervalEnd=1449698400000&limit=10"{
"items": [
{
"id": 13405,
"fromNumber": "12135551100",
"toNumber": "12135551123",
"state": "FINISHED",
"campaignId": 13,
"batchId": 11,
"contact": {
"id": 4101,
"homePhone": "12135551123"
},
"labels": [
"reminders"
],
"attributes": {
"contact_name":"Alice",
"external_user_id":"45450007002"
},
"inbound": true,
"created": 1443382358000,
"modified": 1443382358000,
"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",
"finalTextResult": "SENT",
"records": [
{
"id": 10310,
"billedAmount": 0.0,
"finishTime": 1443403043000,
"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",
"textResult": "SENT"
}
]
},
{
"id": 13404,
"fromNumber": "12135551100",
"toNumber": "12135551122",
"state": "FINISHED",
"campaignId": 13,
"batchId": 10,
"contact": {
"id": 4099,
"homePhone": "12135551122"
},
"labels": [
"reminders"
],
"attributes": {
"contact_name":"Bob",
"external_user_id":"77880007002"
},
"inbound": true,
"created": 1443382248000,
"modified": 1443382248000,
"message": "Hello Bob, you have an appointment with Dr. Jonson tomorrow at 9:30 AM, if you need to reschedule please call (855)-555-4477",
"finalTextResult": "SENT",
"records": [
{
"id": 10410,
"billedAmount": 0.0,
"finishTime": 1443403053000,
"message": "Hello Bob, you have an appointment with Dr. Jonson tomorrow at 9:30 PM, if you need to reschedule please call (855)-555-4477",
"textResult": "SENT"
}
]
}
],
"limit": 10,
"offset": 0,
"totalCount": 100
}import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.callstexts.model.Text;
import com.callfire.api.client.api.callstexts.model.request.FindTextsRequest;
import com.callfire.api.client.api.common.model.Page;
import java.util.Calendar;
import java.util.GregorianCalendar;
class ApiClientSample {
public static void main(String[] args) {
CallfireClient client = new CallfireClient("api_login", "api_password");
FindTextsRequest request = FindTextsRequest.create()
.campaignId(13L)
.label("reminders")
.intervalBegin(new GregorianCalendar(2015, Calendar.DECEMBER, 1, 0, 0, 0).getTime())
.intervalEnd(new GregorianCalendar(2015, Calendar.DECEMBER, 10, 0, 0, 0).getTime())
.limit(10L)
.build();
Page<Text> texts = client.textsApi().find(request);
}
}using System;
using CallfireApiClient;
using CallfireApiClient.Api.CallsTexts.Model;
using CallfireApiClient.Api.CallsTexts.Model.Request;
using CallfireApiClient.Api.Common.Model;
public class ApiClientSample
{
public static void Main(string[] args)
{
var client = new CallfireClient("api_login", "api_password");
var request = new FindTextsRequest
{
// find all texts which belong to a particular campaign and were sent between
// 2015-12-01 and 2015-12-10
CampaignId = 13,
Label = "reminders",
IntervalBegin = new DateTime(2016, 12, 1, 0, 0, 0),
IntervalEnd = new DateTime(2016, 12, 1, 0, 0, 0),
Limit = 10
};
Page<Text> texts = client.TextsApi.Find(request);
}
}'strict'
const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');
client.ready(() => {
client.texts.findTexts({
campaignId: 13,
label: 'reminders',
intervalBegin: 1448920800000,
intervalEnd: 1449698400000,
limit: 10
})
.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.findTexts(
campaignId=13,
label='reminders',
intervalBegin=1448920800000,
intervalEnd=1449698400000,
limit=10
).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->findTexts();
$request->getOperationConfig()->setQueryParameters(array("campaignId" => 13,
"label" => "reminders",
"intervalBegin" => 1448920800000,
"intervalEnd" => 1449698400000,
"limit" => 10));
$result = $client->request($request);
$json = json_decode($result->getBody());
}
}
ApiClientSample::main();You can query calls in the same way as is shown for texts in the previous examples. This method also returns a user's responses (stored using IVR stash tag) for each call. Stored data will appear in the records.questionResponses array.
[[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?campaignId=10&label=reminders&intervalBegin=1448920800000&intervalEnd=1449698400000&limit=10"{
"items": [
{
"id": 13395,
"fromNumber": "12135551189",
"toNumber": "12135551101",
"state": "FINISHED",
"campaignId": 10,
"batchId": 6,
"contact": {
"id": 4097,
"homePhone": "12135551101"
},
"labels": [
"reminders"
],
"attributes": {
"external_user_id":"45450007002"
},
"inbound": false,
"created": 1443373386000,
"modified": 1443373412000,
"finalCallResult": "LA",
"records": [
{
"id": 10306,
"billedAmount": 1.1667,
"finishTime": 1443373425000,
"callResult": "LA",
"questionResponses":
[
{
"question":"selected_menu",
"response":"confirmed"
}
]
}
],
"agentCall": false
},
{
"id": 13394,
"fromNumber": "12135551189",
"toNumber": "12135551100",
"state": "FINISHED",
"campaignId": 10,
"batchId": 6,
"contact": {
"id": 4096,
"homePhone": "12135551100"
},
"labels": [
"reminders"
],
"attributes": {
"external_user_id":"45450008008"
},
"inbound": false,
"created": 1443373382000,
"modified": 1443373412000,
"finalCallResult": "LA",
"records": [
{
"id": 10305,
"billedAmount": 0,
"finishTime": 1443373408000,
"callResult": "LA",
"questionResponses":
[
{
"question":"selected_menu",
"response":"reschedule"
}
]
}
],
"agentCall": false
}
],
"limit": 10,
"offset": 0,
"totalCount": 7160
}import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.callstexts.model.Call;
import com.callfire.api.client.api.callstexts.model.request.FindCallsRequest;
import com.callfire.api.client.api.common.model.Page;
import java.util.Calendar;
import java.util.GregorianCalendar;
class ApiClientSample {
public static void main(String[] args) {
CallfireClient client = new CallfireClient("api_login", "api_password");
// find all calls made through campaign with id = 10, label = reminders is assigned to such campaign,
// between 2015-12-01 and 2015-12-10, return first 10 records if any
FindCallsRequest request = FindCallsRequest.create()
.campaignId(10L)
.label("reminders")
.intervalBegin(new GregorianCalendar(2015, Calendar.NOVEMBER, 30, 22, 0, 0).getTime())
.intervalEnd(new GregorianCalendar(2015, Calendar.DECEMBER, 9, 22, 0, 0).getTime())
.limit(10L)
.build();
Page<Call> calls = client.callsApi().find(request);
// see Call.records.questionResponses list for stored data
}
}using System;
using CallfireApiClient;
using CallfireApiClient.Api.CallsTexts.Model;
using CallfireApiClient.Api.CallsTexts.Model.Request;
using CallfireApiClient.Api.Common.Model;
public class ApiClientSample
{
public static void Main(string[] args)
{
var client = new CallfireClient("api_login", "api_password");
var request = new FindCallsRequest
{
CampaignId = 10,
Label = "reminders",
IntervalBegin = new DateTime(2015, 11, 30, 22, 0, 0),
IntervalEnd = new DateTime(2016, 12, 09, 22, 0, 0),
Limit = 10
};
Page<Call> calls = client.CallsApi.Find(request);
// check Call.records.questionResponses for stored data
}
}'strict'
const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');
client.ready(() => {
client.calls.findCalls({
campaignId: 10,
label: 'reminders',
intervalBegin: 1448920800000,
intervalEnd: 1449698400000,
limit: 10
})
.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.findCalls(
# return calls from particular campaign
campaignId=10,
label='reminders',
# time is in unix milliseconds
intervalBegin=1448920800000,
intervalEnd=1449698400000,
limit=10
).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");
// find all calls made through campaign with id = 10, label = reminders is assigned to such campaign,
// return first 10 records if any
$request = $client->findCalls();
$request->getOperationConfig()->setQueryParameters(array("campaignId" => 10,
"label" => "reminders",
"intervalBegin" => 1448920800000,
"intervalEnd" => 1449698400000,
"limit" => 10));
$result = $client->request($request);
$json = json_decode($result->getBody());
}
}
ApiClientSample::main();Another way of receiving information about sent/received calls or texts is to use CallFire Webhooks.
Receiving Notifications from CallFire
CallFire provides a notification service called webhooks, you can always create a webhook to start receiving notifications from CallFire upon some event, for instance when a message is sent or a call is finished. Information on how to create and configure a webhook can be found at Webhooks Guide page.
API Use Cases
Individual messaging has many use-cases, the following guides show how to build an integration with CallFire based on a particular use-case:
- Web Based Business Uses Two-Factor Authentication - sends individual calls and short messages
- Medical Center Sending Reminders and Notifications - shows how to send an individual text and voice reminders with an interactive voice menu