Non-Profit Agency Soliciting Donations

Short story

Imagine that the local branch of a non-profit agency organizes a charity weekend in Beaufort. This agency is gathering funds for educational classes for disabled people. Mary, a member of the agency, decided to raise funds by selling entrance tickets and by organizing a charity event.

CallFire Voice Broadcast, IVR, and Text Messaging products are the best fit for this task. Let's see them in detail.

Important note. The CallFire Messaging API is divided into two parts: calls and texts. They use similar methods for sending voice and text messages, creating call and text broadcasts, and quering inbound/outbound calls and texts. This article selectively shows how to use methods from both parts. Keep in mind that if we show how to find particular texts or get all the text messages from a particular text broadcast, there are similar methods available to do the same for calls.

What is the Text Broadcast and how can it be used?

Text Broadcast allows you to send a short text message to a list of recipients. By default, all messages go out from the shared shortcode 67076. You can stay with our shortcode or buy a dedicated long or shortcode to use as the FromNumber. Recipients can reply to a received message, and those replies will appear on on the UI Inbox page and can be queried via API. CallFire provides the ability to create a templated message, for instance "Hello ${user}, the current date is ${current_date}" and then pass attributes or custom fields unique to each recipient.

Story

Mary sends out a short notification message using Text broadcast: "Hello ${name}. Looking for a great event? We invite you to participate in our charity fair which takes place the first Saturday of November. You can order tickets by calling us: 855-555-5555. We are looking forward to seeing you there." The agency receives replies from recipients and can plan accordingly.

You can schedule a text broadcast, set local time restrictions on when the messages should go out, or start it right after creation. The following examples show how to create a text broadcast with a templated message. Every recipient has a list of key=value attributes which are used in a message's text.

[[code-container]] [+curl] request:

#!/usr/bin/env bash

curl -u username:password -H "Content-Type:application/json" -X POST -d '
    {
        "name":"Charity SMS Campaign",
        "labels":
        [
            "charity",
            "id-10003"
        ],
        "fromNumber":"19206596476",
        "recipients":
        [
            {
                "phoneNumber":"13233834422",
                "attributes":
                {
                    "u_name": "Alice",
                    "age": 30
                }
            },
            {
                "phoneNumber":"13233834433",
                "attributes":
                {
                    "u_name": "Mark",
                    "age": 45
                }
            },
            {
                "phoneNumber":"13233834488",
                "message": "Hi ${u_name}, the megic number is ${magic_number}",
                "attributes":
                {
                    "u_name": "Jane",
                    "magic_number": "10"
                }
            }
        ],
        "message":"Hello {u_name} ..."
    }' "https://api.callfire.com/v2/texts/broadcasts"
response:
{
  "id": 13
}
[-curl] [+java]

import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.campaigns.model.TextBroadcast;
import com.callfire.api.client.api.campaigns.model.TextRecipient;
import com.callfire.api.client.api.common.model.ResourceId;

import java.util.Arrays;

class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient client = new CallfireClient("api_login", "api_password");

        TextBroadcast broadcast = new TextBroadcast();
        broadcast.setName("Charity SMS Campaign");
        // attach custom labels if needed
        broadcast.setLabels(Arrays.asList("charity", "id-10003"));
        // You can use default shared short code 67076 or uncomment the next line and set your own number
        broadcast.setFromNumber("19206596476");

        // by default if text exceeds length of 160 characters, CallFire will send a text as multiple messages.
        // broadcast.setBigMessageStrategy(TextBroadcast.BigMessageStrategy.TRIM);
        broadcast.setMessage("Hello {u_name} ...");

        // add new recipients
        TextRecipient recipient1 = new TextRecipient();
        recipient1.setPhoneNumber("13233834422");
        // 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
        recipient1.getAttributes().put("u_name", "Alice");
        recipient1.getAttributes().put("age", "30");

        TextRecipient recipient2 = new TextRecipient();
        recipient2.setPhoneNumber("13233834433");
        recipient2.getAttributes().put("u_name", "Mark");
        recipient2.getAttributes().put("age", "45");

        TextRecipient recipient3 = new TextRecipient();
        recipient3.setPhoneNumber("13233834488");
        // You can override a message set in broadcast for a particular recipient
        recipient3.setMessage("Hi {u_name}, the megic number is ${magic_number}");
        // Set custom attribute
        recipient3.getAttributes().put("u_name", "Jane");
        recipient3.getAttributes().put("magic_number", "10");

        broadcast.setRecipients(Arrays.asList(recipient1, recipient2, recipient3));

        // create broadcast and start immediately
        ResourceId id = client.textBroadcastsApi().create(broadcast, true);
    }
}
[-java] [+csharp]
using System.Collections.Generic;
using CallfireApiClient;
using CallfireApiClient.Api.CallsTexts.Model;
using CallfireApiClient.Api.Campaigns.Model;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        var broadcast = new TextBroadcast
        {
            Name = "Charity Campaign",
            // set validated Caller ID number.
            FromNumber = "19206596476",
            // attach custom labels if needed
            Labels = new List<string> {"charity", "id-10003"},
            // set message text
            Message = @"Hello {u_name} ...",
            // add new recipients
            Recipients = new List<TextRecipient>
            {
                new TextRecipient
                {
                    PhoneNumber = "13233834422",
                    // 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>
                    {
                        {"u_name", "Alice"},
                        {"age", "30"}
                    }
                },
                new TextRecipient
                {
                    PhoneNumber = "13233834433",
                    Attributes = new Dictionary<string, string>
                    {
                        {"u_name", "Mark"},
                        {"age", "45"}
                    }
                },
                new TextRecipient
                {
                    PhoneNumber = "13233834488",
                    // you can override a message set in broadcast for a particular recipient
                    Message = "Hi ${u_name}, the megic number is ${magic_number}",
                    Attributes = new Dictionary<string, string>
                    {
                        {"u_name", "Jane"},
                        {"magic_number", "10"}
                    }
                }
            }
        };

        // create broadcast with 'start' argument = true to start campaign immediately
        var id = client.TextBroadcastsApi.Create(broadcast, true);
    }
}
[-csharp] [+js]
'strict'

const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');

client.ready(() => {
    client.texts.createTextBroadcast({
      // set start parameter to run broadcast immediately
      // start: true,
      body: {
        name: 'Charity SMS Campaign',
        labels: [
          'charity',
          'id-10003'
        ],
        fromNumber: '19206596476',
        recipients: [
          {
            phoneNumber: '13233834422',
            attributes: {
              u_name: 'Alice',
              age: 30
            }
          },
          {
            phoneNumber: '13233834433',
            attributes: {
              u_name: 'Mark',
              age: 45
            }
          },
          {
            phoneNumber: '13233834488',
            message: 'Hi ${u_name}, the megic number is ${magic_number}',
            attributes: {
              u_name: 'Jane',
              magic_number: 10
            }
          }
        ],
        message: 'Hello {u_name} ...'
      }
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);
[-js] [+python]
from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.texts.createTextBroadcast(
    # set start parameter to run broadcast immediately
    # start: true,
    body={
        'name': 'Charity SMS Campaign',
        'labels': [
            'charity',
            'id-10003'
        ],
        'fromNumber': '19206596476',
        'recipients': [
            {
                'phoneNumber': '13233834422',
                'attributes': {
                    'u_name': 'Alice',
                    'age': 30
                }
            },
            {
                'phoneNumber': '13233834433',
                'attributes': {
                    'u_name': 'Mark',
                    'age': 45
                }
            },
            {
                'phoneNumber': '13233834488',
                'message': 'Hi ${u_name}, the megic number is ${magic_number}',
                'attributes': {
                    'u_name': 'Jane',
                    'magic_number': 10
                }
            }
        ],
        'message': 'Hello {u_name} ...'
    }
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)
[-python] [+php]
<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->createTextBroadcast();
        $body = '{
                    "name":"Charity SMS Campaign",
                    "labels":
                    [
                        "charity",
                        "id-10003"
                    ],
                    "fromNumber":"19206596476",
                    "recipients":
                    [
                        {
                            "phoneNumber":"13233834422",
                            "attributes":
                            {
                                "u_name": "Alice",
                                "age": 30
                            }
                        },
                        {
                            "phoneNumber":"13233834433",
                            "attributes":
                            {
                                "u_name": "Mark",
                                "age": 45
                            }
                        },
                        {
                            "phoneNumber":"13233834488",
                            "message": "Hi ${u_name}, the megic number is ${magic_number}",
                            "attributes":
                            {
                                "u_name": "Jane",
                                "magic_number": "10"
                            }
                        }
                    ],
                    "message":"Hello {u_name} ..."
                 }';
        $request->getOperationConfig()->setBodyParameter($body);
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}

ApiClientSample::main();
[-php] [[/code-container]]

See Create Text Broadcast API for detailed information about accepted parameters and responses.

What is the Voice Broadcast and how can it be used?

Voice Broadcasts allow you to send a pre-recorded voice message to a number of people. You can configure what message to play if the call is answered by a person, and set a different message to play if an answering machine is detected. Voice broadcasts can be configured to transfer a call when a transfer digit is pressed. The following settings are available for Call Broadcasts (Voice & IVR):

Story

Mary takes the phone numbers of Beaufort citizens and uploads them into CallFire. She prepares a small message, like: "Hello, this is Mary from the local branch of the non-profit agency. Don't miss our charity weekend taking place the first weekend of November. We are looking forward to meeting you there. Press '1' for more details." Beaufort citizens receive the Voice Broadcast call about the event and they can be immediately transferred to an agency representative. Mary receives the ticket orders. The agency has now sold a lot of tickets and begin to concentrate on organizing the charity event.

Let's see how to do that with the Call Broadcasts API.

Important note. There are different ways to send out a voice message to a list of recipients or to a single one using Voice Broadcast:

[[code-container]] [+curl] request:

#!/usr/bin/env bash

curl -u username:password -H "Content-Type:application/json" -X POST -d '
{
  "name": "Charity Campaign",
  "fromNumber": "12135551189",
  "answeringMachineConfig": "AM_AND_LIVE",
  "labels": [
    "charity",
    "id-10002"
  ],
  "sounds": {
    "liveSoundText": "Hello, this is Mary, from the local branch of Non-profit agency. Do not miss our charity weekend taking place at first November weekends. We are looking forward to meet you there. Press '1' to to find out more details.",
    "liveSoundTextVoice": "MALE1",
    "machineSoundText": "Hello, this is Mary, from the local branch of Non-profit agency. If you are interested in charity weekend, please call (231) 455-7676.",
    "machineSoundTextVoice": "MALE1",
    "transferSoundText": "Please wait a moment, call is being transfer.",
    "transferDigit": "1",
    "transferNumber": "12314557676",
  },
  "localTimeRestriction": {
    "beginHour": 9,
    "beginMinute": 0,
    "endHour": 18,
    "endMinute": 0
  },
  "schedules": [
    {
      "startTimeOfDay": {
        "hour": 10,
        "minute": 0,
        "second": 0
      },
      "daysOfWeek": [
        "MONDAY",
        "WEDNESDAY"
      ],
      "timeZone": "America/New_York",
      "startDate": {
        "year": 2016,
        "month": 12,
        "day": 1
      }
    }
  ],
  "retryConfig": {
    "maxAttempts": 2,
    "minutesBetweenAttempts": 5,
    "retryResults": [
      "BUSY",
      "NO_ANS"
    ],
    "retryPhoneTypes": [
      "MOBILE_PHONE",
      "WORK_PHONE"
    ]
  },
  "recipients": [
    {
      "phoneNumber": "12135551100",
      "attributes": {
        "age": "30",
        "position": "Manager"
      }
    },
    {
      "phoneNumber": "12135771188",
      "attributes": {
        "external_system_id": "34347770001",
        "call_label": "friends"
      }
    },
    {
      "contactId": 46000044001
    }
  ]
}' "https://api.callfire.com/v2/calls/broadcasts"
response:
{
  "id": 15
}
[-curl] [+java]
import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.campaigns.model.AnsweringMachineConfig;
import com.callfire.api.client.api.campaigns.model.CallBroadcast;
import com.callfire.api.client.api.campaigns.model.CallBroadcastSounds;
import com.callfire.api.client.api.campaigns.model.DayOfWeek;
import com.callfire.api.client.api.campaigns.model.LocalDate;
import com.callfire.api.client.api.campaigns.model.LocalTime;
import com.callfire.api.client.api.campaigns.model.LocalTimeRestriction;
import com.callfire.api.client.api.campaigns.model.Recipient;
import com.callfire.api.client.api.campaigns.model.RetryConfig;
import com.callfire.api.client.api.campaigns.model.RetryConfig.RetryPhoneTypes;
import com.callfire.api.client.api.campaigns.model.RetryConfig.RetryResults;
import com.callfire.api.client.api.campaigns.model.Schedule;
import com.callfire.api.client.api.campaigns.model.Voice;
import com.callfire.api.client.api.common.model.LocalDate;
import com.callfire.api.client.api.common.model.LocalTime;
import com.callfire.api.client.api.common.model.ResourceId;

import java.time.DayOfWeek;
import java.util.Arrays;
import java.util.HashSet;

/**
 * Example shows how to schedule a voice broadcast in a single call
 * and send a voice message to 3 recipients
 */
class CreateVoiceBroadcastSample {

    public static void main(String[] args) {
        CallfireClient client = new CallfireClient("api_login", "api_password");
        CallBroadcast broadcast = new CallBroadcast();
        broadcast.setName("Charity Campaign");
        // attach custom labels if needed
        broadcast.setLabels(Arrays.asList("charity", "id-10002"));
        // set validated Caller ID number. 
        broadcast.setFromNumber("12135551189");
        // set answering machine detection
        broadcast.setAnsweringMachineConfig(AnsweringMachineConfig.AM_AND_LIVE);

        // set voice messages using TTS option for Live answers and when Answering Machine is detected.
        // you also can set a pre-defined TTS voice.
        CallBroadcastSounds sounds = new CallBroadcastSounds();
        sounds.setLiveSoundText("Hello, this is Mary, from the local branch of Non-profit agency." +
            "Don't miss our charity weekend taking place at first November weekends. We are " +
            "looking forward to meet you there. Press '1' to to find out more details.");
        sounds.setLiveSoundTextVoice(Voice.MALE1);
        sounds.setMachineSoundText("Hello, this is Mary, from the local branch of Non-profit agency." +
            "If you are interested in charity weekend, please call (231) 455-7676.");
        sounds.setMachineSoundTextVoice(Voice.MALE1);
        sounds.setTransferDigit("1");
        // set number to transfer call to once transfer digit is pressed
        sounds.setTransferNumber("12314557676");
        sounds.setTransferSoundText("Please wait a moment, call is being transfer.");
        broadcast.setSounds(sounds);

        // allow CallFire to dial recipient only between 09:00 - 18:00 depending on
        //  recipient's number area code timezone
        LocalTimeRestriction timeRestriction = new LocalTimeRestriction();
        timeRestriction.setBeginHour(9);
        timeRestriction.setBeginMinute(0);
        timeRestriction.setEndHour(18);
        timeRestriction.setEndMinute(0);
        broadcast.setLocalTimeRestriction(timeRestriction);

        // set retry configuration to attempt a contact's Mobile and Work phone numbers twice in case Call was 
        //  resulted to BUSY or No Answer response. Set 5 minutes between attempts.  
        RetryConfig retryConfig = new RetryConfig();
        retryConfig.setMaxAttempts(2);
        retryConfig.setMinutesBetweenAttempts(5);
        retryConfig.setRetryResults(Arrays.asList(RetryResults.BUSY, RetryResults.NO_ANS));
        retryConfig.setRetryPhoneTypes(Arrays.asList(RetryPhoneTypes.MOBILE_PHONE, RetryPhoneTypes.WORK_PHONE));
        broadcast.setRetryConfig(retryConfig);

        // schedule a campaign to run on every Monday and Wednesday starting from 2016-12-01 10:00:00 
        Schedule schedule = new Schedule();
        schedule.setStartDate(new LocalDate(2016, 12, 1));
        schedule.setStartTimeOfDay(new LocalTime(10, 0, 0));
        // set weekly schedule
        schedule.setDaysOfWeek(new HashSet<>(Arrays.asList(DayOfWeek.MONDAY, DayOfWeek.WEDNESDAY)));
        // set optional time zone, if leave empty account's timezone will be used 
        schedule.setTimeZone("America/New_York");
        broadcast.setSchedules(Arrays.asList(schedule));

        // add new recipients
        Recipient recipient1 = new Recipient();
        recipient1.setPhoneNumber("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
        recipient1.getAttributes().put("age", "30");
        recipient1.getAttributes().put("position", "Manager");

        Recipient recipient2 = new Recipient();
        recipient2.setPhoneNumber("12135771188");
        recipient2.getAttributes().put("external_system_id", "34347770001");
        recipient2.getAttributes().put("call_label", "friends");

        // You can use already existing contacts as a recipients
        Recipient recipient3 = new Recipient();
        recipient3.setContactId(46000044001L);

        broadcast.setRecipients(Arrays.asList(recipient1, recipient2, recipient3));

        // create broadcast with 'start' argument = true to start campaign immediately
        ResourceId id = client.callBroadcastsApi().create(broadcast, false);

        System.out.println(id);
    }
}
[-java] [+csharp]
using System.Collections.Generic;
using CallfireApiClient;
using CallfireApiClient.Api.Campaigns.Model;
using CallfireApiClient.Api.Common.Model;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        var broadcast = new CallBroadcast
        {
            Name = "Charity Campaign",
            // set validated Caller ID number.
            FromNumber = "12135551189",
            // attach custom labels if needed
            Labels = new List<string> {"charity", "id-10002"},
            // set answering machine detection
            AnsweringMachineConfig = AnsweringMachineConfig.AM_AND_LIVE,
            // set voice messages using TTS option for Live answers and when Answering Machine is detected.
            // you also can set a pre-defined TTS voice.
            Sounds = new CallBroadcastSounds
            {
                LiveSoundText = "Hello, this is Mary, from the local branch of Non-profit agency. " +
                                "Do not miss our charity weekend taking place at first November weekends." +
                                " We are looking forward to meet you there. Press '1' to to find out more details.",
                LiveSoundTextVoice = Voice.MALE1,
                MachineSoundText = "Hello, this is Mary, from the local branch of Non-profit agency. " +
                                   "If you are interested in charity weekend, please call (231) 455-7676.",
                MachineSoundTextVoice = Voice.MALE1,
                TransferSoundText = "Please wait a moment, call is being transfer.",
                // set number to transfer call to once transfer digit is pressed
                TransferDigit = "1",
                TransferNumber = "12314557676"
            },
            // allow CallFire to dial recipient only between 09:00 - 18:00 depending on
            //  recipient's number area code timezone
            LocalTimeRestriction = new LocalTimeRestriction
            {
                BeginHour = 9,
                BeginMinute = 0,
                EndHour = 18,
                EndMinute = 0
            },
            // schedule a campaign to run on every Monday and Wednesday starting from 2016-12-01 10:00:00
            Schedules = new List<Schedule>
            {
                new Schedule
                {
                    StartDate = new LocalDate {Year = 2016, Month = 12, Day = 1},
                    StartTimeOfDay = new LocalTime {Hour = 10, Minute = 0, Second = 0},
                    // set weekly schedule
                    DaysOfWeek = new HashSet<DayOfWeek> {DayOfWeek.MONDAY, DayOfWeek.WEDNESDAY},
                    // set optional time zone, if leave empty account's timezone will be used
                    TimeZone = "America/New_York"
                }
            },
            // set retry configuration to attempt a contact's Mobile and Work phone numbers twice in case Call was
            //  resulted to BUSY or No Answer response. Set 5 minutes between attempts.
            RetryConfig = new RetryConfig
            {
                MaxAttempts = 2,
                MinutesBetweenAttempts = 5,
                RetryResults = new List<RetryResults> {RetryResults.BUSY, RetryResults.NO_ANS},
                RetryPhoneTypes = new List<RetryPhoneTypes>
                {
                    RetryPhoneTypes.MOBILE_PHONE,
                    RetryPhoneTypes.WORK_PHONE
                }
            },
            // add new recipients
            Recipients = new List<Recipient>
            {
                new Recipient
                {
                    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>
                    {
                        {"age", "30"},
                        {"position", "Manager"}
                    }
                },
                new Recipient
                {
                    PhoneNumber = "12135771188",
                    Attributes = new Dictionary<string, string>
                    {
                        {"external_system_id", "34347770001"},
                        {"call_label", "friends"}
                    }
                },
                // You can use already existing contacts as a recipients
                new Recipient
                {
                    ContactId = 46000044001
                }
            }
        };

        // create broadcast with 'start' argument = true to start campaign immediately
        var id = client.CallBroadcastsApi.Create(broadcast);
    }
}
[-csharp] [+js]
'strict'

const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');

client.ready(() => {
    client.calls.createCallBroadcast({
      body: {
        name: 'Charity Campaign',
        fromNumber: '12135551189',
        answeringMachineConfig: 'AM_AND_LIVE',
        labels: [
          'charity',
          'id-10002'
        ],
        sounds: {
          liveSoundText: 'Hello, this is Mary, from the local branch of Non-profit agency. Do not miss our charity weekend taking place at first November weekends. We are looking forward to meet you there. Press 1 to to find out more details.',
          liveSoundTextVoice: 'MALE1',
          machineSoundText: 'Hello, this is Mary, from the local branch of Non-profit agency. If you are interested in charity weekend, please call (231) 455-7676.',
          machineSoundTextVoice: 'MALE1',
          transferSoundText: 'Please wait a moment, call is being transfer.',
          transferDigit: 1,
          transferNumber: '12314557676',
        },
        localTimeRestriction: {
          beginHour: 9,
          beginMinute: 0,
          endHour: 18,
          endMinute: 0
        },
        schedules: [
          {
            startTimeOfDay: {
              hour: 10,
              minute: 0,
              second: 0
            },
            daysOfWeek: [
              'MONDAY',
              'WEDNESDAY'
            ],
            timeZone: 'America/New_York',
            startDate: {
              year: 2016,
              month: 12,
              day: 1
            }
          }
        ],
        retryConfig: {
          maxAttempts: 2,
          minutesBetweenAttempts: 5,
          retryResults: [
            'BUSY',
            'NO_ANS'
          ],
          retryPhoneTypes: [
            'MOBILE_PHONE',
            'WORK_PHONE'
          ]
        },
        recipients: [
          {
            phoneNumber: '12135551100',
            attributes: {
              age: 30,
              position: 'Manager'
            }
          },
          {
            phoneNumber: '12135771188',
            attributes: {
              external_system_id: 34347770001,
              call_label: 'friends'
            }
          },
          {
            contactId: 46000044001
          }
        ]
      }
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);
[-js] [+python]
from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.calls.createCallBroadcast(
    body={
        'name': 'Charity Campaign',
        'fromNumber': '12135551189',
        'answeringMachineConfig': 'AM_AND_LIVE',
        'labels': [
            'charity',
            'id-10002'
        ],
        'sounds': {
            'liveSoundText': 'Hello, this is Mary, from the local branch of Non-profit agency. Do not miss our charity weekend taking place at first November weekends. We are looking forward to meet you there. Press 1 to to find out more details.',
            'liveSoundTextVoice': 'MALE1',
            'machineSoundText': 'Hello, this is Mary, from the local branch of Non-profit agency. If you are interested in charity weekend, please call (231) 455-7676.',
            'machineSoundTextVoice': 'MALE1',
            'transferSoundText': 'Please wait a moment, call is being transfer.',
            'transferDigit': 1,
            'transferNumber': '12314557676',
        },
        'localTimeRestriction': {
            'beginHour': 9,
            'beginMinute': 0,
            'endHour': 18,
            'endMinute': 0
        },
        'schedules': [
            {
                'startTimeOfDay': {
                    'hour': 10,
                    'minute': 0,
                    'second': 0
                },
                'daysOfWeek': [
                    'MONDAY',
                    'WEDNESDAY'
                ],
                'timeZone': 'America/New_York',
                'startDate': {
                    'year': 2016,
                    'month': 12,
                    'day': 1
                }
            }
        ],
        'retryConfig': {
            'maxAttempts': 2,
            'minutesBetweenAttempts': 5,
            'retryResults': [
                'BUSY',
                'NO_ANS'
            ],
            'retryPhoneTypes': [
                'MOBILE_PHONE',
                'WORK_PHONE'
            ]
        },
        'recipients': [
            {
                'phoneNumber': '12135551100',
                'attributes': {
                    'age': 30,
                    'position': 'Manager'
                }
            },
            {
                'phoneNumber': '12135771188',
                'attributes': {
                    'external_system_id': 34347770001,
                    'call_label': 'friends'
                }
            },
            {
                'contactId': 46000044001
            }
        ]
    }
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)
[-python] [+php]
<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->createCallBroadcast();
        $body = '{
                    "name": "Charity Campaign",
                    "fromNumber": "12135551189",
                    "answeringMachineConfig": "AM_AND_LIVE",
                    "labels":
                    [
                        "charity",
                        "id-10002"
                    ],
                    "sounds":
                    {
                        "liveSoundText": "Hello, this is Mary, from the local branch of Non-profit agency. Do not miss our charity weekend taking place at first November weekends. We are looking forward to meet you there. Press 1 to to find out more details.",
                        "liveSoundTextVoice": "MALE1",
                        "machineSoundText": "Hello, this is Mary, from the local branch of Non-profit agency. If you are interested in charity weekend, please call (231) 455-7676.",
                        "machineSoundTextVoice": "MALE1",
                        "transferSoundText": "Please wait a moment, call is being transfer.",
                        "transferDigit": "1",
                        "transferNumber": "12314557676",
                    },
                    "localTimeRestriction":
                    {
                        "beginHour": 9,
                        "beginMinute": 0,
                        "endHour": 18,
                        "endMinute": 0
                    },
                    "schedules":
                    [
                        {
                            "startTimeOfDay":
                            {
                                "hour": 10,
                                "minute": 0,
                                "second": 0
                            },
                            "daysOfWeek":
                            [
                                "MONDAY",
                                "WEDNESDAY"
                            ],
                            "timeZone": "America/New_York",
                            "startDate":
                            {
                                "year": 2016,
                                "month": 12,
                                "day": 1
                            }
                        }
                    ],
                    "retryConfig":
                    {
                        "maxAttempts": 2,
                        "minutesBetweenAttempts": 5,
                        "retryResults":
                        [
                            "BUSY",
                            "NO_ANS"
                        ],
                        "retryPhoneTypes":
                        [
                            "MOBILE_PHONE",
                            "WORK_PHONE"
                        ]
                    },
                    "recipients":
                    [
                        {
                            "phoneNumber": "12135551100",
                            "attributes":
                            {
                                "age": "30",
                                "position": "Manager"
                            }
                        },
                        {
                            "phoneNumber": "12135771188",
                            "attributes":
                            {
                                "external_system_id": "34347770001",
                                "call_label": "friends"
                            }
                        },
                        {
                            "contactId": 46000044001
                        }
                    ]
                 }';
        $request->getOperationConfig()->setBodyParameter($body);
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}

ApiClientSample::main();
[-php] [[/code-container]]

See Create Call Broadcast API for detailed information about accepted parameters and responses.

What is the IVR Broadcast and how can it be used?

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.

You can set up an outbound IVR which allows you to fine-tune a Voice Broadcast with additional settings and advanced configuration options. IVR Broadcasts can be sent to your contacts, providing live call recipients with multiple transfer options and/or the ability to collect their responses. Some popular use cases for outbound IVRs include political polls, appointment confirmations, and different kinds of surveys.

Story

The charity has plans to attract donations both by selling entrance tickets and home-made baked goods. It is easy to do this having a contact list of people who may be interested in participating. Mary, a member of the non-profit agency, prepares a small survey and addresses it via IVR to phone numbers from her phone book. CallFire calls everyone and plays the message: "Hello, we are organizing a charity weekend in November. Don't miss it. Press 1 for instructions on ordering tickets, press 2 if you are willing to volunteer at the event." This way, the agency can attempt to raise money and then focus on organizing the event with increased volunteer support.

You can achieve this goal in two steps:

Example of IVR XML dialplan:

<dialplan name="Root">
    <!-- answering machine detection -->
    <amd>
        <!-- if call is answered by human go to live menu -->
        <live>
            <goto name="goto_Live">Live</goto>
        </live>
        <machine>
            <goto name="goto_Machine">Machine</goto>
        </machine>
    </amd>
    <menu maxDigits="1" timeout="3500" name="Live">
        <play type="tts" voice="female1" name="play_Live">
            Hello ${contact.firstName}, we are organizing a charity weekend in November.
            Don't miss to visit it. Press "1" to follow the instructions how to order the 
            tickets, press "2" if you are willing to become a volunteer at event.
        </play>
        <keypress pressed="1" name="kp_order_tickets">
             <!-- store recipient's answer and go to another menu to make a purchase -->
            <stash varname="order" name="create_an_order">Yes</stash>
            <goto>order_tickets</goto>
        </keypress>
        <keypress pressed="2" name="kp_become_volonteer">
            <!-- store recipient's answer -->
            <stash varname="volonteer" name="become_volonteer">Yes</stash>
            <play type="tts" voice="female1" name="play_Goodbye_1">Thanks for the response. We will call you later today.</play>
            <goto>Hangup</goto>
        </keypress>
         <!-- if pressed key is not specified in menu replay Live menu -->
        <keypress pressed="default" name="incorrect_Selection">
            <play type="tts" voice="female1" name="play_Inorrect_Selection">That is not a valid selection. Please try again.</play>
            <goto name="replay_Live">Live</goto>
        </keypress>
    </menu>
    <menu maxDigits="1" timeout="3500" name="order_tickets">
        <play type="tts" voice="female1" name="play_order_tickets">
            You will be transferred to Sales representative in a moment. Please wait.
        </play>
        <transfer callerid="${call.callerid}" musiconhold="blues" mode="ringall">
            15551234567
        </transfer>
    </menu>
    <play type="tts" voice="female1" name="Goodbye">
        Thank you for taking our survey
    </play>
    <goto name="Goodbye_Hangup">Hangup</goto>
    <play type="tts" voice="female1" name="Machine">
        Hello ${contact.firstName} ${contact.lastName}. 
        We are organizing a charity weekend in November.
        If you would like to participate, please call 8 5 5, 5 5 5, 5 5 5 5. 
        Thank you.
    </play>
    <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 detailed descriptions of all IVR tags.

The following code samples show how to create an IVR broadcast with an XML dialplan, schedule it, set up retry configuration, and some other things which are available in a Voice broadcast.

[[code-container]] [+curl] request:

#!/usr/bin/env bash

curl -u username:password -H "Content-Type:application/json" -X POST -d '
{
  "name": "Charity Campaign",
  "fromNumber": "12135551189",
  "labels": [
    "charity",
    "id-10002"
  ],
  "localTimeRestriction": {
    "beginHour": 9,
    "beginMinute": 0,
    "endHour": 18,
    "endMinute": 0
  },
  "schedules": [
    {
      "startTimeOfDay": {
        "hour": 10,
        "minute": 0,
        "second": 0
      },
      "daysOfWeek": [
        "MONDAY",
        "WEDNESDAY"
      ],
      "timeZone": "America/New_York",
      "startDate": {
        "year": 2016,
        "month": 12,
        "day": 1
      }
    }
  ],
  "retryConfig": {
    "maxAttempts": 2,
    "minutesBetweenAttempts": 5,
    "retryResults": [
      "BUSY",
      "NO_ANS"
    ],
    "retryPhoneTypes": [
      "MOBILE_PHONE",
      "WORK_PHONE"
    ]
  },
  "recipients": [
    {
      "phoneNumber": "12135551100",
      "attributes": {
        "age": "30",
        "position": "Manager"
      }
    },
    {
      "phoneNumber": "12135771188",
      "attributes": {
        "external_system_id": "34347770001",
        "call_label": "friends"
      }
    },
    {
      "contactId": 46000044001
    }
  ],  
  "dialPlanXml": "<dialplan name=\"Root\"> <!-- answering machine detection --> <amd> <!-- if call is answered by human go to live menu --> <live> <goto name=\"goto_Live\">Live</goto> </live> <machine> <goto name=\"goto_Machine\">Machine</goto> </machine> </amd> <menu maxDigits=\"1\" timeout=\"3500\" name=\"Live\"> <play type=\"tts\" voice=\"female1\" name=\"play_Live\"> Hello ${contact.firstName}, we are organizing a charity weekend in November. Do not miss to visit it. Press \"1\" to follow the instructions how to order the tickets, press \"2\" if you are willing to become a volunteer at event. </play> <keypress pressed=\"1\" name=\"kp_order_tickets\"> <!-- store recipients answer and go to another menu to make a purchase --> <stash varname=\"order\" name=\"create_an_order\">Yes</stash> <goto>order_tickets</goto> </keypress> <keypress pressed=\"2\" name=\"kp_become_volonteer\"> <!-- store recipients answer --> <stash varname=\"volonteer\" name=\"become_volonteer\">Yes</stash> <play type=\"tts\" voice=\"female1\" name=\"play_Goodbye_1\">Thanks for the response. We will call you later today.</play> <goto>Hangup</goto> </keypress> <!-- if pressed key is not specified in menu replay Live menu --> <keypress pressed=\"default\" name=\"incorrect_Selection\"> <play type=\"tts\" voice=\"female1\" name=\"play_Inorrect_Selection\">That is not a valid selection. Please try again.</play> <goto name=\"replay_Live\">Live</goto> </keypress> </menu> <menu maxDigits=\"1\" timeout=\"3500\" name=\"order_tickets\"> <play type=\"tts\" voice=\"female1\" name=\"play_order_tickets\"> You will be transferred to Sales representative in a moment. Please wait. </play> <transfer callerid=\"${call.callerid}\" musiconhold=\"blues\" mode=\"ringall\"> 15551234567 </transfer> </menu> <play type=\"tts\" voice=\"female1\" name=\"Goodbye\"> Thank you for taking our survey </play> <goto name=\"Goodbye_Hangup\">Hangup</goto> <play type=\"tts\" voice=\"female1\" name=\"Machine\"> Hello ${contact.firstName} ${contact.lastName}. We are organizing a charity weekend in November. If you would like to participate, please call 8 5 5, 5 5 5, 5 5 5 5. Thank you. </play> <hangup name=\"Hangup\"/> </dialplan>"
}' "https://api.callfire.com/v2/calls/broadcasts"
response:
{
  "id": 15
}
[-curl] [+java]
import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.campaigns.model.CallBroadcast;
import com.callfire.api.client.api.campaigns.model.LocalTimeRestriction;
import com.callfire.api.client.api.campaigns.model.Recipient;
import com.callfire.api.client.api.campaigns.model.RetryConfig;
import com.callfire.api.client.api.campaigns.model.RetryConfig.RetryPhoneTypes;
import com.callfire.api.client.api.campaigns.model.RetryConfig.RetryResults;
import com.callfire.api.client.api.campaigns.model.Schedule;
import com.callfire.api.client.api.common.model.LocalDate;
import com.callfire.api.client.api.common.model.LocalTime;
import com.callfire.api.client.api.common.model.ResourceId;

import java.time.DayOfWeek;
import java.util.Arrays;
import java.util.HashSet;

class CreateVoiceBroadcastSample {

    public static void main(String[] args) {
        CallfireClient client = new CallfireClient("api_login", "api_password");
        CallBroadcast broadcast = new CallBroadcast();
        broadcast.setName("Charity Campaign");
        // attach custom labels if needed
        broadcast.setLabels(Arrays.asList("charity", "id-10002"));
        // set validated Caller ID number. 
        broadcast.setFromNumber("12135551189");
        // add IVR XML
        broadcast.setDialplanXml(buildDialplanXml());

        // allow CallFire to dial recipient only between 09:00 - 18:00 depending on
        //  recipient's number area code timezone
        LocalTimeRestriction timeRestriction = new LocalTimeRestriction();
        timeRestriction.setBeginHour(10);
        timeRestriction.setBeginMinute(0);
        timeRestriction.setEndHour(18);
        timeRestriction.setEndMinute(0);
        broadcast.setLocalTimeRestriction(timeRestriction);

        // set retry configuration to attempt a contact's Mobile and Work phone numbers twice in case Call was 
        //  resulted to BUSY or No Answer response. Set 5 minutes between attempts.  
        RetryConfig retryConfig = new RetryConfig();
        retryConfig.setMaxAttempts(2);
        retryConfig.setMinutesBetweenAttempts(5);
        retryConfig.setRetryResults(Arrays.asList(RetryResults.BUSY, RetryResults.NO_ANS));
        retryConfig.setRetryPhoneTypes(Arrays.asList(RetryPhoneTypes.MOBILE_PHONE, RetryPhoneTypes.WORK_PHONE));
        broadcast.setRetryConfig(retryConfig);

        // schedule a campaign to run on every Monday and Wednesday starting from 2016-12-01 10:00:00 
        Schedule schedule = new Schedule();
        schedule.setStartDate(new LocalDate(2016, 12, 1));
        schedule.setStartTimeOfDay(new LocalTime(10, 0, 0));
        // set weekly schedule
        schedule.setDaysOfWeek(new HashSet<>(Arrays.asList(DayOfWeek.MONDAY, DayOfWeek.WEDNESDAY)));
        // set optional time zone, if leave empty account's timezone will be used 
        schedule.setTimeZone("America/New_York");
        broadcast.setSchedules(Arrays.asList(schedule));

        // add new recipients
        Recipient recipient1 = new Recipient();
        recipient1.setPhoneNumber("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
        recipient1.getAttributes().put("age", "30");
        recipient1.getAttributes().put("position", "Manager");

        Recipient recipient2 = new Recipient();
        recipient2.setPhoneNumber("12135771188");
        recipient2.getAttributes().put("external_system_id", "34347770001");
        recipient2.getAttributes().put("call_label", "friends");

        // You can use already existing contacts as a recipients
        Recipient recipient3 = new Recipient();
        recipient3.setContactId(46000044001L);

        broadcast.setRecipients(Arrays.asList(recipient1, recipient2, recipient3));

        // create broadcast with 'start' argument = true to start campaign immediately
        ResourceId id = client.callBroadcastsApi().create(broadcast, true);

        System.out.println(id);
    }

    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=\"goto_Live\">Live</goto>                                   "
                + "    </live>                                                                    "
                + "    <machine>                                                                  "
                + "        <goto name=\"goto_Machine\">Machine</goto>                             "
                + "    </machine>                                                                 "
                + "</amd>                                                                         "
                + "<menu maxDigits=\"1\" timeout=\"3500\" name=\"Live\">                          "
                + "    <play type=\"tts\" voice=\"female1\" name=\"play_Live\">                   "
                + "Hello ${contact.firstName}, we are organizing a charity weekend in November.   "
                + "Don't miss to visit it. Press \"1\" to follow the instructions how to order the"
                + "tickets, press \"2\" if you are willing to become a volunteer at event.        "
                + "    </play>                                                                    "
                + "<keypress pressed=\"1\" name=\"kp_order_tickets\">                             "
                + "    <!-- store recipient's answer and go to another menu to make a purchase -->"
                + "    <stash varname=\"order\" name=\"create_an_order\">Yes</stash>              "
                + "    <goto>order_tickets</goto>                                                 "
                + "</keypress>                                                                    "
                + "<keypress pressed=\"2\" name=\"kp_become_volonteer\">                          "
                + "    <!-- store recipient's answer -->                                          "
                + "    <stash varname=\"volonteer\" name=\"become_volonteer\">Yes</stash>         "
                + "    <play type=\"tts\" voice=\"female1\" name=\"play_Goodbye_1\">Thanks for the"
                + "        Thanks for the response. We will call you later today.                 "
                + "    </play>                                                                    "
                + "    <goto>Hangup</goto>                                                        "
                + "</keypress>                                                                    "
                + "<!-- if pressed key is not specified in menu replay Live menu -->              "
                + "<keypress pressed=\"default\" name=\"incorrect_Selection\">                    "
                + "    <play type=\"tts\" voice=\"female1\" name=\"play_Inorrect_Selection\">That "
                + "        That is not a valid selection. Please try again.                       "
                + "    </play>                                                                    "
                + "    <goto name=\"replay_Live\">Live</goto>                                     "
                + "</keypress>                                                                    "
                + "</menu>                                                                        "
                + "<menu maxDigits=\"1\" timeout=\"3500\" name=\"order_tickets\">                 "
                + "    <play type=\"tts\" voice=\"female1\" name=\"play_order_tickets\">          "
                + "    You will be transferred to Sales representative in a moment. Please wait.  "
                + "    </play>                                                                    "
                + "    <transfer callerid=\"${call.callerid}\" musiconhold=\"blues\" mode=\"ringall\">"
                + "        15551234567                                                            "
                + "    </transfer>                                                                "
                + "</menu>                                                                        "
                + "<play type=\"tts\" voice=\"female1\" name=\"Goodbye\">                         "
                + "    Thank you for taking our survey                                            "
                + "</play>                                                                        "
                + "<goto name=\"Goodbye_Hangup\">Hangup</goto>                                    "
                + "<play type=\"tts\" voice=\"female1\" name=\"Machine\">                         "
                + "Hello ${contact.firstName} ${contact.lastName}.                                "
                + "We are organizing a charity weekend in November.                               "
                + "If you would like to participate, please call 8 5 5, 5 5 5, 5 5 5 5.           "
                + "Thank you.                                                                     "
                + "</play>                                                                        "
                + "<hangup name=\"Hangup\"/>                                                      "
                + "</dialplan>";
    }
}
[-java] [+csharp]
using System.Collections.Generic;
using CallfireApiClient;
using CallfireApiClient.Api.Campaigns.Model;
using CallfireApiClient.Api.Common.Model;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        var broadcast = new CallBroadcast
        {
            Name = "Charity Campaign",
            // set validated Caller ID number.
            FromNumber = "12135551189",
            // attach custom labels if needed
            Labels = new List<string> {"charity", "id-10002"},
            // allow CallFire to dial recipient only between 09:00 - 18:00 depending on
            //  recipient's number area code timezone
            LocalTimeRestriction = new LocalTimeRestriction
            {
                BeginHour = 9,
                BeginMinute = 0,
                EndHour = 18,
                EndMinute = 0
            },
            // schedule a campaign to run on every Monday and Wednesday starting from 2016-12-01 10:00:00
            Schedules = new List<Schedule>
            {
                new Schedule
                {
                    StartDate = new LocalDate {Year = 2016, Month = 12, Day = 1},
                    StartTimeOfDay = new LocalTime {Hour = 10, Minute = 0, Second = 0},
                    // set weekly schedule
                    DaysOfWeek = new HashSet<DayOfWeek> {DayOfWeek.MONDAY, DayOfWeek.WEDNESDAY},
                    // set optional time zone, if leave empty account's timezone will be used
                    TimeZone = "America/New_York"
                }
            },
            // set retry configuration to attempt a contact's Mobile and Work phone numbers twice in case Call was
            //  resulted to BUSY or No Answer response. Set 5 minutes between attempts.
            RetryConfig = new RetryConfig
            {
                MaxAttempts = 2,
                MinutesBetweenAttempts = 5,
                RetryResults = new List<RetryResults> {RetryResults.BUSY, RetryResults.NO_ANS},
                RetryPhoneTypes = new List<RetryPhoneTypes>
                {
                    RetryPhoneTypes.MOBILE_PHONE,
                    RetryPhoneTypes.WORK_PHONE
                }
            },
            // set IVR XML
            DialplanXml = @"
                <dialplan name=""Root"">
                    <!-- answering machine detection -->
                    <amd>
                        <!-- if call is answered by human go to live menu -->
                        <live>
                            <goto name=""goto_Live"">Live</goto>
                        </live>
                        <machine>
                            <goto name=""goto_Machine"">Machine</goto>
                        </machine>
                    </amd>
                    <menu maxDigits=""1"" timeout=""3500"" name=""Live"">
                        <play type=""tts"" voice=""female1"" name=""play_Live"">
                            Hello ${contact.firstName}, we are organizing a charity weekend in November.
                            Don't miss to visit it. Press ""1"" to follow the instructions how to order the 
                            tickets, press ""2"" if you are willing to become a volunteer at event.
                        </play>
                        <keypress pressed=""1"" name=""kp_order_tickets"">
                             <!-- store recipient's answer and go to another menu to make a purchase -->
                            <stash varname=""order"" name=""create_an_order"">Yes</stash>
                            <goto>order_tickets</goto>
                        </keypress>
                        <keypress pressed=""2"" name=""kp_become_volonteer"">
                            <!-- store recipient's answer -->
                            <stash varname=""volonteer"" name=""become_volonteer"">Yes</stash>
                            <play type=""tts"" voice=""female1"" name=""play_Goodbye_1"">
                                Thanks for the response. We will call you later today.
                            </play>
                            <goto>Hangup</goto>
                        </keypress>
                         <!-- if pressed key is not specified in menu replay Live menu -->
                        <keypress pressed=""default"" name=""incorrect_Selection"">
                            <play type=""tts"" voice=""female1"" name=""play_Inorrect_Selection"">
                                That is not a valid selection. Please try again.
                            </play>
                            <goto name=""replay_Live"">Live</goto>
                        </keypress>
                    </menu>
                    <menu maxDigits=""1"" timeout=""3500"" name=""order_tickets"">
                        <play type=""tts"" voice=""female1"" name=""play_order_tickets"">
                            You will be transferred to Sales representative in a moment. Please wait.
                        </play>
                        <transfer callerid=""${call.callerid}"" musiconhold=""blues"" mode=""ringall"">
                            15551234567
                        </transfer>
                    </menu>
                    <play type=""tts"" voice=""female1"" name=""Goodbye"">
                        Thank you for taking our survey
                    </play>
                    <goto name=""Goodbye_Hangup"">Hangup</goto>
                    <play type=""tts"" voice=""female1"" name=""Machine"">
                        Hello ${contact.firstName} ${contact.lastName}. 
                        We are organizing a charity weekend in November.
                        If you would like to participate, please call 8 5 5, 5 5 5, 5 5 5 5. 
                        Thank you.
                    </play>
                    <hangup name=""Hangup""/>
                </dialplan>
            ",
            // add new recipients
            Recipients = new List<Recipient>
            {
                new Recipient
                {
                    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>
                    {
                        {"age", "30"},
                        {"position", "Manager"}
                    }
                },
                new Recipient
                {
                    PhoneNumber = "12135771188",
                    Attributes = new Dictionary<string, string>
                    {
                        {"external_system_id", "34347770001"},
                        {"call_label", "friends"}
                    }
                },
                // You can use already existing contacts as a recipients
                new Recipient
                {
                    ContactId = 46000044001
                }
            }
        };

        // create broadcast with 'start' argument = true to start campaign immediately
        var id = client.CallBroadcastsApi.Create(broadcast, false);
    }
}
[-csharp] [+js]
'strict'

const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');

client.ready(() => {
    client.calls.createCallBroadcast({
      body: {
        name: 'Charity Campaign',
        fromNumber: '12135551189',
        labels: [
          'charity',
          'id-10002'
        ],
        localTimeRestriction: {
          beginHour: 9,
          beginMinute: 0,
          endHour: 18,
          endMinute: 0
        },
        schedules: [
          {
            startTimeOfDay: {
              hour: 10,
              minute: 0,
              second: 0
            },
            daysOfWeek: [
              'MONDAY',
              'WEDNESDAY'
            ],
            timeZone: 'America/New_York',
            startDate: {
              year: 2016,
              month: 12,
              day: 1
            }
          }
        ],
        retryConfig: {
          maxAttempts: 2,
          minutesBetweenAttempts: 5,
          retryResults: [
            'BUSY',
            'NO_ANS'
          ],
          retryPhoneTypes: [
            'MOBILE_PHONE',
            'WORK_PHONE'
          ]
        },
        recipients: [
          {
            phoneNumber: '12135551100',
            attributes: {
              age: 30,
              position: 'Manager'
            }
          },
          {
            phoneNumber: '12135771188',
            attributes: {
              external_system_id: 34347770001,
              call_label: 'friends'
            }
          },
          {
            contactId: 46000044001
          }
        ],
        dialPlanXml: '<dialplan name=\"Root\"> <!-- answering machine detection --> <amd> <!-- if call is answered by human go to live menu --> <live> <goto name=\"goto_Live\">Live</goto> </live> <machine> <goto name=\"goto_Machine\">Machine</goto> </machine> </amd> <menu maxDigits=\"1\" timeout=\"3500\" name=\"Live\"> <play type=\"tts\" voice=\"female1\" name=\"play_Live\"> Hello ${contact.firstName}, we are organizing a charity weekend in November. Do not miss to visit it. Press \"1\" to follow the instructions how to order the tickets, press \"2\" if you are willing to become a volunteer at event. </play> <keypress pressed=\"1\" name=\"kp_order_tickets\"> <!-- store recipients answer and go to another menu to make a purchase --> <stash varname=\"order\" name=\"create_an_order\">Yes</stash> <goto>order_tickets</goto> </keypress> <keypress pressed=\"2\" name=\"kp_become_volonteer\"> <!-- store recipients answer --> <stash varname=\"volonteer\" name=\"become_volonteer\">Yes</stash> <play type=\"tts\" voice=\"female1\" name=\"play_Goodbye_1\">Thanks for the response. We will call you later today.</play> <goto>Hangup</goto> </keypress> <!-- if pressed key is not specified in menu replay Live menu --> <keypress pressed=\"default\" name=\"incorrect_Selection\"> <play type=\"tts\" voice=\"female1\" name=\"play_Inorrect_Selection\">That is not a valid selection. Please try again.</play> <goto name=\"replay_Live\">Live</goto> </keypress> </menu> <menu maxDigits=\"1\" timeout=\"3500\" name=\"order_tickets\"> <play type=\"tts\" voice=\"female1\" name=\"play_order_tickets\"> You will be transferred to Sales representative in a moment. Please wait. </play> <transfer callerid=\"${call.callerid}\" musiconhold=\"blues\" mode=\"ringall\"> 15551234567 </transfer> </menu> <play type=\"tts\" voice=\"female1\" name=\"Goodbye\"> Thank you for taking our survey </play> <goto name=\"Goodbye_Hangup\">Hangup</goto> <play type=\"tts\" voice=\"female1\" name=\"Machine\"> Hello ${contact.firstName} ${contact.lastName}. We are organizing a charity weekend in November. If you would like to participate, please call 8 5 5, 5 5 5, 5 5 5 5. Thank you. </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);
  }
);
[-js] [+python]
from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.calls.createCallBroadcast(
    body={
        'name': 'Charity Campaign',
        'fromNumber': '12135551189',
        'labels': [
            'charity',
            'id-10002'
        ],
        'localTimeRestriction': {
            'beginHour': 9,
            'beginMinute': 0,
            'endHour': 18,
            'endMinute': 0
        },
        'schedules': [
            {
                'startTimeOfDay': {
                    'hour': 10,
                    'minute': 0,
                    'second': 0
                },
                'daysOfWeek': [
                    'MONDAY',
                    'WEDNESDAY'
                ],
                'timeZone': 'America/New_York',
                'startDate': {
                    'year': 2016,
                    'month': 12,
                    'day': 1
                }
            }
        ],
        'retryConfig': {
            'maxAttempts': 2,
            'minutesBetweenAttempts': 5,
            'retryResults': [
                'BUSY',
                'NO_ANS'
            ],
            'retryPhoneTypes': [
                'MOBILE_PHONE',
                'WORK_PHONE'
            ]
        },
        'recipients': [
            {
                'phoneNumber': '12135551100',
                'attributes': {
                    'age': 30,
                    'position': 'Manager'
                }
            },
            {
                'phoneNumber': '12135771188',
                'attributes': {
                    'external_system_id': 34347770001,
                    'call_label': 'friends'
                }
            },
            {
                'contactId': 46000044001
            }
        ],
        'dialPlanXml': '<dialplan name=\"Root\"> <!-- answering machine detection --> <amd> <!-- if call is answered by human go to live menu --> <live> <goto name=\"goto_Live\">Live</goto> </live> <machine> <goto name=\"goto_Machine\">Machine</goto> </machine> </amd> <menu maxDigits=\"1\" timeout=\"3500\" name=\"Live\"> <play type=\"tts\" voice=\"female1\" name=\"play_Live\"> Hello ${contact.firstName}, we are organizing a charity weekend in November. Do not miss to visit it. Press \"1\" to follow the instructions how to order the tickets, press \"2\" if you are willing to become a volunteer at event. </play> <keypress pressed=\"1\" name=\"kp_order_tickets\"> <!-- store recipients answer and go to another menu to make a purchase --> <stash varname=\"order\" name=\"create_an_order\">Yes</stash> <goto>order_tickets</goto> </keypress> <keypress pressed=\"2\" name=\"kp_become_volonteer\"> <!-- store recipients answer --> <stash varname=\"volonteer\" name=\"become_volonteer\">Yes</stash> <play type=\"tts\" voice=\"female1\" name=\"play_Goodbye_1\">Thanks for the response. We will call you later today.</play> <goto>Hangup</goto> </keypress> <!-- if pressed key is not specified in menu replay Live menu --> <keypress pressed=\"default\" name=\"incorrect_Selection\"> <play type=\"tts\" voice=\"female1\" name=\"play_Inorrect_Selection\">That is not a valid selection. Please try again.</play> <goto name=\"replay_Live\">Live</goto> </keypress> </menu> <menu maxDigits=\"1\" timeout=\"3500\" name=\"order_tickets\"> <play type=\"tts\" voice=\"female1\" name=\"play_order_tickets\"> You will be transferred to Sales representative in a moment. Please wait. </play> <transfer callerid=\"${call.callerid}\" musiconhold=\"blues\" mode=\"ringall\"> 15551234567 </transfer> </menu> <play type=\"tts\" voice=\"female1\" name=\"Goodbye\"> Thank you for taking our survey </play> <goto name=\"Goodbye_Hangup\">Hangup</goto> <play type=\"tts\" voice=\"female1\" name=\"Machine\"> Hello ${contact.firstName} ${contact.lastName}. We are organizing a charity weekend in November. If you would like to participate, please call 8 5 5, 5 5 5, 5 5 5 5. Thank you. </play> <hangup name=\"Hangup\"/> </dialplan>'
    }
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)
[-python] [+php]
<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->createCallBroadcast();
        $body = '{
                    "name": "Charity Campaign",
                    "fromNumber": "12135551189",
                    "labels":
                    [
                        "charity",
                        "id-10002"
                    ],
                    "localTimeRestriction":
                    {
                        "beginHour": 9,
                        "beginMinute": 0,
                        "endHour": 18,
                        "endMinute": 0
                    },
                    "schedules":
                    [
                        {
                            "startTimeOfDay":
                            {
                                "hour": 10,
                                "minute": 0,
                                "second": 0
                            },
                            "daysOfWeek":
                            [
                                "MONDAY",
                                "WEDNESDAY"
                            ],
                            "timeZone": "America/New_York",
                            "startDate":
                            {
                                "year": 2016,
                                "month": 12,
                                "day": 1
                            }
                        }
                    ],
                    "retryConfig":
                    {
                        "maxAttempts": 2,
                        "minutesBetweenAttempts": 5,
                        "retryResults":
                        [
                            "BUSY",
                            "NO_ANS"
                        ],
                        "retryPhoneTypes":
                        [
                            "MOBILE_PHONE",
                            "WORK_PHONE"
                        ]
                    },
                    "recipients":
                    [
                        {
                            "phoneNumber": "12135551100",
                            "attributes":
                            {
                                "age": "30",
                                "position": "Manager"
                            }
                        },
                        {
                            "phoneNumber": "12135771188",
                            "attributes":
                            {
                                "external_system_id": "34347770001",
                                "call_label": "friends"
                            }
                        },
                        {
                            "contactId": 46000044001
                        }
                    ],
                    "dialPlanXml": "<dialplan name=\"Root\"> <!-- answering machine detection --> <amd> <!-- if call is answered by human go to live menu --> <live> <goto name=\"goto_Live\">Live</goto> </live> <machine> <goto name=\"goto_Machine\">Machine</goto> </machine> </amd> <menu maxDigits=\"1\" timeout=\"3500\" name=\"Live\"> <play type=\"tts\" voice=\"female1\" name=\"play_Live\"> Hello ${contact.firstName}, we are organizing a charity weekend in November. Do not miss to visit it. Press \"1\" to follow the instructions how to order the tickets, press \"2\" if you are willing to become a volunteer at event. </play> <keypress pressed=\"1\" name=\"kp_order_tickets\"> <!-- store recipients answer and go to another menu to make a purchase --> <stash varname=\"order\" name=\"create_an_order\">Yes</stash> <goto>order_tickets</goto> </keypress> <keypress pressed=\"2\" name=\"kp_become_volonteer\"> <!-- store recipients answer --> <stash varname=\"volonteer\" name=\"become_volonteer\">Yes</stash> <play type=\"tts\" voice=\"female1\" name=\"play_Goodbye_1\">Thanks for the response. We will call you later today.</play> <goto>Hangup</goto> </keypress> <!-- if pressed key is not specified in menu replay Live menu --> <keypress pressed=\"default\" name=\"incorrect_Selection\"> <play type=\"tts\" voice=\"female1\" name=\"play_Inorrect_Selection\">That is not a valid selection. Please try again.</play> <goto name=\"replay_Live\">Live</goto> </keypress> </menu> <menu maxDigits=\"1\" timeout=\"3500\" name=\"order_tickets\"> <play type=\"tts\" voice=\"female1\" name=\"play_order_tickets\"> You will be transferred to Sales representative in a moment. Please wait. </play> <transfer callerid=\"${call.callerid}\" musiconhold=\"blues\" mode=\"ringall\"> 15551234567 </transfer> </menu> <play type=\"tts\" voice=\"female1\" name=\"Goodbye\"> Thank you for taking our survey </play> <goto name=\"Goodbye_Hangup\">Hangup</goto> <play type=\"tts\" voice=\"female1\" name=\"Machine\"> Hello ${contact.firstName} ${contact.lastName}. We are organizing a charity weekend in November. If you would like to participate, please call 8 5 5, 5 5 5, 5 5 5 5. Thank you. </play> <hangup name=\"Hangup\"/> </dialplan>"
                 }';
        $request->getOperationConfig()->setBodyParameter($body);
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}

ApiClientSample::main();
[-php] [[/code-container]]

How to Add Recipients / Contacts to an Existing Broadcast

You can add only phone numbers to a broadcast (no contact names required), or you can add existing contacts. CallFire creates contacts on the fly from the recipients' numbers. Check contacts guide for more information on how to manage CallFire Contacts.

Users have two options to add contacts to an existing broadcast:

The main difference to both approaches is the first one accepts an existing contact list id and performs validation of recipients' numbers, whereas the second one doesn't perform a contact validation, so you may have duplicates in your broadcast.

[[code-container]] [+curl] request:

#!/usr/bin/env bash

curl -u username:password -H "Content-Type:application/json" -X POST -d '
    {
        "name":"contact batch for call broadcast",
        "recipients":
        [
            {
                "phoneNumber":"12135551122"
            },
            {
                "phoneNumber":"12135553434"
            },
            {
                "phoneNumber":"12135558090",
                "attributes":
                {
                    "custom_external_id": 30005044,
                    "custom_property_1": "value1"
                }
            }
        ],
        # or you can add contacts from particular contact list
        # contactListId: 70055003,
        "scrubDuplicates": true
    }' "https://api.callfire.com/v2/calls/broadcasts/11646003/batches"
response:
{
  "id": 13
}
[-curl] [+java]
import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.callstexts.model.CallRecipient;
import com.callfire.api.client.api.campaigns.model.request.AddBatchRequest;
import com.callfire.api.client.api.common.model.ResourceId;

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient callfireClient = new CallfireClient("api_login", "api_password");
        CallRecipient recipient1 = new CallRecipient();
        recipient1.setPhoneNumber("12135551122");
        CallRecipient recipient2 = new CallRecipient();
        recipient2.setPhoneNumber("12135553434");
        CallRecipient recipient3 = new CallRecipient();
        recipient3.setPhoneNumber("12135558090");
        Map<String,String> attrs = new HashMap<>();
        attrs.put("custom_external_id", "30005044");
        attrs.put("custom_property_1", "value1");
        recipient3.setAttributes(attrs);

        AddBatchRequest request = AddBatchRequest.create()
            .campaignId(11646003L)
            .name("contact batch for call broadcast")
            .scrubDuplicates(true)
            .recipients(Arrays.asList(recipient1, recipient2, recipient3))
            //or you can add contacts from particular contact list
            //.contactListId(70055003L)
            .build();
        ResourceId resourceId = callfireClient.callBroadcastsApi().addBatch(request);
    }
}
[-java] [+csharp]
using System.Collections.Generic;
using CallfireApiClient;
using CallfireApiClient.Api.CallsTexts.Model;
using CallfireApiClient.Api.Campaigns.Model;
using CallfireApiClient.Api.Campaigns.Model.Request;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        var request1 = new AddBatchRequest
        {
            CampaignId = 11646003,
            Name = "contact batch for call broadcast",
            Recipients = new List<Recipient>
            {
                new CallRecipient {PhoneNumber = "12135551122"},
                new CallRecipient {PhoneNumber = "12135553434"},
                new CallRecipient
                {
                    PhoneNumber = "12135558090",
                    Attributes = new Dictionary<string, string>
                    {
                        {"custom_external_id", "30005044"},
                        {"custom_property_1", "value1"}
                    }
                }
            },
            //or you can add contacts from particular contact list
            //ContactListId = 70055003
            ScrubDuplicates = true
        };
        var resourceId = client.TextBroadcastsApi.AddBatch(request1);
    }
}
[-csharp] [+js]
'strict'

const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');

client.ready(() => {
    client.calls.addCallBroadcastBatch({
      id: 11646003,
      body: {
        name: 'contact batch for call broadcast',
        recipients: [
          {phoneNumber: '12135551122'},
          {phoneNumber: '12135553434'},
          {
            phoneNumber: '12135558090',
            attributes: {
              custom_external_id: 30005044,
              custom_property_1: 'value1'
            }
          },
        ],
        // or you can add contacts from particular contact list
        // contactListId: 70055003,
        scrubDuplicates: true
      }
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);
[-js] [+python]
from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.calls.addCallBroadcastBatch(
    id=11646003,
    body={
        'name': 'contact batch for call broadcast',
        'recipients': [
            {'phoneNumber': '12135551122'},
            {'phoneNumber': '12135553434'},
            {
                'phoneNumber': '12135558090',
                'attributes': {
                    'custom_external_id': 30005044,
                    'custom_property_1': 'value1'
                }
            }
        ],
        # or you can add contacts from particular contact list
        # contactListId: 70055003,
        'scrubDuplicates': True
    }
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)
[-python] [+php]
<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->addCallBroadcastBatch();
        $request->getOperationConfig()->setPathParameters(array("id" => 11646003));
        $body = '{
                    "name":"contact batch for call broadcast",
                    "recipients":
                    [
                        {
                            "phoneNumber":"12135551122"
                        },
                        {
                            "phoneNumber":"12135553434"
                        },
                        {
                            "phoneNumber":"12135558090",
                            "attributes":
                            {
                                "custom_external_id": 30005044,
                                "custom_property_1": "value1"
                            }
                        }
                    ],
                    # or you can add contacts from particular contact list
                    # contactListId: 70055003,
                    "scrubDuplicates": true
                 }';
        $request->getOperationConfig()->setBodyParameter($body);
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}
[-php] [[/code-container]]

Another method to add recipients to broadcast:

[[code-container]] [+curl] request:

#!/usr/bin/env bash

curl -u username:password -H "Content-Type:application/json" -X POST -d '
    [
        {
            "phoneNumber":"12135551122"
        },
        {
            "contactId":122460000043
        },
        {
            "phoneNumber":"12135558090",
            "attributes":
            {
                "custom_external_id": 30005044,
                "custom_property_1": "value1"
            }
        }
    ]' "https://api.callfire.com/v2/calls/broadcasts/11646003/recipients"
response:
{
  "items": [
    {
      "id": 13410,
      "fromNumber": "12135551189",
      "toNumber": "12135551100",
      "state": "READY",
      "campaignId": 14,
      "batchId": 12,
      "contact": {
        "id": 4096,
        "homePhone": "12135551100"
      },
      "inbound": false,
      "created": 1443383295000,
      "modified": 1443383295000,
      "agentCall": false
    },
    {
      "id": 13411,
      "fromNumber": "12135551189",
      "toNumber": "12135551101",
      "state": "READY",
      "campaignId": 14,
      "batchId": 12,
      "contact": {
        "id": 4097,
        "homePhone": "12135551101"
      },
      "inbound": false,
      "created": 1443383295000,
      "modified": 1443383295000,
      "agentCall": false
    }
  ]
}
[-curl] [+java]
import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.callstexts.model.Call;
import com.callfire.api.client.api.campaigns.model.Recipient;

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 callfireClient = new CallfireClient("api_login", "api_password");
        Recipient recipient1 = new Recipient();
        recipient1.setPhoneNumber("12135551122");
        Recipient recipient2 = new Recipient();
        recipient2.setContactId(122460000043L);
        Recipient recipient3 = new Recipient();
        recipient3.setPhoneNumber("12135558090");
        Map<String,String> attrs = new HashMap<>();
        attrs.put("custom_external_id", "30005044");
        attrs.put("custom_property_1", "value1");
        recipient3.setAttributes(attrs);
        List<Recipient> recipients = Arrays.asList(recipient1, recipient2, recipient3);
        List<Call> calls = callfireClient.callBroadcastsApi().addRecipients(11646003L, recipients);
    }
}
[-java] [+csharp]
using System.Collections.Generic;
using CallfireApiClient;
using CallfireApiClient.Api.Campaigns.Model;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        var calls = client.CallBroadcastsApi.AddRecipients(11646003, new List<Recipient>
        {
            new Recipient {PhoneNumber = "12135551122"},
            new Recipient {ContactId = 122460000043},
            new Recipient {PhoneNumber = "12135558090",
                           Attributes = new Dictionary<string, string>
                          {
                              {"custom_external_id", "30005044"},
                              {"custom_property_1", "value1"}
                          }
            }
        });
    }
}
[-csharp] [+js]
'strict'

const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');

client.ready(() => {
    client.calls.addCallBroadcastRecipients({
      id: 11646003,
      body: [
        {phoneNumber: '12135551122'},
        // use an existing contact in CallFire account
        {contactId: 122460000043},
        {
          phoneNumber: '12135558090',
          attributes: {
            custom_external_id: 30005044,
            custom_property_1: 'value1'
          }
        },
      ]
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);
[-js] [+python]
from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.calls.addCallBroadcastRecipients(
    id=11646003,
    body=[
        {'phoneNumber': '12135551122'},
        # use an existing contact in CallFire account
        {'contactId': 122460000043},
        {
            'phoneNumber': '12135558090',
            'attributes': {
                'custom_external_id': 30005044,
                'custom_property_1': 'value1'
            }
        }
    ]
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)
[-python] [+php]
<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->addCallBroadcastRecipients();
        $request->getOperationConfig()->setPathParameters(array("id" => 11646003));
        $body = '[
                    {
                        "phoneNumber":"12135551122"
                    },
                    {
                        "contactId":122460000043
                    },
                    {
                        "phoneNumber":"12135558090",
                        "attributes":
                        {
                            "custom_external_id": 30005044,
                            "custom_property_1": "value1"
                        }
                    }
                 ]';
        $request->getOperationConfig()->setBodyParameter($body);
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}

ApiClientSample::main();
[-php] [[/code-container]]

See Call Broadcast API for detailed information about accepted parameters and responses. See a similar method in Text Broadcast API which works the same way as above, but for Text Broadcasts.

Start / Stop / Schedule a Broadcast

CallFire provides the ability to start and stop broadcasts at any time. This applies to all types of broadcasts: Voice, IVR, and Text. Also, you can schedule a broadcast to start in the future. The following examples show how to start a Call Broadcast, and the same operations are available for IVR and Text broadcasts.

[[code-container]] [+curl] request:

#!/usr/bin/env bash

curl -u username:password -H "Content-Type:application/json" -X POST "https://api.callfire.com/v2/calls/broadcasts/11646003/start"
response:
200 OK - No Response
[-curl] [+java]
import com.callfire.api.client.CallfireClient;

class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient client = new CallfireClient("api_login", "api_password");
        client.callBroadcastsApi().start(11646003L);
    }
}
[-java] [+csharp]
using CallfireApiClient;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        client.CallBroadcastsApi.Start(11646003);
    }
}
[-csharp] [+js]
'strict'

const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');

client.ready(() => {
    client.calls.startVoiceBroadcast({id: 11646003})
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);
[-js] [+python]
from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
client.calls.startVoiceBroadcast(id=11646003).result()
[-python] [+php]
<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->startVoiceBroadcast();
        $request->getOperationConfig()->setPathParameters(array("id" => 11646003));
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}

ApiClientSample::main();
[-php] [[/code-container]]

The same API method is available to start Text Broadcasts.

To schedule a broadcast, invoke Update API on a given broadcast with a schedule object set. Broadcasts support multiple schedule objects per single instance, so you can make a long-term schedule to start-stop your campaigns. Each schedule can be turned on and off. The following examples show how to add schedules to a broadcast so that it will start twice in December: one the one hand, between 10:00 and 18:00 between the 1st through 10th, and on the other, between 10:00 and 18:00 on weekends between the 20th and 30th.

[[code-container]] [+curl] request:

#!/usr/bin/env bash

curl -u username:password -H "Content-Type:application/json" -X PUT -d '
{
  "schedules": [
    {
      "startTimeOfDay": {
        "hour": 10,
        "minute": 0,
        "second": 0
      },
      "stopTimeOfDay": {
        "hour": 18,
        "minute": 0,
        "second": 0
      },
      "daysOfWeek": [
        "SATURDAY",
        "SUNDAY"
      ],
      "timeZone": "America/New_York",
      "startDate": {
        "year": 2016,
        "month": 12,
        "day": 1
      },
      "stopDate": {
        "year": 2016,
        "month": 12,
        "day": 10
      }
    },
    {
      "startTimeOfDay": {
        "hour": 10,
        "minute": 0,
        "second": 0
      },
      "stopTimeOfDay": {
        "hour": 18,
        "minute": 0,
        "second": 0
      },
      "daysOfWeek": [
        "SATURDAY",
        "SUNDAY"
      ],
      "timeZone": "America/New_York",
      "startDate": {
        "year": 2016,
        "month": 12,
        "day": 20
      },
      "stopDate": {
        "year": 2016,
        "month": 12,
        "day": 30
      }
    }
  ]
}' "https://api.callfire.com/v2/calls/broadcasts/11646003"
response:
200 OK - No Response
[-curl] [+java]
import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.campaigns.model.CallBroadcast;
import com.callfire.api.client.api.campaigns.model.DayOfWeek;
import com.callfire.api.client.api.campaigns.model.LocalDate;
import com.callfire.api.client.api.campaigns.model.LocalTime;
import com.callfire.api.client.api.campaigns.model.Schedule;
import com.callfire.api.client.api.common.model.LocalDate;
import com.callfire.api.client.api.common.model.LocalTime;

import java.time.DayOfWeek;
import java.util.Arrays;
import java.util.HashSet;

/**
 * An Example how update broadcast and set multiple schedule to
 * start-stop campaign twice in December
 */
class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient client = new CallfireClient("api_login", "api_password");

        CallBroadcast broadcast = new CallBroadcast();
        // set id of an existing broadcast, you can use find() method to search
        //  for particular broadcast id
        broadcast.setId(11646003L);
        // schedule a campaign to run on Saturday and Sunday between 2016-12-01 10:00:00
        //  and 2016-12-10 18:00:00
        Schedule schedule1 = new Schedule();
        schedule1.setStartDate(new LocalDate(2016, 12, 1));
        schedule1.setStartTimeOfDay(new LocalTime(10, 0, 0));
        schedule1.setStopDate(new LocalDate(2016, 12, 10));
        schedule1.setStopTimeOfDay(new LocalTime(18, 0, 0));
        schedule1.setDaysOfWeek(new HashSet<>(Arrays.asList(DayOfWeek.SATURDAY, DayOfWeek.SUNDAY)));
        // set optional time zone, if leave empty account's timezone will be used
        schedule1.setTimeZone("America/New_York");
        // add another schedule for campaign to start on Saturday and Sunday between 2016-12-20 10:00:00
        //  and 2016-12-30 18:00:00
        Schedule schedule2 = new Schedule();
        schedule2.setStartDate(new LocalDate(2016, 12, 20));
        schedule2.setStartTimeOfDay(new LocalTime(10, 0, 0));
        schedule2.setStopDate(new LocalDate(2016, 12, 30));
        schedule2.setStopTimeOfDay(new LocalTime(18, 0, 0));
        schedule2.setDaysOfWeek(new HashSet<>(Arrays.asList(DayOfWeek.SATURDAY, DayOfWeek.SUNDAY)));
        broadcast.setSchedules(Arrays.asList(schedule1, schedule2));

        // update broadcast
        client.callBroadcastsApi().update(broadcast);
    }
}
[-java] [+csharp]
using System.Collections.Generic;
using CallfireApiClient;
using CallfireApiClient.Api.Campaigns.Model;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        var broadcast = new CallBroadcast
        {
            Id = 11646003,
            Schedules = new List<Schedule>
            {
                // schedule a campaign to run on Saturday and Sunday between 2016-12-01 10:00:00
                //  and 2016-12-10 18:00:00
                new Schedule
                {
                    StartDate = new LocalDate {Year = 2016, Month = 12, Day = 1},
                    StartTimeOfDay = new LocalTime {Hour = 10, Minute = 0, Second = 0},
                    StopDate = new LocalDate {Year = 2016, Month = 12, Day = 10},
                    StopTimeOfDay = new LocalTime {Hour = 18, Minute = 0, Second = 0},
                    // set weekly schedule
                    DaysOfWeek = new HashSet<DayOfWeek> {DayOfWeek.SATURDAY, DayOfWeek.SUNDAY},
                    // set optional time zone, if leave empty account's timezone will be used
                    TimeZone = "America/New_York"
                },
                // add another schedule for campaign to start on Saturday and Sunday between 2016-12-20 10:00:00
                //  and 2016-12-30 18:00:00
                new Schedule
                {
                    StartDate = new LocalDate {Year = 2016, Month = 12, Day = 20},
                    StartTimeOfDay = new LocalTime {Hour = 10, Minute = 0, Second = 0},
                    StopDate = new LocalDate {Year = 2016, Month = 12, Day = 30},
                    StopTimeOfDay = new LocalTime {Hour = 18, Minute = 0, Second = 0},
                    // set weekly schedule
                    DaysOfWeek = new HashSet<DayOfWeek> {DayOfWeek.SATURDAY, DayOfWeek.SUNDAY}
                }
            }
        };

        // update broadcast with new schedules
        client.CallBroadcastsApi.Update(broadcast);
    }
}
[-csharp] [+js]
'strict'

const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');

client.ready(() => {
    client.calls.updateCallBroadcast({
      id: 11646003,
      body: {
        schedules: [
          {
            startTimeOfDay: {
              hour: 10,
              minute: 0,
              second: 0
            },
            stopTimeOfDay: {
              hour: 18,
              minute: 0,
              second: 0
            },
            daysOfWeek: [
              'SATURDAY',
              'SUNDAY'
            ],
            timeZone: 'America/New_York',
            startDate: {
              year: 2016,
              month: 12,
              day: 1
            },
            stopDate: {
              year: 2016,
              month: 12,
              day: 10
            }
          },
          {
            startTimeOfDay: {
              hour: 10,
              minute: 0,
              second: 0
            },
            stopTimeOfDay: {
              hour: 18,
              minute: 0,
              second: 0
            },
            daysOfWeek: [
              'SATURDAY',
              'SUNDAY'
            ],
            timeZone: 'America/New_York',
            startDate: {
              year: 2016,
              month: 12,
              day: 20
            },
            stopDate: {
              year: 2016,
              month: 12,
              day: 30
            }
          },
        ]
      }
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);
[-js] [+python]
from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
client.calls.updateCallBroadcast(
    id=11646003,
    body={
        'schedules': [
            {
                'startTimeOfDay': {
                    'hour': 10,
                    'minute': 0,
                    'second': 0
                },
                'stopTimeOfDay': {
                    'hour': 18,
                    'minute': 0,
                    'second': 0
                },
                'daysOfWeek': [
                    'SATURDAY',
                    'SUNDAY'
                ],
                'timeZone': 'America/New_York',
                'startDate': {
                    'year': 2016,
                    'month': 12,
                    'day': 1
                },
                'stopDate': {
                    'year': 2016,
                    'month': 12,
                    'day': 10
                }
            },
            {
                'startTimeOfDay': {
                    'hour': 10,
                    'minute': 0,
                    'second': 0
                },
                'stopTimeOfDay': {
                    'hour': 18,
                    'minute': 0,
                    'second': 0
                },
                'daysOfWeek': [
                    'SATURDAY',
                    'SUNDAY'
                ],
                'timeZone': 'America/New_York',
                'startDate': {
                    'year': 2016,
                    'month': 12,
                    'day': 20
                },
                'stopDate': {
                    'year': 2016,
                    'month': 12,
                    'day': 30
                }
            },
        ]
    }
).result()
[-python] [+php]
<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->updateCallBroadcast();
        $request->getOperationConfig()->setPathParameters(array("id" => 11646003));
        $body = '{
                    "schedules":
                    [
                        {
                            "startTimeOfDay":
                            {
                                "hour": 10,
                                "minute": 0,
                                "second": 0
                            },
                            "stopTimeOfDay":
                            {
                                "hour": 18,
                                "minute": 0,
                                "second": 0
                            },
                            "daysOfWeek":
                            [
                                "SATURDAY",
                                "SUNDAY"
                            ],
                            "timeZone": "America/New_York",
                            "startDate":
                            {
                                "year": 2016,
                                "month": 12,
                                "day": 1
                            },
                            "stopDate":
                            {
                                "year": 2016,
                                "month": 12,
                                "day": 10
                            }
                        },
                        {
                            "startTimeOfDay":
                            {
                                "hour": 10,
                                "minute": 0,
                                "second": 0
                            },
                            "stopTimeOfDay":
                            {
                                "hour": 18,
                                "minute": 0,
                                "second": 0
                            },
                            "daysOfWeek":
                            [
                                "SATURDAY",
                                "SUNDAY"
                            ],
                            "timeZone": "America/New_York",
                            "startDate":
                            {
                                "year": 2016,
                                "month": 12,
                                "day": 20
                            },
                            "stopDate":
                            {
                                "year": 2016,
                                "month": 12,
                                "day": 30
                            }
                        }
                    ]
                }';
        $request->getOperationConfig()->setBodyParameter($body);
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}

ApiClientSample::main();
[-php] [[/code-container]]

See API method reference for more information about request type, arguments, and API responses.

How to Find Outbound Calls or Texts, and How to Search for Inbound Texts

Our Calls and Texts API provides you several ways to query outbound and inbound actions. You can use Calls Find or Texts Find methods to search outbound/inbound actions. All find() methods support pagination and limiting returned data. More information can be found on this page

The next examples show how to find all text replies sent in response to a text 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/texts?inbound=true&campaignId=1003002&limit=10"
response:
{
  "items": [
    {
      "id": 13405,
      "fromNumber": "12135551100",
      "toNumber": "12135551123",
      "state": "READY",
      "campaignId": 13,
      "batchId": 11,
      "contact": {
        "id": 4101,
        "homePhone": "12135551123"
      },
      "inbound": true,
      "created": 1443382358000,
      "modified": 1443382358000,
      "message": "a new test message"
    },
    {
      "id": 13404,
      "fromNumber": "12135551100",
      "toNumber": "12135551122",
      "state": "READY",
      "campaignId": 13,
      "batchId": 10,
      "contact": {
        "id": 4099,
        "homePhone": "12135551122"
      },
      "inbound": true,
      "created": 1443382248000,
      "modified": 1443382248000,
      "message": "a new test message"
    }
  ],
  "limit": 2,
  "offset": 0,
  "totalCount": 4107
}
[-curl] [+java]
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;

class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient client = new CallfireClient("api_login", "api_password");
        FindTextsRequest request = FindTextsRequest.create()
            // find messages sent from particular campaign or replies.
            .campaignId(1003002L)
            // find only inbound messages
            .inbound(true)
            .limit(10L)
            .build();
        Page<Text> texts = client.textsApi().find(request);
    }
}
[-java] [+csharp]
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 replies for a particular Text Broadcast
            CampaignId = 1003003,
            Inbound = true,
            Limit = 10
        };
        Page<Text> texts = client.TextsApi.Find(request);
    }
}
[-csharp] [+js]
'strict'

const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');

client.ready(() => {
    client.texts.findTexts({
      inbound: true,
      campaignId: 1003002,
      limit: 10
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);
[-js] [+python]
from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.texts.findTexts(
    inbound=True,
    campaignId=1003002,
    limit=10
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)
[-python] [+php]
<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->findTexts();
        $request->getOperationConfig()->setQueryParameters(array("campaignId" => 1003002,
                                                                 "inbound" => true,
                                                                 "limit" => 10));
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}

ApiClientSample::main();
[-php] [[/code-container]]

These examples show how to get all the calls from a particular broadcast. The similar method is available for Text Broadcasts.

[[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/calls?batchId=5500030002&offset=0&limit=10&fields=items(fromNumber,toNumber,state,modified)"
response:
{
  "items": [
    {
      "id": 13408,
      "fromNumber": "12135551189",
      "toNumber": "12135551101",
      "state": "READY",
      "campaignId": 14,
      "batchId": 13,
      "contact": {
        "id": 4097,
        "homePhone": "12135551101"
      },
      "inbound": false,
      "created": 1443383158000,
      "modified": 1443383158000,
      "agentCall": false
    },
    {
      "id": 13407,
      "fromNumber": "12135551189",
      "toNumber": "12135551100",
      "state": "READY",
      "campaignId": 14,
      "batchId": 13,
      "contact": {
        "id": 4096,
        "homePhone": "12135551100"
      },
      "inbound": false,
      "created": 1443383158000,
      "modified": 1443383158000,
      "agentCall": false
    },
    {
      "id": 13406,
      "fromNumber": "12135551189",
      "toNumber": "12135551133",
      "state": "READY",
      "campaignId": 14,
      "batchId": 12,
      "contact": {
        "id": 4102,
        "homePhone": "2135551133"
      },
      "inbound": false,
      "created": 1443382636000,
      "modified": 1443382636000,
      "agentCall": false
    }
  ],
  "limit": 100,
  "offset": 0,
  "totalCount": 3
}
[-curl] [+java]
import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.callstexts.model.Call;
import com.callfire.api.client.api.campaigns.model.request.FindBroadcastCallsRequest;
import com.callfire.api.client.api.common.model.Page;

class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient client = new CallfireClient("api_login", "api_password");
        FindBroadcastCallsRequest request = FindBroadcastCallsRequest.create()
            .id(11646003L)
            .batchId(5500030002L)
            .offset(0L)
            .limit(10L)
            .fields("items(fromNumber,toNumber,state,modified)")
        .build();
        Page<Call> calls = client.callBroadcastsApi().findCalls(request);
    }
}
[-java] [+csharp]
using CallfireApiClient;
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 GetBroadcastCallsTextsRequest
        {
            Id = 11646003,
            BatchId = 5500030002,
            Offset = 0,
            Limit = 10,
            Fields = "items(fromNumber,toNumber,state,modified)"
        };
        var calls = client.CallBroadcastsApi.GetCalls(request);
    }
}
[-csharp] [+js]
'strict'

const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');

client.ready(() => {
    client.calls.getCallBroadcastCalls({
      id: 11646003,
      // get calls assigned to particular contact batch
      batchId: 5500030002,
      // search offset
      offset: 0,
      // return 10 items per request
      limit: 10,
      // return only specific fields
      fields: 'items(fromNumber,toNumber,state,modified)'
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);
[-js] [+python]
from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.calls.getCallBroadcastCalls(
    id=11646003,
    # get calls assigned to particular contact batch
    batchId=5500030002,
    # search offset
    offset=0,
    # return 10 items per request
    limit=10,
    # return only specific fields
    fields='items(fromNumber,toNumber,state,modified)'
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)
[-python] [+php]
<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->getCallBroadcastCalls();
        $request->getOperationConfig()->setPathParameters(array("id" => 11646003));
        $request->getOperationConfig()->setQueryParameters(array("batchId" => 5500030002,
                                                                 "offset" => 0,
                                                                 "limit" => 10,
                                                                 "fields" => "items(fromNumber,toNumber,state,modified)"));
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}
[-php] [[/code-container]]

How to Get Call/Text Statistics from a Broadcast

You can fetch a broadcast's statistics like the number of total actions (Call/Text) made by the platform, the number of remaining actions, the number of errors, the number of calls by disposition, the calls duration, billed amount, etc. The following samples show how to fetch statistics for a 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"
response:
{
  "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
}
[-curl] [+java]
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);
    }
}
[-java] [+csharp]
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);
    }
}
[-csharp] [+js]
'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);
  }
);
[-js] [+python]
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)
[-python] [+php]
<?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();
[-php] [[/code-container]]

Check API method reference for detailed information about request type, parameters, responses.

How CallFire Platform Notifies Its Users

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 webhooks guide for more information about CallFire Webhooks.

The following examples show how start receiving notifications for every finished outbound call:

[[code-container]] [+curl] request:

#!/usr/bin/env bash

curl -u username:password -H "Content-Type:application/json" -X POST "https://api.callfire.com/v2/webhooks" -d '
    {
        "name":"Call finished webhook",
        "resource":"OutboundCall",
        "events":["Finished"], 
        "callback":"http://callback-service.com/webhook"
    }'
response:
{
  "id": 4321
}
[-curl] [+java]
import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.common.model.ResourceId;
import com.callfire.api.client.api.webhooks.model.ResourceType;
import com.callfire.api.client.api.webhooks.model.Webhook;

class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient client = new CallfireClient("api_login", "api_password");
        Webhook webhook = new Webhook();
        webhook.setName("Call finished webhook");
        webhook.setResource(ResourceType.OUTBOUND_CALL);
        webhook.getEvents().add(ResourceType.ResourceEvent.FINISHED);
        // CallFire will send a POST request to specified endpoint
        webhook.setCallback("http://callback-service.com/webhook");
        ResourceId id = client.webhooksApi().create(webhook);
    }
}
[-java] [+csharp]
using System.Collections.Generic;
using CallfireApiClient;
using CallfireApiClient.Api.Common.Model;
using CallfireApiClient.Api.Webhooks.Model;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        var webhook = new Webhook
        {
            Name = "Call finished webhook",
            Resource = ResourceType.OUTBOUND_CALL,
            Events = new HashSet<ResourceEvent> {ResourceEvent.FINISHED},
            Callback = "http://callback-service.com/webhook"
        };
        ResourceId resource = client.WebhooksApi.Create(webhook);
    }
}
[-csharp] [+js]
'strict'

const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');

client.ready(() => {
    client.webhooks.createWebhook({
      body: {
        name: 'Call finished webhook',
        resource: 'OutboundCall',
        events: ['Finished'],
        callback: 'http://callback-service.com/webhook'
      }
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);
[-js] [+python]
from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.webhooks.createWebhook(
    body={
        'name': 'Call finished webhook',
        'resource': 'OutboundCall',
        'events': ['Finished'],
        'callback': 'http://callback-service.com/webhook'
    }
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)
[-python] [+php]
<?php

class ApiClientSample {

    public static function main() {
        $client =\CallFire\Api\DocumentedClient::createClient ("login", "password");
        $request = $client -> createWebhook();
        $body = '{
                    "name":"Call finished webhook",
                    "resource":"OutboundCall",
                    "events":["Finished"],
                    "callback":"http://callback-service.com/webhook"
                 }';
        $request->getOperationConfig()->setBodyParameter($body);
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}

ApiClientSample::main();
[-php] [[/code-container]]

How to Get a User's Responses Recorded via IVR

To get data stored using the IVR, you can simply query calls and find it 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?id=11646003&id=12646003&id=13776003&campaignId=449060003&batchId=447060003&fromNumber=12135551126&toNumber=12136666123&label=my label&states=READY,FINISHED,INVALID&results=LA&inboubd=true&intervalBegin=1473781817000&intervalEnd=1473781817000&offset=0&limit=10&fields=items(id,fromNumber,toNumber,modified,finalCallResult)"
response:
{
  "items": [
    {
      "id": 13395,
      "fromNumber": "12135551189",
      "toNumber": "12135551101",
      "state": "FINISHED",
      "campaignId": 10,
      "batchId": 6,
      "contact": {
        "id": 4097,
        "homePhone": "12135551101"
      },
      "labels": [
        "survey 1"
      ],
      "attributes": {
          "external_user_id":"45450007002",
          "external_route_id":"77770007002"
      },
      "inbound": false,
      "created": 1443373386000,
      "modified": 1443373412000,
      "finalCallResult": "LA",
      "records": [
        {
          "id": 10306,
          "billedAmount": 1.1667,
          "finishTime": 1443373425000,
          "callResult": "LA",
          "questionResponses":[  
           {  
             "question":"Do you have a dog",
             "response":"Yes"
           },
           {  
              "question":"What's your favorite movie",
              "response":"StarWars"
           }
          ]
        }
      ],
      "agentCall": false
    },
    {
      "id": 13394,
      "fromNumber": "12135551189",
      "toNumber": "12135551100",
      "state": "FINISHED",
      "campaignId": 10,
      "batchId": 6,
      "contact": {
        "id": 4096,
        "homePhone": "12135551100"
      },
      "inbound": false,
      "created": 1443373382000,
      "modified": 1443373412000,
      "finalCallResult": "CARRIER_ERROR",
      "records": [
        {
          "id": 10305,
          "billedAmount": 0,
          "finishTime": 1443373408000,
          "callResult": "CARRIER_ERROR"
        }
      ],
      "agentCall": false
    }
  ],
  "limit": 2,
  "offset": 0,
  "totalCount": 7160
}
[-curl] [+java]
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 static com.callfire.api.client.api.callstexts.model.Action.State;
import static com.callfire.api.client.api.callstexts.model.Call.CallResult;

import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Arrays;

class ApiClientSample {
    public static void main(String[] args) throws ParseException {
        CallfireClient client = new CallfireClient("api_login", "api_password");
        // find all calls made through particular campaign, with exact toNumber and fromNumber
        FindCallsRequest request = FindCallsRequest.create()
            .id(Arrays.asList(11646003L, 12646003L, 13776003L))
            .campaignId(449060003L)
            .batchId(447060003L)
            .fromNumber("12135551126")
            .toNumber("12136666123")
            .label("my label")
            .states(Arrays.asList(State.READY, State.FINISHED, State.INVALID))
            .results(Arrays.asList(CallResult.LA))
            .inbound(false)
            .intervalBegin(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").parse("2016-09-13 15:50:17"))
            .intervalEnd(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").parse("2016-09-13 15:50:17"))
            .offset(0L)
            .limit(10L)
            .fields("items(id,fromNumber,toNumber,modified,finalCallResult)")
            .build();
        Page<Call> calls = client.callsApi().find(request);
        // check Call.records.questionResponses list for stored data
    }
}
[-java] [+csharp]
using System;
using System.Collections.Generic;
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
        {
            Id = new List<long> { 11646003, 12646003, 13776003 },
            CampaignId = 449060003,
            BatchId = 447060003,
            FromNumber = "12135551126",
            ToNumber  = "12136666123",
            Label = "my label",
            States = new List<StateType> { StateType.FINISHED, StateType.READY, StateType.INVALID },
            Results = new List<Call.CallResult> { Call.CallResult.LA },
            Inbound = true,
            IntervalBegin = new DateTime(2016, 9, 13, 15, 50, 17),
            IntervalEnd = new DateTime(2016, 9, 13, 15, 50, 17),
            Offset = 0,
            Limit = 10,
            Fields = "items(id,fromNumber,toNumber,modified,finalCallResult)"
        };
        Page<Call> calls = client.CallsApi.Find(request);
        // check Call.records.questionResponses for stored data
    }
}
[-csharp] [+js]
'strict'

const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');

client.ready(() => {
    client.calls.findCalls({
      // filter by call ids
      id: [
        11646003,
        12646003,
        13776003
      ],
      // specify  id of a campaign, queries for calls inside a particular campaign.
      // do not set to list calls of all campaigns or 0 for a default campaign
      campaignId: 449060003,
      // queries for calls which are used in the particular contact batch
      batchId: 447060003,
      // filter by fromNumber
      fromNumber: '12135551126',
      // filter by toNumber
      toNumber: '12136666123',
      // filter by label
      label: 'my label',
      // filter by call state
      states: 'READY,FINISHED,INVALID',
      // filter by call result
      results: 'SENT',
      // filter only inbound actions
      inbound: false,
      // filter by time interval
      intervalBegin: 1473781817000,
      // filter by time interval
      intervalEnd: 1473781817000,
      // search offset
      offset: 0,
      // return 10 items per request
      limit: 10,
      // return only specific fields
      fields: 'items(id,fromNumber,toNumber,modified,finalCallResult)'
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);
[-js] [+python]
from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.calls.findCalls(
    # filter by call ids
    id=[
        11646003,
        12646003,
        13776003
    ],
    # specify  id of a campaign, queries for calls inside a particular campaign.
    # do not set to list calls of all campaigns or 0 for a default campaign
    campaignId=449060003,
    # queries for calls which are used in the particular contact batch
    batchId=447060003,
    # filter by fromNumber
    fromNumber='12135551126',
    # filter by toNumber
    toNumber='12136666123',
    # filter by label
    label='my label',
    # filter by call state
    states='READY,FINISHED,INVALID',
    # filter by call result
    results='LA',
    # filter only inbound actions
    inbound=False,
    # filter by time interval
    intervalBegin=1473781817000,
    # filter by time interval
    intervalEnd=1473781817000,
    # search offset
    offset=0,
    # return 10 items per request
    limit=10,
    # return only specific fields
    fields='items(id,fromNumber,toNumber,modified,finalCallResult)'
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)
[-python] [+php]
<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->findCalls();
        $request->getOperationConfig()->setQueryParameters(array("id" => 11646003,
                                                                 "id" => 12646003,
                                                                 "id" => 13776003,
                                                                 "campaignId" => 449060003,
                                                                 "batchId" => 447060003,
                                                                 "fromNumber" => "12135551126",
                                                                 "toNumber" => "12136666123",
                                                                 "label" => "my label",
                                                                 "states" => "READY,FINISHED,INVALID",
                                                                 "results" => "LA",
                                                                 "inbound" => true,
                                                                 "intervalBegin" => 1473781817000,
                                                                 "intervalEnd" => 1473781817000,
                                                                 "offset" => 0,
                                                                 "limit" => 10,
                                                                 "fields" => "items(id,fromNumber,toNumber,modified,finalCallResult)"));
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}
[-php] [[/code-container]]