CallFire Solutions

04. Configure a Phone Number On Your Account

Follow

This endpoint allows elements of a phone number’s configuration to be modified. After numbers have been added to your account, you can make changes to them. This includes the more basic features of enabling and disabling calling and messaging, to the more advanced features of setting up Call Tracking or an Interactive Voice Response (IVR).

Numbers can be changed based on one of 3 parameters, these are CallFeature, TextFeature, andInboundCallConfigurationType. More information about each of these is available below.

Endpoint

https://www.callfire.com/api/1.1/rest/number/:number

Request Type

PUT

Request Headers

Content-Type application/xml
Accepts application/xml

Returns

Depending on the configuration change requested, if successful, an XML payload may or may not be returned. Please check the respective sections to see if they do or do not return a payload, and if so, what it is.

Response

FieldTypeDescription
r:HttpStatus long The status code of the response.
r:Message string A human-readable description of the failure.

Core Request Arguments

These are the core request arguments available with the request. Other options are able to be supplied, depending on the configuration of these four.

OptionTypeDescription
Number string required - A E.164 compliant phone number, which follows the following format: [+][country code][subscriber number including area code]. A US example phone number is: +1 405 509 2773.
CallFeature string Allows for setting the calling options on the phone number (affecting inbound and outbound functionality).Available options: UNSUPPORTED,PENDING, ENABLED, DISABLED.
TextFeature string Allows for setting the texting options on the phone number. Available options: UNSUPPORTED, PENDING, ENABLED, DISABLED.
InboundCallConfigurationType string Enables the number to be setup as either with Call Tracking or as an Interactive Voice Response type. Available options are: TRACKING, IVR

CallFeature & TextFeature Request Arguments Explained

ArgumentDescription
UNSUPPORTED This is for numbers that don’t support SMS, eg., land lines
PENDING Means that a change to the numbers in progress
ENABLED Sets the number as enabled and able to accept calls and SMS’
DISABLED Sets the number as disabled, or not currently in service

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

Example Request

Curl

curl -i https://www.callfire.com/api/1.1/rest/number/12092084590 \
  -X PUT \
  -F "CallFeature=DISABLED;TextFeature=ENABLED" \
  -H "Accept: application/xml" \
  --user <YOUR_LOGIN>:<YOUR_PASSWORD>

PHP SDK

<?php

$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('DISABLED')  // enable calling
                ->setTextFeature('ENABLED');   // disable messages

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

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=DISABLED&TextFeature=ENABLED",
}
client, req := callfire.InitHttpClient(requestOptions)
resp, err := client.Do(req)

Example Responses

On Success

No XML payload is returned on success.

InboundCallConfigurationType Request Arguments

ArgumentDescription
TRACKING Enable Call Tracking
IVR Sets the number to be able to handle IVR or Interactive Voice Responses.

On Failure

Number Not 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>
Resource Error

This indicates an internal error. It does occur, but is not one which should be received often.

<?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>

Configuring Call Tracking

Call tracking helps a business market more effectively by being able to track the success of a phone number.

ArgumentTypeDescription
CallTrackingConfig[id] long This is only available via a GET for the number details
TransferNumber string required - 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
Example Request

Curl

curl -i https://www.callfire.com/api/1.1/rest/number/12092084590 \ 
  -X PUT \                                                                    
  -F TransferNumber=12092084589 \
  -F InboundCallConfigurationType=TRACKING \
  -F Screen=true \
  -F Record=false \
  -F IntroSoundId=779686003 \
  -F WhisperSoundId=779688003 \
  -H "Accept: application/xml" \
  --user <YOUR_LOGIN>:<YOUR_PASSWORD>

PHP SDK

<?php

$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);

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)
Example Response
On Success
HTTP/1.1 204 No Content
Content-Type: text/plain; charset=UTF-8
On Failure
HTTP/1.1 400 Bad Request
Content-Type: application/xml

<?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>sound 77968603 does not exist</r:Message>
</r:ResourceException>

Configuring Interactive Voice Responses (IVR)

Interactive voice response (IVR) is a technology that allows a computer to interact with humans through the use of voice and DTMF (Dual-tone multi-frequency signaling) tones input via keypad. IVRs can be used to set up such operations assurveys, polls, appointment reminders, payments, auto-attendant, and call routing. IVRs can be setup for both inbound and outbound uses.

ArgumentTypeDescription
IvrInboundConfig[id] long The ID in the database of that configuration. This is only available via a GET for the number details
DialplanXml file required - An XML string which provides the configuration for the IVR.
Example Request

Curl

curl -i https://www.callfire.com/api/1.1/rest/number/12092084590 \
  -X PUT \
  -F InboundCallConfigurationType=IVR \
  -F DialplanXml=@/tmp/simple-dialplan.xml \
  -H "Accept: application/xml" \
  --user <YOUR_LOGIN>:<YOUR_PASSWORD>

PHP SDK

<?php

// 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)

Example Responses

Malformed XML

If the DialplanXML is not well-formed, the request will fail. You’ll find specific details in the message element of the XML response, such 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>400</r:HttpStatus>
      <r:Message>
    invalid IVR: javax.xml.bind.UnmarshalException
     - with linked exception:
  [org.xml.sax.SAXParseException; lineNumber: 3; columnNumber: 18; The markup in the document following the root element must be well-formed.]</r:Message>
</r:ResourceException>

 

Have more questions? Submit a request

Comments