Sound Library

Overview

CallFire supports two kinds of sound files: .wav and .mp3 formats with a varied range of sampling rate frequency and bitrate. All .wav files must be at least 8000 hz, 16 bit (or more), and mono, and CallFire will attempt to convert sound files whose quality exceeds these specifications. The format for .mp3 files is unspecified, as CallFire will convert these file types to .wav. If sound file cannot be uploaded, you'll receive an appropriate error message.

Uploaded sound files can be used as voice messages in Voice or IVR broadcasts.

How to Add new Sounds

You can easily add new sounds via the API or the Developers' UI. There are four ways to add a sound to your library:

• Upload an Audio File
• Use Text to Speech
• Record via Phone
• Dial-in to Record (Developers' UI only)

Let's look at all the options in detail.

Upload an Audio File

To upload a new file on the Developers' UI, click on the appropriate icon and choose a sound file. To do this using the API, see the following code examples on how to upload sound.mp3 file using curl utility or Callfire SDK.

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

#!/usr/bin/env bash

curl -u username:password -X POST -F 'name=test image' -F 'file=@/sound.mp3' "https://api.callfire.com/v2/campaigns/sounds/files"

{
  "id": 63
}

import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.campaigns.model.CampaignSound;

import java.io.File;
import java.net.URISyntaxException;

class ApiClientSample {
    public static void main(String[] args) throws URISyntaxException {
        CallfireClient client = new CallfireClient("api_login", "api_password");
        File mp3File = new File(ApiClientSample.class.getClassLoader().getResource("sound1.mp3").toURI());
        CampaignSound mp3Sound = client.campaignSoundsApi().uploadAndGetSoundDetails(mp3File, "campaign sound");
    }
}

using CallfireApiClient;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        var mp3 = client.CampaignSoundsApi.Upload("sound1.mp3", "campaign sound");
    }
}

'strict'

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

client.ready(() => {
    client.campaigns.postFileCampaignSound({
      name: 'my-file',
      // for nodejs environment
      // file: fs.createReadStream('./myfile.wav')
      // for browser environment
      // file: new Blob([/* binary data */], {type: 'audio/wav'})
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);

from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.campaigns.postFileCampaignSound(
    name='campaign sound',
    file=open('sound1.mp3', 'rb')
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)

<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->postFileCampaignSound();
        $request->getOperationConfig()->setFileUpload(__dir__.'\sound1.mp3', 'campaign sound');
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}

ApiClientSample::main();

The API method is described on the documentation page

Text to Speech

The Text to Speech (TTS) engine allows you to convert text to a human voice. A number of different voices can be chosen. To add a new sound using the TTS feature, click on the 'Text to Speech' button on the UI, enter your message, and save. The API operation is shown below.

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

#!/usr/bin/env bash

curl -u "username:password" -H "Content-Type:application/json" -X POST -d '
    {
        "voice":"MALE1",
        "message":"This is a TTS sound"
    }' "https://api.callfire.com/v2/campaigns/sounds/tts"

{
  "id": 62
}

import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.campaigns.model.TextToSpeech;
import com.callfire.api.client.api.campaigns.model.Voice;
import com.callfire.api.client.api.common.model.ResourceId;

class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient callfireClient = new CallfireClient("api_login", "api_password");
        TextToSpeech tts = new TextToSpeech();
        tts.setVoice(Voice.MALE1);
        tts.setMessage("This is a TTS sound");
        ResourceId resourceId = callfireClient.campaignSoundsApi().createFromTts(tts);
    }
}

using CallfireApiClient;
using CallfireApiClient.Api.Campaigns.Model;
using CallfireApiClient.Api.Common.Model;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        var tts = new TextToSpeech
        {
            Message = "This is a TTS sound",
            Voice = Voice.MALE1
        };
        ResourceId resourceId = client.CampaignSoundsApi.CreateFromTts(tts);
    }
}

'strict'

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

client.ready(() => {
    client.campaigns.postTTSCampaignSound({
      body: {
        voice: 'MALE1',
        message: 'This is a TTS sound'
      }
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);

from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.campaigns.postTTSCampaignSound(
    body={
        'voice': 'MALE1',
        'message': 'This is a TTS sound'
    }
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)

<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->postTTSCampaignSound();
        $body = '{
                    "voice":"MALE1",
                    "message":"This is a TTS sound"
                 }';
        $request->getOperationConfig()->setBodyParameter($body);
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}

ApiClientSample::main();

The API method is described on the documentation page

Record via Phone

If you choose the 'Record via Phone' option, you will be prompted to enter your phone number. When you receive the call from CallFire, follow the prompts to record your message over the phone.

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

#!/usr/bin/env bash

curl -u "username:password" -H "Content-Type:application/json" -X POST -d '
    {
        "name":"Sound 1",
        "toNumber":"12135551122"
    }' "https://api.callfire.com/v2/campaigns/sounds/calls"

{
  "id": 61
}

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

class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient callfireClient = new CallfireClient("api_login", "api_password");
        CallCreateSound callCreateSound = new CallCreateSound();
        callCreateSound.setName("Sound 1");
        callCreateSound.setToNumber("12135551122");
        ResourceId resourceId = callfireClient.campaignSoundsApi().recordViaPhone(callCreateSound);
    }
}

using CallfireApiClient;
using CallfireApiClient.Api.Campaigns.Model;
using CallfireApiClient.Api.Common.Model;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        var callCreateSound = new CallCreateSound
        {
            Name = "Sound 1",
            ToNumber = "12135551122"
        };
        ResourceId resourceId = client.CampaignSoundsApi.RecordViaPhone(callCreateSound);
    }
}

'strict'

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

client.ready(() => {
    client.campaigns.postCallCampaignSound({
      body: {
        name: 'Sound 1',
        toNumber: '12135551122'
      }
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);

from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.campaigns.postCallCampaignSound(
    body={
        'name': 'Sound 1',
        'toNumber': '12135551122'
    }
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)

<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->postCallCampaignSound();
        $body = '{
                    "name":"Sound 1",
                    "toNumber":"12135551122"
                 }';
        $request->getOperationConfig()->setBodyParameter($body);
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}

ApiClientSample::main();

The API method is described on the documentation page

Dial-in to Record (Developers' UI only)

With the 'Dial-in to Record' option, you dial a toll-free or local number to record a message. Click on the 'Dial-in to Record' button on the UI to see the phone numbers and PIN codes for access.

Find and Delete Sounds in the Sound Library

Both the API and the Developers' UI allow you to search available sounds in the Library, fetch details about a particular sound, and remove sounds from your account. The following code samples show how to retrieve all available sounds.

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

#!/usr/bin/env bash

curl -u "username:password" -H "Content-Type:application/json" -X GET "https://api.callfire.com/v2/campaigns/sounds?filter=name&includeArchived=true&includePending=true&includeScrubbed=true&offset=0&limit=10&fileds=items(id,name,callback)"

{
  "items": [
    {
      "id": 60,
      "name": "TTS: And hello to you too.",
      "created": 1443333911000,
      "lengthInSeconds": 1,
      "status": "ACTIVE"
    },
    {
      "id": 59,
      "name": "TTS: Why hello there!",
      "created": 1443333905000,
      "lengthInSeconds": 1,
      "status": "ACTIVE"
    }
  ],
  "limit": 100,
  "offset": 0,
  "totalCount": 8
}

import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.campaigns.model.CampaignSound;
import com.callfire.api.client.api.campaigns.model.request.FindSoundsRequest;
import com.callfire.api.client.api.common.model.Page;

class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient callfireClient = new CallfireClient("api_login", "api_password");
        FindSoundsRequest request = FindSoundsRequest.create()
            .filter("name")
            .includeArchived(true)
            .includePending(true)
            .includeScrubbed(true)
            .offset(0L)
            .limit(10L)
            .fields("items(id,name,callback)")
            .build();
        Page<CampaignSound> campaignSounds = callfireClient.campaignSoundsApi().find(request);
    }
}

using CallfireApiClient;
using CallfireApiClient.Api.CallsTexts.Model.Request;
using CallfireApiClient.Api.Campaigns.Model;
using CallfireApiClient.Api.Common.Model;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        FindSoundsRequest request = new FindSoundsRequest
        {
            Filter = "name",
            IncludeArchived = true,
            IncludePending = true,
            IncludeScrubbed = true,
            Offset = 0,
            Limit = 10,
            Fields = "items(id,name,callback)"
        };
        Page<CampaignSound> campaignSounds = client.CampaignSoundsApi.Find(request);
    }
}

'strict'

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

client.ready(() => {
    client.campaigns.findCampaignSounds({
      // filter by sound name
      filter: 'name',
      // includes ARCHIVED sounds
      includeArchived: true,
      // includes UPLOAD/RECORDING
      includePending: true,
      // includes SCRUBBED sounds
      includeScrubbed: true,
      // search offset
      offset: 0,
      // return 10 items per request
      limit: 10,
      // return only specific fields
      fields: 'items(id,name,callback)'
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);

from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.campaigns.findCampaignSounds(
    # filter by sound name
    filter='name',
    # includes ARCHIVED sounds
    includeArchived=True,
    # includes UPLOAD/RECORDING
    includePending=True,
    # includes SCRUBBED sounds
    includeScrubbed=True,
    # search offset
    offset=0,
    # return 10 items per request
    limit=10,
    # return only specific fields
    fields='items(id,name,callback)'
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)

<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->findCampaignSounds();
        $request->getOperationConfig()->setQueryParameters(array("filter" => "name",
                                                                 "includeArchived" => true,
                                                                 "includePending" => true,
                                                                 "includeScrubbed" => true,
                                                                 "offset" => 0,
                                                                 "limit" => 10,
                                                                 "fields" => "items(id,name,callback)"));
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}

ApiClientSample::main();

The API method is described on the documentation page

Example of how to delete a sound from the Library:

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

#!/usr/bin/env bash

curl -u "username:password" -H "Content-Type:application/json" -X DELETE "https://api.callfire.com/v2/campaigns/sounds/11646003"

200 OK - No Response

'strict'

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

client.ready(() => {
    client.campaigns.deleteCampaignSound({id: 11646003})
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);

from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
client.campaigns.deleteCampaignSound(id=11646003).result()

<?php

class ApiClientSample {

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

ApiClientSample::main();

The API method is described on the documentation page

Download Sound API

Users have the ability to download a file hosted in the Sound Library. CallFire provides two API operations for .mp3 and .wav formats. The examples below show how to download an .mp3 version of sound file.

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

#!/usr/bin/env bash

curl -u "username:password" -H "Content-Type:application/json" -X GET "https://api.callfire.com/v2/campaigns/sounds/379506003.mp3"

mp3 binary file response

import com.callfire.api.client.CallfireClient;

import java.io.InputStream;

class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient callfireClient = new CallfireClient("api_login", "api_password");
        InputStream is = callfireClient.campaignSoundsApi().getMp3(379506003L);
    }
}

using System.IO;
using CallfireApiClient;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        Stream stream = client.CampaignSoundsApi.GetMp3(379506003);
    }
}

'strict'

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

client.ready(() => {
    client.campaigns.getCampaignSoundDataMp3({id: 379506003})
      .then((response) => {
        // returns binary response
        console.log(response.data);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);

from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.campaigns.getCampaignSoundDataMp3(id=379506003).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)

<?php

class ApiClientSample {

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

ApiClientSample::main();

The API method is described on the documentation page