Advertising Agency Tracking the Success of Advertisements

Story

ABC Advertising Company provides different advertising campaigns to their clients. They decided to find a service which can help to track the effectiveness of selected advertising campaigns. ABC Advertising can easily solve this task with the help of the CallFire platform. All they need is to purchase a phone number for every advertising campaign and configure Call Tracking.

Call Tracking utilizes a database of virtual numbers to create a local presence or maintain a global one. Purchase 10-digit numbers, place each unique phone number in a different location, channel, or medium, and compare the resulting call traffic. Our robust analytics provide detailed performance reports that can be linked to Google Analytics. From there you can determine which advertising methods are most effective.

Please refer to the Order Numbers Guide to find out how to purchase new numbers through the Developers' UI or the CallFire API.

Once you buy a number, you have two ways to configure call tracking on a given number using:

for both options you can use either the Developers' UI or a single API call.

How to Configure Call Tracking

A simple call tracking configuration allows you to quickly set up a transfer number, play a sound message upon transfer, record a call, add Google Analytics to track events, and other useful settings. See the full list of available settings below:

See the code examples below on how to configure a call tracking number using all available options:

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

#!/usr/bin/env bash

curl -u "username:password" -H "Content-Type:application/json" -X PUT -d '
    {
        "configType":"TRACKING",
        "callTrackingConfig":
        {
            "screen":"false",
            "recorded":"true",
            "voicemail":"true",
            "introSoundId":10004001,
            "whisperSoundId":10005002,
            "voicemailSoundId":10006003,
            "failedTransferSoundId":10007004,
            "transferNumbers":
            [
                "12135551122",
                "12135551189"
            ],
            "weeklySchedule":
            {
                "startTimeOfDay":
                {
                    "hour": 10,
                    "minute": 0,
                    "second": 0
                },
                "stopTimeOfDay": 
                {
                    "hour": 18,
                    "minute": 0,
                    "second": 0
                },
                "daysOfWeek": [
                    "MONDAY",
                    "TUESDAY",
                    "WEDNESDAY",
                    "THURSDAY",
                    "FRIDAY"
                ],
                "timeZone": "America/New_York"
            },
            "googleAnalytics": 
            {
                "domain":"domain-name",
                "googleAccountId":"UA-XXXXX-2X",
                "category":"Sales"
            }
        }
    }' "https://api.callfire.com/v2/numbers/leases/configs/19206596476"
response:
200 OK - No Response
[-curl] [+java]
import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.common.model.LocalTime;
import com.callfire.api.client.api.common.model.WeeklySchedule;
import com.callfire.api.client.api.numbers.model.CallTrackingConfig;
import com.callfire.api.client.api.numbers.model.GoogleAnalytics;
import com.callfire.api.client.api.numbers.model.NumberConfig;

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

class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient client = new CallfireClient("api_login", "api_password");
        NumberConfig config = new NumberConfig();
        config.setNumber("'19206596476'");
        config.setConfigType(NumberConfig.ConfigType.TRACKING);
        // create call tracking config
        CallTrackingConfig callTrackingConfig = new CallTrackingConfig();
        callTrackingConfig.setScreen(false);
        callTrackingConfig.setRecorded(true);
        callTrackingConfig.setRecorded(true);
        callTrackingConfig.setVoicemail(true);
        callTrackingConfig.setIntroSoundId(10004001L);
        callTrackingConfig.setWhisperSoundId(10005002L);
        callTrackingConfig.setVoicemailSoundId(10006003L);
        callTrackingConfig.setFailedTransferSoundId(10007004L);
        callTrackingConfig.setTransferNumbers(Arrays.asList("'12135551122", "'12135551189'"));

        WeeklySchedule schedule = new WeeklySchedule();
        schedule.setStartTimeOfDay(new LocalTime(10, 0, 0));
        schedule.setStopTimeOfDay(new LocalTime(18, 0, 0));
        schedule.setDaysOfWeek(new HashSet<>(
                Arrays.asList(DayOfWeek.MONDAY, DayOfWeek.TUESDAY, DayOfWeek.THURSDAY, DayOfWeek.WEDNESDAY, DayOfWeek.FRIDAY)));
        schedule.setTimeZone("America/New_York");
        callTrackingConfig.setWeeklySchedule(schedule);

        GoogleAnalytics googleAnalytics = new GoogleAnalytics();
        googleAnalytics.setDomain("domain - name");
        googleAnalytics.setCategory("Sales");
        googleAnalytics.setGoogleAccountId("UA - XXXXX - 2X");
        callTrackingConfig.setGoogleAnalytics(googleAnalytics);

        config.setCallTrackingConfig(callTrackingConfig);
        client.numberLeasesApi().updateConfig(config);
    }
}
[-java] [+csharp]
using System.Collections.Generic;
using CallfireApiClient;
using CallfireApiClient.Api.Numbers.Model;
using CallfireApiClient.Api.Common.Model;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        // create new call tracking config
        var callTrackingConfig = new CallTrackingConfig
        {
            Screen = false,
            Recorded = true,
            Voicemail = true,
            IntroSoundId = 10004001,
            WhisperSoundId = 10005002,
            VoicemailSoundId = 10006003,
            FailedTransferSoundId = 10007004,
            TransferNumbers = new List<string> {"12135551122", "12135551189"},
            WeeklySchedule = new WeeklySchedule()
            {
                StartTimeOfDay = new LocalTime { Hour = 10, Minute = 0, Second = 0 },
                StopTimeOfDay = new LocalTime { Hour = 18, Minute = 0, Second = 0 },
                DaysOfWeek = new HashSet<DayOfWeek> { DayOfWeek.MONDAY, DayOfWeek.TUESDAY, DayOfWeek.WEDNESDAY, DayOfWeek.THURSDAY, DayOfWeek.FRIDAY },
                TimeZone = "America/New_York"
            },
            GoogleAnalytics = new GoogleAnalytics ()
            {
                Domain = "domain - name",
                GoogleAccountId = "UA - XXXXX - 2X",
                Category = "Sales"
            }
        };
        NumberConfig config = new NumberConfig
        {
            Number = "19206596476",
            ConfigType = NumberConfig.NumberConfigType.TRACKING,
            CallTrackingConfig = callTrackingConfig
        };
        client.NumberLeasesApi.UpdateConfig(config);
    }
}
[-csharp] [+js]
'strict'

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

client.ready(() => {
    client.numbers.updateNumberLeaseConfig({
      number: '19206596476',
      body: {
        configType: 'TRACKING',
        callTrackingConfig: {
          screen: false,
          recorded: true,
          voicemail: true,
          introSoundId: 10004001,
          whisperSoundId: 10005002,
          voicemailSoundId: 10006003,
          failedTransferSoundId: 10007004,
          transferNumbers: [
            '12135551122',
            '12135551189'
          ],
          weeklySchedule: {
            startTimeOfDay: {
              hour: 10,
              minute: 0,
              second: 0
            },
            stopTimeOfDay: {
              hour: 18,
              minute: 0,
              second: 0
            },
            daysOfWeek: [
              'MONDAY',
              'TUESDAY',
              'WEDNESDAY',
              'THURSDAY',
              'FRIDAY',
            ],
            timeZone: 'America/New_York'
          },
          googleAnalytics: {
            domain: 'domain - name',
            googleAccountId: 'UA - XXXXX - 2X',
            category: 'Sales'
          }
        }
      }
    })
      .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.numbers.updateNumberLeaseConfig(
    number='19206596476',
    body={
        'configType': 'TRACKING',
        'callTrackingConfig': {
            'screen': False,
            'recorded': True,
            'voicemail': True,
            'introSoundId': 10004001,
            'whisperSoundId': 10005002,
            'voicemailSoundId': 10006003,
            'failedTransferSoundId': 10007004,
            'transferNumbers': [
                '12135551122',
                '12135551189'
            ],
            'weeklySchedule': {
                'startTimeOfDay': {
                    'hour': 10,
                    'minute': 0,
                    'second': 0
                },
                'stopTimeOfDay': {
                    'hour': 18,
                    'minute': 0,
                    'second': 0
                },
                'daysOfWeek': [
                    'MONDAY',
                    'TUESDAY',
                    'WEDNESDAY',
                    'THURSDAY',
                    'FRIDAY',
                ],
                'timeZone': 'America/New_York'
            },
            'googleAnalytics': {
                'domain': 'domain - name',
                'googleAccountId': 'UA - XXXXX - 2X',
                'category': 'Sales'
            }
        }
    }
).result()
[-python] [+php]
<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->updateNumberLeaseConfig();
        $request->getOperationConfig()->setPathParameters(array("number" => "19206596476"));
        $body = '{
                    "configType":"TRACKING",
                    "callTrackingConfig":
                    {
                        "screen":"false",
                        "recorded":"true",
                        "voicemail":"true",
                        "introSoundId":10004001,
                        "whisperSoundId":10005002,
                        "voicemailSoundId":10006003,
                        "failedTransferSoundId":10007004,
                        "transferNumbers":
                        [
                            "12135551122",
                            "12135551189"
                        ],
                        "weeklySchedule":
                        {
                            "startTimeOfDay":
                            {
                                "hour": 10,
                                "minute": 0,
                                "second": 0
                            },
                            "stopTimeOfDay":
                            {
                                "hour": 18,
                                "minute": 0,
                                "second": 0
                            },
                            "daysOfWeek":
                            [
                                "MONDAY",
                                "TUESDAY",
                                "WEDNESDAY",
                                "THURSDAY",
                                "FRIDAY"
                            ],
                            "timeZone": "America/New_York"
                        },
                        "googleAnalytics":
                        {
                            "domain":"domain-name",
                            "googleAccountId":"UA-XXXXX-2X",
                            "category":"Sales"
                        }
                    }
                 }';
        $request->getOperationConfig()->setBodyParameter($body);
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}

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

How to Set up an Inbound IVR

The term IVR stands for Interactive Voice Response. An IVR provides more a advanced configuration. You can ask questions through pre-recorded or auto-voice prompts, receive response via a phone pad key-press, and/or transfer to a specific phone number depending on user's responses.

Below is an example IVR XML dialplan which asks the user to press 1 or 2 to transfer either to sales or support representatives; also, it stores what the user has chosen, so for instance, you can gather statistics about how many clients are transferred to sales or support numbers:

<dialplan name="Root">
    <menu maxDigits="1" timeout="3500" name="Live">
        <play type="tts" voice="female1">
            Hello this is AB Advertising, please press 1 to transfer to our sales representative, 
            press 2 to contact clients support.
        </play>
        <keypress pressed="1">
             <!-- user pressed 1, store this data in 'selected_menu' variable -->
            <stash varname="selected_menu">sales</stash>
            <play type="tts" voice="female1">
                You will be transferred to sales representative in a moment. Please wait.
            </play>
            <transfer callerid="${call.callerid}" musiconhold="blues" mode="ringall">
                15550004455
            </transfer>
        </keypress>
        <keypress pressed="2">
             <!-- user pressed 2, store this data in 'selected_menu' variable -->
            <stash varname="selected_menu">support</stash>
            <play type="tts" voice="female1">
                You will be transferred to clients support. Please wait.
            </play>
            <transfer callerid="${call.callerid}" musiconhold="blues" mode="ringall">
                15550005500
            </transfer>
        </keypress>
         <!-- if pressed key is not specified in menu replay Live menu -->
        <keypress pressed="default" name="incorrect_Selection">
            <play type="tts" voice="female1">That is not a valid selection. Please try again.</play>
            <goto name="replay_Live">Live</goto>
        </keypress>
    </menu>
    <play type="tts" voice="female1">
        Thank you for calling us. Have a good day.
    </play>
    <hangup name="Hangup"/>
</dialplan>

You can find more information about the IVR on CallFire Answers Page also different IVR examples are available on our public Github repository.

Check the CallFire XML page for a detailed description of all IVR tags.

The next code samples show how to set up an inbound IVR for a previously purchased number:

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

#!/usr/bin/env bash

curl -u "username:password" -H "Content-Type:application/json" -X PUT -d '
    {
        "configType":"IVR",
        "ivrInboundConfig":
        {
            "dialplanXml":"<dialplan name=\"Root\"> <menu maxDigits=\"1\" timeout=\"3500\" name=\"Live\"> <play type=\"tts\" voice=\"female1\"> Hello this is AB Advertising, please press 1 to transfer to our sales repreentative, press 2 to contact clients support. </play> <keypress pressed=\"1\"> <stash varname=\"selected_menu\">sales</stash> <play type=\"tts\" voice=\"female1\"> You will be transferred to sales representative in a moment. Please wait. </play> <transfer callerid=\"${call.callerid}\" musiconhold=\"blues\" mode=\"ringall\"> 15550004455 </transfer> </keypress> <keypress pressed=\"2\" name=\"kp_become_volonteer\"> <stash varname=\"selected_menu\">sales</stash> <play type=\"tts\" voice=\"female1\"> You will be transferred to clients support. Please wait. </play> <transfer callerid=\"${call.callerid}\" musiconhold=\"blues\" mode=\"ringall\"> 15550005500 </transfer> </keypress> <keypress pressed=\"default\" name=\"incorrect_Selection\"> <play type=\"tts\" voice=\"female1\">That is not a valid selection. Please try again.</play> <goto name=\"replay_Live\">Live</goto> </keypress> </menu> <play type=\"tts\" voice=\"female1\"> Thank you for calling us. Have a good day. </play> <hangup name=\"Hangup\"/> </dialplan> "
        }
    }' "https://api.callfire.com/v2/numbers/leases/configs/19206596476"
response:
200 OK - No Response
[-curl] [+java]
import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.numbers.model.IvrInboundConfig;
import com.callfire.api.client.api.numbers.model.NumberConfig;

class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient client = new CallfireClient("api_login", "api_password");
        NumberConfig config = new NumberConfig();
        config.setNumber("19206596476");
        config.setConfigType(NumberConfig.ConfigType.IVR);
        // create IVR config
        IvrInboundConfig ivrInboundConfig = new IvrInboundConfig();
        ivrInboundConfig.setDialplanXml(buildDialplanXml());
        config.setIvrInboundConfig(ivrInboundConfig);
        // update number configuration
        client.numberLeasesApi().updateConfig(config);
    }

    private static String buildDialplanXml() {
        return
            " <dialplan name=\"Root\">                                                                                        "
                + " <menu maxDigits=\"1\" timeout=\"3500\" name=\"Live\">                                                     "
                + "     <play type=\"tts\" voice=\"female1\">                                                                 "
                + "         Hello this is AB Advertising, please press 1 to transfer to our sales representative,              "
                + "         press 2 to contact clients support.                                                               "
                + "      </play>                                                                                              "
                + "      <keypress pressed=\"1\">                                                                             "
                + "          <!-- user pressed 1, store this data in 'selected_menu' variable -->                             "
                + "          <stash varname=\"selected_menu\">sales</stash>                                                   "
                + "          <play type=\"tts\" voice=\"female1\">                                                            "
                + "              You will be transferred to sales representative in a moment. Please wait.                    "
                + "          </play>                                                                                          "
                + "          <transfer callerid=\"${call.callerid}\" musiconhold=\"blues\" mode=\"ringall\">                  "
                + "              15550004455                                                                                  "
                + "          </transfer>                                                                                      "
                + "          </keypress>                                                                                      "
                + "          <keypress pressed=\"2\" name=\"kp_become_volonteer\">                                            "
                + "              <!-- user pressed 2, store this data in 'selected_menu' variable -->                         "
                + "              <stash varname=\"selected_menu\">support</stash>                                             "
                + "              <play type=\"tts\" voice=\"female1\">                                                        "
                + "                  You will be transferred to clients support. Please wait.                                 "
                + "              </play>                                                                                      "
                + "              <transfer callerid=\"${call.callerid}\" musiconhold=\"blues\" mode=\"ringall\">              "
                + "                  15550005500                                                                              "
                + "              </transfer>                                                                                  "
                + "           </keypress>                                                                                     "
                + "           <!-- if pressed key is not specified in menu replay Live menu -->                               "
                + "           <keypress pressed=\"default\" name=\"incorrect_Selection\">                                     "
                + "               <play type=\"tts\" voice=\"female1\">That is not a valid selection. Please try again.</play>"
                + "               <goto name=\"replay_Live\">Live</goto>                                                      "
                + "           </keypress>                                                                                     "
                + " </menu>                                                                                                   "
                + " <play type=\"tts\" voice=\"female1\">                                                                     "
                + "     Thank you for calling us. Have a good day.                                                            "
                + " </play>                                                                                                   "
                + " <hangup name=\"Hangup\"/>                                                                                 "
                + " </dialplan>                                                                                               ";
    }
}
[-java] [+csharp]
using CallfireApiClient;
using CallfireApiClient.Api.Numbers.Model;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        // create new IVR config
        var config = new NumberConfig
        {
            Number = "19206596476",
            ConfigType = NumberConfig.NumberConfigType.IVR,
            IvrInboundConfig = new IvrInboundConfig
            {
                DialplanXml = @"
                    <dialplan name=""Root"">
                        <menu maxDigits=""1"" timeout=""3500"" name=""Live"">
                            <play type=""tts"" voice=""female1"">
                                Hello this is AB Advertising, please press 1 to transfer to our sales representative, 
                                press 2 to contact clients support.
                            </play>
                            <keypress pressed=""1"">
                                 <!-- user pressed 1, store this data in 'selected_menu' variable -->
                                <stash varname=""selected_menu"">sales</stash>
                                <play type=""tts"" voice=""female1"">
                                    You will be transferred to sales representative in a moment. Please wait.
                                </play>
                                <transfer callerid=""${call.callerid}"" musiconhold=""blues"" mode=""ringall"">
                                    15550004455
                                </transfer>
                            </keypress>
                            <keypress pressed=""2"" name=""kp_become_volonteer"">
                                 <!-- user pressed 2, store this data in 'selected_menu' variable -->
                                <stash varname=""selected_menu"">support</stash>
                                <play type=""tts"" voice=""female1"">
                                    You will be transferred to clients support. Please wait.
                                </play>
                                <transfer callerid=""${call.callerid}"" musiconhold=""blues"" mode=""ringall"">
                                    15550005500
                                </transfer>
                            </keypress>
                             <!-- if pressed key is not specified in menu replay Live menu -->
                            <keypress pressed=""default"" name=""incorrect_Selection"">
                                <play type=""tts"" voice=""female1"">That is not a valid selection. Please try again.</play>
                                <goto name=""replay_Live"">Live</goto>
                            </keypress>
                        </menu>
                        <play type=""tts"" voice=""female1"">
                            Thank you for calling us. Have a good day.
                        </play>
                        <hangup name=""Hangup""/>
                    </dialplan>
                "
            }
        };
        client.NumberLeasesApi.UpdateConfig(config);
    }
}
[-csharp] [+js]
'strict'

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

client.ready(() => {
    client.numbers.updateNumberLeaseConfig({
      number: '19206596476',
      body: {
        configType: 'IVR',
        ivrInboundConfig: {
          dialplanXml: '<dialplan name="Root"> <menu maxDigits="1" timeout="3500" name="Live"> <play type="tts" voice="female1"> Hello this is AB Advertising, please press 1 to transfer to our sales repreentative, press 2 to contact clients support. </play> <keypress pressed="1"> <stash varname="selected_menu">sales</stash> <play type="tts" voice="female1"> You will be transferred to sales representative in a moment. Please wait. </play> <transfer callerid="${call.callerid}" musiconhold="blues" mode="ringall"> 15550004455 </transfer> </keypress> <keypress pressed="2" name="kp_become_volonteer"> <stash varname="selected_menu">sales</stash> <play type="tts" voice="female1"> You will be transferred to clients support. Please wait. </play> <transfer callerid="${call.callerid}" musiconhold="blues" mode="ringall"> 15550005500 </transfer> </keypress> <keypress pressed="default" name="incorrect_Selection"> <play type="tts" voice="female1">That is not a valid selection. Please try again.</play> <goto name="replay_Live">Live</goto> </keypress> </menu> <play type="tts" voice="female1"> Thank you for calling us. Have a good day. </play> <hangup name="Hangup"/> </dialplan> '
        }
      }
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);
[-js] [+python]
from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
client.numbers.updateNumberLeaseConfig(
    number='19206596476',
    body={
        'configType': 'IVR',
        'ivrInboundConfig': {
            'dialplanXml': '<dialplan name="Root"> <menu maxDigits="1" timeout="3500" name="Live"> <play type="tts" voice="female1"> Hello this is AB Advertising, please press 1 to transfer to our sales repreentative, press 2 to contact clients support. </play> <keypress pressed="1"> <stash varname="selected_menu">sales</stash> <play type="tts" voice="female1"> You will be transferred to sales representative in a moment. Please wait. </play> <transfer callerid="${call.callerid}" musiconhold="blues" mode="ringall"> 15550004455 </transfer> </keypress> <keypress pressed="2" name="kp_become_volonteer"> <stash varname="selected_menu">sales</stash> <play type="tts" voice="female1"> You will be transferred to clients support. Please wait. </play> <transfer callerid="${call.callerid}" musiconhold="blues" mode="ringall"> 15550005500 </transfer> </keypress> <keypress pressed="default" name="incorrect_Selection"> <play type="tts" voice="female1">That is not a valid selection. Please try again.</play> <goto name="replay_Live">Live</goto> </keypress> </menu> <play type="tts" voice="female1"> Thank you for calling us. Have a good day. </play> <hangup name="Hangup"/> </dialplan> '
        }
    }
).result()
[-python] [+php]
<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->updateNumberLeaseConfig();
        $request->getOperationConfig()->setPathParameters(array("number" => "19206596476"));
        $body = '{
                    "configType":"IVR",
                    "ivrInboundConfig":
                    {
                        "dialplanXml":"<dialplan name=\"Root\"> <menu maxDigits=\"1\" timeout=\"3500\" name=\"Live\"> <play type=\"tts\" voice=\"female1\"> Hello this is AB Advertising, please press 1 to transfer to our sales repreentative, press 2 to contact clients support. </play> <keypress pressed=\"1\"> <stash varname=\"selected_menu\">sales</stash> <play type=\"tts\" voice=\"female1\"> You will be transferred to sales representative in a moment. Please wait. </play> <transfer callerid=\"${call.callerid}\" musiconhold=\"blues\" mode=\"ringall\"> 15550004455 </transfer> </keypress> <keypress pressed=\"2\" name=\"kp_become_volonteer\"> <stash varname=\"selected_menu\">sales</stash> <play type=\"tts\" voice=\"female1\"> You will be transferred to clients support. Please wait. </play> <transfer callerid=\"${call.callerid}\" musiconhold=\"blues\" mode=\"ringall\"> 15550005500 </transfer> </keypress> <keypress pressed=\"default\" name=\"incorrect_Selection\"> <play type=\"tts\" voice=\"female1\">That is not a valid selection. Please try again.</play> <goto name=\"replay_Live\">Live</goto> </keypress> </menu> <play type=\"tts\" voice=\"female1\"> Thank you for calling us. Have a good day. </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 Query Calls and Pull User's Data

CallFire provides two ways of getting a user's data:

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 Inbound Calls and Texts to your service. Check the webhooks guide for more information about CallFire Webhooks.

The following examples show how to query calls. You can find the user's data in 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]]

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