CallFire Solutions

Provisioning a Phone Number How-to

Follow

Provisioning a phone number can be quite a tricky process, tricky in that there’s quite a number of steps involved. What’s more, the process varies slightly, depending on whether you’re a new customer to CallFire, or whether you’ve been using the platform for some time.

In this How-To, we’re going to step through the process of provisioning a phone number and keywords, using both the REST and SOAP APIs. To ensure that your understanding is as well-rounded as possible, we’ll take in to account as many variations as is practically possible.

By the time we’re finished, you’ll be able to create an application which can manage all of the various aspects involved in provisioning a phone number. To help make it easier to envisage, here’s a simple scenario, which will form the basis of the how-to:

You’re setting up a new business, in San Francisco, and you want to be able to programmatically provision a set of phone numbers for the business. So you want to create a small application which interacts with CallFire’s API which will be able to do this.

What Is Provisioning?

In short, provisioning is the process of adding one or more phone numbers to your CallFire account, then configuring them to work the way you need them to. As concisely as possible, the provisioning process involves the following steps:

  1. Search for numbers to purchase (and provision)
  2. Create a number order
  3. Retrieve a number order
  4. Viewing numbers on your account
  5. Configure a number
  6. Viewing details of a number on your account
  7. Releasing a number on your account

There’s also one last step, releasing a number, which at some point you’ll need to use. The reason why it’s separate, is because the first four steps add numbers to, or configure numbers on, your account.

Releasing a number however, as the name implies, releases it from your account, making it available for purchase by other users after the next billing cycle. So it’s more of an addition to the core work of provisioning, as opposed to being a direct part of it.

Client Libraries & Languages

In this How-To, you’ll see code examples using PHP, Node.js and Go. The PHP code samples will use our PHP Software Development Kit (SDK). Currently we don’t have SDKs for either Node.js or Go; but these are in the works and should be available before too long.

PHP

If you’re using Composer to manage your project dependencies, add `”callfire/php-sdk“:”1.1.5" to your composer.json file:

{
  "require": {
    "callfire/php-sdk": "1.1.5"
  }
}

You can also get started without Composer, or download the source directly.

Go

Whilst we don’t provide an official SDK for Go, we’ve put together some helper code, which makes interacting with CallFire’s API a bit easier, requiring less code to be written.

However, the helper code is just that, helper code. It only aids in making the code samples less verbose. It isn’t professionally packaged code. Please keep that in mind if you use it.

We also make the assumptions that you’re more than familiar with HTTP requests as well as parsing of XML responses. So please also keep this in mind, as you read through the Go code examples.

To get started with it, install the package:

go get github.com/callfire/callfire-go

Then import the package into your source file:

import (
    "github.com/callfire/callfire-go"
)

If you need more information, check out the source on GitHub.

Node.js

The Node.js code samples make the assumption that you’re familiar enough with making HTTP requests and parsing XML responses. They show just enough to document the respective API requests.

Accessing The API

In order to access the CallFire API you need to pass two credentials with each request; these are a login and password. To get these, in your CallFire account, you’ll need to create a new application, if you haven’t already. To do so, underSettings -> API Access click the button marked “+ Add API Access”, which you can see in the screenshot above.

This will open a modal dialog which where you need to enter an app name and agree to the terms of service. Before you click “Save” click “Copy” over on the right-hand side of the dialog to copy the app login and password to the clipboard, or copy & paste them individually.


CallFire - enter access details

Retrieve Details From An Existing Application

If you already have an application created, to retrieve its details, click its name, under “Application Name”, in the list of applications. A modal dialog will then open, where you can copy the login and password. With access ready to go, let’s get started provisioning a number.


CallFire - view access details.png

Step 1. Searching For Numbers To Purchase

To search for a set of numbers, requires a GET request to the /numbers/search endpoint. The endpoint allows for filtering either by a toll-free status or by supplying region information, such as prefix, city, and zip code, etc.

Why Not Just Search For Everything?

There’s a couple of reasons why you need to provide filter criteria:

  • Resultset size
  • Phone number type

Resultset Size

With no filter criteria provided, the result sets returned may be enormous. This will likely result in both time-consuming request times, as well as providing phone numbers which aren’t useful to your business or organization.

Phone Number Type

Phone numbers need to be provided from Rate Centers located as close to the business’ or organization’s location as possible. When numbers are assigned from local Rate Centers they will be deemed as local. Otherwise, there’s the risk of creating a long distance number and incurring long distance call charges.

Code Samples

PHP SDK

<?php
require 'vendor/autoload.php';

use CallFire\Api\Rest\Request,                                                                                                                                                                                                              
    CallFire\Api\Rest\Response;

// Initialize the CallFire REST Api Client
$callfireNumberClient = CallFire\Api\Client::Rest(
    'YOUR_LOGIN', 'YOUR_PASSWORD', 'Number'
);

// Initialize a \CallFire\Api\Rest\Request\SearchAvailableNumbers object to search
// with city, state, country and count parameters
$searchAvailableNumbers = new Request\SearchAvailableNumbers();
$searchAvailableNumbers->setCity('Los Angeles')
        ->setCount(12)
        ->setState('CA')
        ->setCountry('US');

// Make the request against the endpoint
$response = $callfireNumberClient->SearchAvailableNumbers(
    $searchAvailableNumbers
);

// Marshall the response into a \CallFire\Api\Rest\Response\ResourceList object,
// which contains a list of \CallFire\Common\Resource\Number objects
$result = $callfireNumberClient::response($response);

Node.js

var querystring = require('querystring');
var https = require('https');

// Create the query string to pass to the request      
var endpoint = '?' + querystring.stringify({ 
    Count: 5,
    City: 'Los Angeles',
    State: 'CA',
    Country: 'US'
});

// Initialize the request parameters
var options = {
    host: 'www.callfire.com',
    path: '/api/1.1/rest/number/search',
    query: endpoint,
    // Specify the authorization credentials
    auth: 'YOUR_LOGIN' + ':' + 'YOUR_PASSWORD'  
};
  
// Initialize a GET request 
var req = https.get(options, function(res) {
        // Print the response payload to stdout, if available
    res.on('data', function(d) {
        process.stdout.write(d);
    });
}).on('error', function(e) {
    console.error(e);
});

req.end();

Go

package main

import (
    "fmt"
    "github.com/google/go-querystring/query"
    "github.com/settermjd/callfire"
    "io/ioutil"
    "log"
)

func main() {
    // Initialise the search parameters, which will form the query string
    opt := callfire.RequestOptions{
        Count: 5, City: "Los Angeles", State: "CA", Country: "US",
    }
    v, _ := query.Values(opt)

    // Make a GET request against the endpoint
    requestOptions := callfire.CallFireRequestOptions{
        Url:           "https://www.callfire.com/api/1.1/rest/number/search?",
        Login:         "YOUR_LOGIN",
        Secret:        "YOUR_PASSWORD",
        ReqType:       "GET",
        RequestOptions: v.Encode(),
    }
    client, req := callfire.InitHttpClient(requestOptions)
    
    resp, err := client.Do(req)

    if err != nil {
        log.Fatal(err)
    }

    // Retrieve the body of the response
    body, err := ioutil.ReadAll(resp.Body)
    resp.Body.Close()

    if err != nil {
        log.Fatal(err)
    }

    // Dump the response
    fmt.Printf("%s", body)
}

Note: There are a number of other search criteria available, which can be used in addition to the one’s in the code samples above. To see them all, check out the API, to learn more about them.

Response

Data Available

Running each of the code samples will return an XML response payload, such as the sample below. The response will contain a range of information about the numbers which matched the search criteria.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<r:ResourceList xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource" totalResults="5">
    <Number>
        <Number>12092084590</Number>
        <NationalFormat>(213) 204-9665</NationalFormat>
        <TollFree>false</TollFree>
        <Region>
            <Prefix>1209208</Prefix>
            <City>LOS ANGELES</City>
            <State>CA</State>
            <Zipcode>90079</Zipcode>
            <Country>US</Country>
            <Lata>730</Lata>
            <RateCenter>LSAN DA 07</RateCenter>
            <Latitude>34.0462</Latitude>
            <Longitude>-118.2568</Longitude>
            <TimeZone>America/Los_Angeles</TimeZone>
        </Region>
    </Number>
    <Number>
        <Number>12092084589</Number>
        <NationalFormat>(213) 204-9665</NationalFormat>
        <TollFree>false</TollFree>
        <Region>
            <Prefix>1209208</Prefix>
            <City>LOS ANGELES</City>
            <State>CA</State>
            <Zipcode>90079</Zipcode>
            <Country>US</Country>
            <Lata>730</Lata>
            <RateCenter>LSAN DA 07</RateCenter>
            <Latitude>34.0462</Latitude>
            <Longitude>-118.2568</Longitude>
            <TimeZone>America/Los_Angeles</TimeZone>
        </Region>
    </Number>
</r:ResourceList>

The most essential information for this how-to is the Number/Number element. However, you can also see the region information allocated to that number. With the XML payload returned, we now have two phone numbers we can purchase: 12092084590 and 12092084589.

Note: Numbers are specified in the E.164 format. You’d normally see them written as +1 (209) 208 4590 and+1 (209) 208 4589.

No Matching Results

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<r:ResourceList xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource" 
  totalResults="0"/>

Errors

Unauthorized

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<r:ResourceException xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">
    <r:HttpStatus>401</r:HttpStatus>
    <r:Message>UNAUTHORIZED</r:Message>
</r:ResourceException>

Step 2. Create a Number Order

With the two numbers we’ve identified, we now need to create an order to purchase them. To do that, we make a POSTrequest to the /number/order endpoint of the API, which may take up to 20 seconds to complete. This request will create a number order and return an orderId which can be used to check on the status of the order.

Tip: Creating a number order is an asynchronous process Given that, there is no guarantee an order will be finished by the time the request is completed. So we recommend setting up a Postback to be automatically alerted when the order is ready.

Order States

When an order is initialized, until it’s completed, it will be in one of the following three states.

StateDescription
PROCESSING The order is still being processed
FINISHED The order successfully completed and the numbers are linked to your account
ERRORED There was an error in creating the order

Code Samples

PHP SDK

<?php
// Initialize a \CallFire\Api\Rest\Request\CreateNumberOrder object to purchase two numbers
$numberOrder = new Request\CreateNumberOrder();
$numberOrder->setNumbers(array(
    "+12092084590", "+12092084589"
));

// Make a request to purchase the two phone numbers
$response = $callfireNumberClient->CreateNumberOrder($numberOrder);

// Marshall the response payload
$result = $callfireNumberClient::response($response);

Node.js

var querystring = require('querystring');
var https = require('https');

var data  = {
    Numbers: "12092084590+12092084589"
};
var endpoint = '?' + querystring.stringify(data);
var options = {
    host: 'www.callfire.com',
    path: '/api/1.1/rest/number/order',
    query: endpoint,
    auth: 'YOUR_LOGIN' + ':' + 'YOUR_PASSWORD',
    method: 'POST'
};

var req = https.request(options, function(res) {
    res.on('data', function(d) {
        process.stdout.write(d);
    });
}).on('error', function(e) {
    console.error(e);
});

req.end();

Go

requestOptions := callfire.CallFireRequestOptions{
    Url:            "https://www.callfire.com/api/1.1/rest/number/order?",
    Login:          "YOUR_LOGIN",
    Secret:         "YOUR_PASSWORD",
    ReqType:        "POST",
    RequestOptions: "Numbers=12092084590+12092084589&",
}
client, req := callfire.InitHttpClient(requestOptions)
resp, err := client.Do(req)

Sample Response

Running any of the code samples above will return an XML response payload, such as the sample below, where we see an order id of 12092084589.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<r:ResourceReference xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">
      <r:Id>1642251003</r:Id>
      <r:Location>https://www.callfire.com/api/1.1/rest/number/order/1642251003</r:Location>
</r:ResourceReference>

Errors

Unauthorized Access

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<r:ResourceException xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">
    <r:HttpStatus>401</r:HttpStatus>
    <r:Message>UNAUTHORIZED</r:Message>
</r:ResourceException>

Step 3. Retrieve a Number Order

Now that we’ve created an order (we’ll assume that it was successful) and have its order id, 12092084589, next we need to make a GET request to the /number/order/:orderId endpoint to retrieve the order’s details. This will, similar to some of the other requests, return the phone numbers on your account, along with the region information.

Code Samples

PHP SDK

$orderId = '1642251003';

// Make a request for the order with id 1642251003
$response = $callfireNumberClient->GetNumberOrder($orderId);

$result = $callfireNumberClient::response($response);

Node.js

var querystring = require('querystring');
var https = require('https');

var orderId = 'YOUR_ORDER_ID';

// Initialize the request parameters
var options = {
    host: 'www.callfire.com',
    path: '/api/1.1/rest/number/order/' + orderId,
    auth: 'YOUR_LOGIN' + ':' + 'YOUR_PASSWORD'
};

// Initialize the request
var req = https.get(options, function(res) {
    // Print the response payload to stdout, if available
    res.on('data', function(d) {
        process.stdout.write(d);
    });
}).on('error', function(e) {
    console.error(e);
});

req.end();

Go

requestOptions := callfire.CallFireRequestOptions{
    Url:     "https://www.callfire.com/api/1.1/rest/number/order/12092084589",
    Login:   "YOUR_LOGIN",
    Secret:  "YOUR_PASSWORD",
    ReqType: "GET",
}
client, req := callfire.InitHttpClient(requestOptions)

resp, err := client.Do(req)

Responses

After running any of the code samples above, if an order is found, it will return an XML response payload, such as the sample below, which contains the order details.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<r:Resource xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">
      <NumberOrder id="1642251003">
            <Status>FINISHED</Status>
            <Created>2015-02-12T12:06:39Z</Created>
            <TotalCost>50.0</TotalCost>
            <Keywords>
                  <Ordered>2</Ordered>
                  <UnitCost>25.0</UnitCost>
                  <Fulfilled>YELLOWTAXI ORANGEBROADSWORD</Fulfilled>
            </Keywords>
      </NumberOrder>
</r:Resource>

Errors

Unavailable Order

If an order’s not able to be located, then the following XML response payload will be returned.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<r:ResourceException xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">
    <r:HttpStatus>404</r:HttpStatus>
    <r:Message>Not Found</r:Message>
</r:ResourceException>

Step 4. Viewing Numbers On Your Account

Now that we’ve added some numbers to our account, it’s time to see how to check that they’re available. To do that, we need to make a GET request to the number endpoint.

This endpoint returns, based on the search criteria supplied, all numbers assigned to our account. Similar to the other requests we’ve made in this how-to, a set of query parameters can be passed, to help filter down the results returned.

Code Samples

PHP SDK

// Initialise a \CallFire\Api\Rest\Request\QueryNumbers object for querying
// the API for numbers on the account, specifying the country, state, and city.
$configureNumber = new Request\QueryNumbers();

$configureNumber->setCountry('US')
    ->setState('CA')
    ->setCity('Los Angeles');

// Make a request for the numbers, based on the criteria in $configureNumber    
$response = $callfireNumberClient->QueryNumbers($configureNumber);

$numbers = $callfireNumberClient::response($response);

Node.js

var querystring = require('querystring');
var https = require('https');

// Initialise the request parameters
var options = {
    host: 'www.callfire.com',
    path: '/api/1.1/rest/number',
    auth: 'YOUR_LOGIN' + ':' + 'YOUR_PASSWORD'
};

// Initialise a GET request
var req = https.get(options, function(res) {
    // Print the response payload to stdout, if available
    res.on('data', function(d) {
        process.stdout.write(d);
    });
}).on('error', function(e) {
    console.error(e);
});

req.end();

Go

requestOptions := callfire.CallFireRequestOptions{
    Url:            "https://www.callfire.com/api/1.1/rest/number",
    Login:          "YOUR_LOGIN",
    Secret:         "YOUR_PASSWORD",
    ReqType:        "GET",
}
client, req := callfire.InitHttpClient(requestOptions)
resp, err := client.Do(req)

Response

Assuming that the request to the endpoint was successful, you can expect an XML payload response similar to the one below.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<r:ResourceList xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource" totalResults="2"> 
    <Number> 
        <Number>12092084590</Number> 
        <NationalFormat>(209) 208-4590</NationalFormat> 
        <TollFree>false</TollFree> 
        <Region>
            <Prefix>1209208</Prefix> 
            <City>WATERFORD</City> 
            <State>CA</State>
            <Zipcode>95386</Zipcode> 
            <Country>US</Country> 
            <Lata>738</Lata>
            <RateCenter>KNIGHTFRRY</RateCenter> 
            <Latitude>37.8248</Latitude>
            <Longitude>-120.665</Longitude> 
            <TimeZone>America/Los_Angeles</TimeZone>
        </Region> 
        <Status>ACTIVE</Status> 
        <LeaseInfo>
            <LeaseBegin>2015-01-22Z</LeaseBegin> 
            <LeaseEnd>2015-02-21Z</LeaseEnd>
            <AutoRenew>true</AutoRenew> 
        </LeaseInfo> 
        <NumberConfiguration>
            <CallFeature>DISABLED</CallFeature> 
            <TextFeature>ENABLED</TextFeature>
        </NumberConfiguration> 
    </Number> 
</r:ResourceList> 

Step 5. Configure a Phone Number

After numbers have been added to our account, we can make changes to their configuration based on three, optional, parameters; these are CallFeature, TextFeature, and InboundCallConfigurationType.

To do this, we need to make a PUT request to the /number endpoint, specifying the number which we want to configure, along with the configuration options required.

Configuration Options Explained

CallFeature & TextFeature

CallFeature governs the ability (inbound and outbound) to make and receive calls on that number. TextFeature governs the ability to send and receive text messages. The accepted values for both of these options are:

FeatureDescription
ENABLED Enable the feature
DISABLED Disable the feature
UNSUPPORTED This is for numbers that don’t support SMS, e.g., land lines
PENDING Pending means that a change to the numbers in progress

Note: Neither UNSUPPORTED, nor PENDING are able to be set. They’re notification of an existing state on the number.

InboundCallConfigurationType

Enables the number to be setup as either a Tracking or IVR type by passing the value of either TRACKING or IVR.

ParameterDescriptionType
IvrInboundConfig[id] The ID in the database of that configuration. This is only available via a GET for the number details long
DialplanXml This is an XML string which is required to setup an Interactive Voice Response. file

Step 5a. Enabling Call & Disabling SMS Functionality

Code Samples

As there’s quite a lot of combinations available the examples in this section will take some time to work through. Let’s first start off by enabling one of the two numbers on our account, +1 209 208 4590 , to make and receive calls, yet not be able to send and receive SMS’.

PHP SDK
$number = "12092084590";

// Initialise a \CallFire\Api\Rest\Request\ConfigureNumber object, 
// setting it to enable calling but disable messaging on the number
$configureNumber = new Request\ConfigureNumber();
$configureNumber->setCallFeature('ENABLED')  // enable calling
                ->setTextFeature('DISABLED');   // disable messages

// Make the configuration request against the number in the account
$response = $callfireNumberClient->ConfigureNumber(
    "+" . $number, $configureNumber
); 

User Action: Try doing the reverse.

Node.js
var querystring = require('querystring');
var https = require('https');

var number = '12092084590';
var endpoint = '?' + querystring.stringify({
    Number: number,
    CallFeature: 'DISABLED',
    TextFeature: 'ENABLED'
});
var options = {
    host: 'www.callfire.com',
    path: '/api/1.1/rest/number',
    query: endpoint,
    auth: 'YOUR_LOGIN' + ':' + 'YOUR_PASSWORD'
};

var req = https.request('PUT', options, function(res) {
    res.on('data', function(d) {
        process.stdout.write(d);
    });
}).on('error', function(e) {
    console.error(e);
});

req.end();
Go
requestOptions := callfire.CallFireRequestOptions{
    Url:            "https://www.callfire.com/api/1.1/rest/number/12092084589?",
    Login:          "YOUR_LOGIN",
    Secret:         "YOUR_PASSWORD",
    ReqType:        "PUT",
    RequestOptions: "CallFeature=enabled&TextFeature=disabled",
}
client, req := callfire.InitHttpClient(requestOptions)
resp, err := client.Do(req)

Response

This request does not return an XML payload on success, but it will return an HTTP status code 204.

Errors

If something goes wrong however, an XML payload is returned, along with an HTTP status code of 404.

Phone Number Does Not Exist or is Inactive

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<r:ResourceException xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">
      <r:HttpStatus>404</r:HttpStatus>
      <r:Message>number 12092084580 does not exist, or is inactive</r:Message>
</r:ResourceException>

Step 5b. Setting Up Call Tracking

Now let’s look at call tracking, which helps measure the impact of marketing effort on lead generation and sales. Configuring call tracking requires a combination of the following X parameters:

ArgumentTypeDescription
CallTrackingConfig[id] long The ID in the database of that configuration. This is only available via a GET for the number details
TransferNumber long Call tracking numbers always accept the call, and transfer it to a different number. TransferNumber is the call’s next destination. Up to three numbers, comma-separated, can be entered. The first number to accept the call is the one which is connected
Screen boolean Whether to tell the person who answers the call who is calling
Record boolean Whether to record the call or not.
IntroSoundId long This is the id of the sound which can be played to the caller before being transferred
WhisperSoundId long The id of a sound to be played to the call receiver before the call is connected. This isn’t heard by the caller

Note: Both the IntroSoundId and the WhisperSoundId are optional.

Six sounds come with your account by default, which you can find in the table below.

Sound NameSound Id
Sample Audio for Do Not Call 779683003
Sample Audio for Machines 779684003
Sample Audio for Transfers 779685003
Sample Audio for Live Answers 779686003
DNC Confirmation 779687003
Transfer Confirmation 779688003

To retrieve the available sound id’s you need to make a call to the /call/sound endpoint.

Creating a New Message Sound


create a new message sound in the callfire dashboard

You can also create a new message from the CallFire UI. To do this, after logging in, click “Phone Numbers”, pick a phone number, then click “Configure Tracking”. On the Configure Tracking page, under Sounds, click “Select a Message” in either the “Intro Message” or “Whisper Message” sections, click “Create a Message”.

This will open a final modal dialog where you can:

  1. Upload an audio file
  2. Record a sound via a phone call
  3. Create a message from text

Let’s now setup call tracking on the number with the following properties:

  • The call will not be recorded
  • The receiver will be able to see who is calling
  • The call will transfer to our second number: +1 209 208 4590
  • The Intro Sound will be Sample Audio for Live Answers
  • The Whisper Sound will be Transfer Confirmation

Code Samples

PHP SDK
$number = '12092084589';
$configureNumber = new Request\ConfigureNumber();                                                                       
$configureNumber->setTransferNumber('12092084590')
                ->setInboundCallConfigurationType('TRACKING')
                ->setRecord(false)
                ->setScreen(true)
                ->setWhisperSoundId('779688003')
                ->setIntroSoundId('779686003');

// Make the request to setup call tracking on the number
$response = $callfireNumberClient->ConfigureNumber(
     "+" . $number, $configureNumber
);

$result = $callfireNumberClient::response($response);

$result will be a boolean, so that you can know if the operation succeeded or failed.

Node.js
var querystring = require('querystring');
var https = require('https');

var number = '12092084589';
var endpoint = '?' + querystring.stringify({
    Number: number,
    InboundCallConfigurationType: 'TRACKING',
    TransferNumber: '12092084590',
    Screen: 'true',
    Record: 'false',
    IntroSoundId: '779686003',
    WhisperSoundId: '779688003'
});
var options = {
    host: 'www.callfire.com',
    path: '/api/1.1/rest/number',
    query: endpoint,
    auth: 'YOUR_LOGIN' + ':' + 'YOUR_PASSWORD'
};

var req = https.request('PUT', options, function(res) {
    res.on('data', function(d) {
        process.stdout.write(d);
    });
}).on('error', function(e) {
    console.error(e);
});

req.end();
Go
requestOptions := callfire.CallFireRequestOptions{
    Url:            "https://www.callfire.com/api/1.1/rest/number/12092084589?",
    Login:          "YOUR_LOGIN",
    Secret:         "YOUR_PASSWORD",
    ReqType:        "PUT",
    RequestOptions: "InboundCallConfigurationType=tracking&TransferNumber=12092084590&Screen=true&Record=true&IntroSoundId=779688003&WhisperSoundId=779686003",
}
client, req := callfire.InitHttpClient(requestOptions)
resp, err := client.Do(req)

Step 5c. Setting Up an IVR

Now let’s look at setting up an Interactive Voice Response (IVR). To configure an IVR requires only two parameters: IvrInboundConfig id and a DialPlanXml string.

Understanding the DialPlanXml Schema

By default, the DialPlanXml Schema looks as follows:

<dialplan name="Root">
    <play type="tts">Congratulations! You have successfully configured a CallFire I V R.</play>
    </dialplan></play>
</dialplan>

However, we’re going to use the following one, which you can find in the online documentation.

<dialplan name="Root">
    <menu maxDigits="1" timeout="4000" name="menu_top">
        <play type="tts" voice="female2" name="play_intro">Thank you for calling the Acme Corporation. For Sales press one. For Marketing please press two. to leave a message in our general voicemail press eight.</play>
        <keypress pressed="1" name="kp_1">
            <transfer name="trans_sales">8005551212</transfer>
        </keypress>
        <keypress pressed="2" name="kp_2">
            <transfer name="trans_marketing">8005551313</transfer>
        </keypress>
        <keypress pressed="8" name="kp_8">
            <record varname="general_voicemail" name="rec_voicemail"/>
        </keypress>
        <keypress pressed="default" name="kp_defalt">
            <play type="tts" voice="female2" name="play_default">I'm sorry. That's not a valid selection.</play>
            <goto name="goto_menuTop">menu_top</goto>
        </keypress>
        <keypress pressed="timeout" name="kp_timeout">
        </keypress>
    </menu>
</dialplan>

The configuration above, creates an IVR with 3 options: 1, 2, & 8. The message played when the call is answered will be spoken with a female voice, using the text inside the play element.

If number 1 is pressed, the user will be transferred to 8005551212. If number 2 is pressed, the user will be transferred to 8005551313. If number 8 is pressed, they’ll be able to leave a recorded message. If any other key is pressed, the user will be informed that the selection is not valid.

Going in-depth into the schema is outside the scope of this how-to. We’re just going to work with a simple example. But to find out everything about the schema, consult the online documentation.

Errors

If, for some reason, we failed to provide a phone number, the following XML payload will be returned.

Phone Number Wasn’t Provided

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<r:ResourceException xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">
    <r:HttpStatus>400</r:HttpStatus>
    <r:Message>no number data were provided</r:Message>
</r:ResourceException>

If something went wrong, whilst processing the request, then the following XML payload will be returned. If you receive this, please contact support for further information. You should rarely, if ever, receive such a payload.

Resource Error

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<r:ResourceException xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">
    <r:HttpStatus>500</r:HttpStatus>
    <r:Message>Internal resource exception. Ref: fef4dfbb-f49c-4ff2-bb7e-a3ecc40e63f3</r:Message>
</r:ResourceException>

Step 6. Viewing Details of a Number

After acquiring & provisioning phone numbers now it’s time to have a look at the details of a number. To do so, you need to make a GET request to the /number/{Number} endpoint. As you can see in the response section below, it returns a payload containing all the information about the number, which you’ve seen in the how-to so far.

In the NumberConfiguration section, you’ll see all of the options that are currently configured. In the example below, you can see that the number has the call and text features enabled, and call Tracking enabled, along with the settings for it. If the number was instead setup as an IVR, then that configuration would instead be present.

Code Samples

PHP SDK

// Call the GetNumber method, passing the phone number to query
$response = $callfireNumberClient->GetNumber("+".$number);

// Marshall the response into a \CallFire\Api\Rest\Response\Resource object
// which contains a list of \CallFire\Common\Resource\Number objects
$result = $callfireNumberClient::response($response);

// Iterate over the Resource object, displaying the properties. 
// Here's a quick sample
foreach ($result as $number) {
    printf(
        "Inbound Call Type: %s<br />
         Calls Enabled: %s<br />
         Messages Enabled: %s",
        // 'IVR' or 'Tracking'
        $number->getNumberConfiguration()->getInboundCallConfigurationType(), 
        // Is calling enabled?
        $number->getNumberConfiguration()->getCallFeature(),
        // Is messaging enabled?
        $number->getNumberConfiguration()->getTextFeature()
    );
}

Node.js

var querystring = require('querystring');
var https = require('https');

var req = https.get({
    host: 'www.callfire.com',
    path: '/api/1.1/rest/number/12092084590',
    auth: 'YOUR_LOGIN' + ':' + 'YOUR_PASSWORD'
}, function (res) {
    res.on('data', function (d) {
        process.stdout.write(d);
    });
}).on('error', function (e) {
    console.error(e);
});

req.end();

Go

requestOptions := callfire.CallFireRequestOptions{
    Url:            "https://www.callfire.com/api/1.1/rest/number/12092084589",
    Login:          "YOUR_LOGIN",
    Secret:         "YOUR_PASSWORD",
    ReqType:        "GET",
}
client, req := callfire.InitHttpClient(requestOptions)
resp, err := client.Do(req)

Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<r:Resource xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">
      <Number>
            <Number>12092084590</Number>
            <NationalFormat>(209) 208-4590</NationalFormat>
            <TollFree>false</TollFree>
            <Region>
                  <Prefix>1209208</Prefix>
                  <City>WATERFORD</City>
                  <State>CA</State>
                  <Zipcode>95386</Zipcode>
                  <Country>US</Country>
                  <Lata>738</Lata>
                  <RateCenter>KNIGHTFRRY</RateCenter>
                  <Latitude>37.8248</Latitude>
                  <Longitude>-120.665</Longitude>
                  <TimeZone>America/Los_Angeles</TimeZone>
            </Region>
            <Status>ACTIVE</Status>
            <LeaseInfo>
                  <LeaseBegin>2015-01-22Z</LeaseBegin>
                  <LeaseEnd>2015-02-21Z</LeaseEnd>
                  <AutoRenew>true</AutoRenew>
            </LeaseInfo>
            <NumberConfiguration>
                  <CallFeature>DISABLED</CallFeature>
                  <TextFeature>ENABLED</TextFeature>
                  <InboundCallConfigurationType>TRACKING</InboundCallConfigurationType>
                  <InboundCallConfiguration>
                        <CallTrackingConfig id="3978832003">
                              <TransferNumber>12092084591 12092084590</TransferNumber>
                              <Screen>false</Screen>
                              <Record>false</Record>
                              <IntroSoundId>779686003</IntroSoundId>
                              <WhisperSoundId>779688003</WhisperSoundId>
                        </CallTrackingConfig>
                  </InboundCallConfiguration>
            </NumberConfiguration>
      </Number>
</r:Resource>

Step 7. Releasing a Number On Your Account

Now that we’ve stepped through the process of provisioning phone numbers for our account, let’s look at how to release one or more numbers which we’ve provisioned.

CallFire’s system automatically renews the numbers you’ve purchased each month and bills you accordingly. So if & when you no longer need a number you should release it to avoid incurring recurring monthly charges.

Once you release a keyword, you will not be able to repurchase it for a month after the release becomes effective. So make sure you really want to release the number before making the request to the endpoint.

Tip: You can still use a phone number up to the expiry date, even if you release it beforehand .

So to release a number, we need to make a PUT request to the /number/release endpoint. This endpoint accepts one of two parameters, Number and Keyword.

Note: We’re not covering keywords in this how-to, so will just focus on Number.

Let’s assume that we no longer need it, so let’s see how to release it.

Code Samples

PHP SDK

$requestRelease = new Request\Release();
$requestRelease->setNumber($number);

/**
 * Will attempt to release the number.
 * If the request succeeds, $response will be a boolean. 
 * If the request fails, $response will be an \CallFire\Api\Rest\Response\ResourceException object
 */
$response = $callfireNumberClient->Release($requestRelease);

// Display the HTTP status and message if an error's encountered.
if ($result instanceof CallFire\Api\Rest\Response\ResourceException) {
  printf(
      "Status: %s / Message: %s<br />",
      $result->getHttpStatus(),
      $result->getMessage()
  );
}

Node.js

var querystring = require('querystring');
var https = require('https');

var data  = { 
  Number: '12092084591'
};
var dataString = JSON.stringify(data);
var endpoint = '?' + querystring.stringify(data);
var options = { 
host: 'www.callfire.com',
      path: '/api/1.1/rest/number/release',
      query: endpoint,
      method: 'PUT',
      auth: 'YOUR_LOGIN' + ':' + 'YOUR_PASSWORD'
};

var req = https.request(options, function(res) {
    res.on('data', function(d) {
      process.stdout.write(d);                                                                                                                                                               
      }); 
    }).on('error', function(e) {
      console.error(e);
      });

req.end();

Go

requestOptions := callfire.CallFireRequestOptions{
    Url:            "https://www.callfire.com/api/1.1/rest/number/release/",
    Login:          "YOUR_LOGIN",
    Secret:         "YOUR_PASSWORD",
    ReqType:        "PUT",
    RequestOptions: "Number=12092084590",
}
client, req := callfire.InitHttpClient(requestOptions)
resp, err := client.Do(req)

Response

As with enabling and disabling call and SMS functionality, this request, on success, doesn’t return an XML payload, but returns an HTTP 204 status code to indicate success.

Errors

However, if something goes wrong or if you attempt to release a number not associated with your account, it does, as in the example below.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<r:ResourceException xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">
    <r:HttpStatus>404</r:HttpStatus>
    <r:Message>number 12092084591 does not exist, or is inactive</r:Message>
</r:ResourceException>

Questions

If you have any questions, our support is available Mon - Fri between 8am and 4pm PT. You can reach us via the live help or on (877) 897-FIRE. Alternatively check out the online FAQ.

Have more questions? Submit a request

Comments