Play a Recording

👍

You're ready for this tutorial if you've got the following:

A FreeClimb account
A registered application
A configured FreeClimb Number
Your tools and language installed


Node.js

Using the FreeClimb SDK an asynchronous out dial request can be created. At minimum a request to create an out dial request requires a To, From and callConnectUrl. The From number is a number bought through FreeClimb and associated with your account. The To number is any phone number (not provided in this example). Successful invocation of the create method indicates the asynchronous out dial request has successfully been queued. All subsequent updates for the request will be directed to the URLs provided.

Create your package.json file and save in the root directory of your project:

{
  "name": "node-play-a-recording-tutorial",
  "version": "1.0.0",
  "dependencies": {
    "@freeclimb/sdk": "^1.0.0",
    "body-parser": "^1.19.0",
    "dotenv": "^8.1.0",
    "express": "^4.17.1"
  }
}

Install the package by running the following in the command line/terminal:

yarn install

Example code:

// Imports and setup
require('dotenv').config()
const express = require('express')
const bodyParser = require('body-parser')
const freeclimbSDK = require('@freeclimb/sdk')

const app = express()
app.use(bodyParser.json())
// Where your app is hosted ex. www.myapp.com
const port = process.env.PORT || 80
// your freeclimb API credentials (available in the Dashboard) - be sure to set up environment variables to store these values
const accountId = process.env.ACCOUNT_ID
const apiKey = process.env.API_KEY
const freeclimb = freeclimbSDK(accountId, apiKey)
const applicationId = process.env.APPLICATION_ID
// Invoke create method to initiate the asynchronous outdial request
freeclimb.api.calls.create(to, from, applicationId).catch(err => {/* Handle Errors */ })

The callConnectUrl provided in the App config will be the recipient of FreeClimb requests for additional actions upon call answer. The additional PerCL actions are contained in the context of the response. In this sample the Play PerCL action is utilized.

// Handles incoming calls. Set with 'Call Connect URL' in App Config
app.post('/incomingCall', (req, res) => {
  const play = freeclimb.percl.play(recordingUrl)
  const percl = freeclimb.percl.build(play)
  res.status(200).json(percl)
})

Handle status updates:

// Specify this route with 'Status Callback URL' in App Config
app.post('/status', (req, res) => {
  // handle status changes
  res.status(200)
})

Start the server:

app.listen(port, () => {
  console.log(`Started server on port ${port}`)
})

C#

To initiate any interaction with FreeClimb a FreeClimbClient object must be created. Using the CallsRequester created upon successful creation of the FreeClimbClient an asynchronous out dial request can be created. At minimum a request to create an out dial request requires a To, From and applicationId. Successful invocation of the create method indicates the asynchronous out dial request has successfully been queued. All subsequent updates for the request will be directed to the URLs of the provided application.

Given the asynchronous nature of the FreeClimb out dial request the sample retains the request recording identifier in a global object until the out dial call has been successfully answered.

Example code:

try {
    // Create the FreeClimbClient
    // Your account ID & api key can be found under API credentials on the FreeClimb Dashboard
    FreeClimbClient client = new FreeClimbClient(accountId, apiKey);
    // Create a Call
    Call call = client.getCallsRequester.create(phoneNumber, // To
                                                freeClimbPhoneNumber, // From,
                                                applicationId); // Application to Handle the call
} catch(FreeClimbException ex) {
    System.Console.Write(ex.Message);
}

The callConnectUrl of the provided application in the original create request will be the recipient of FreeClimb request for additional actions upon call answer. The additional PerCL actions are contained in the context of the response. In this sample the Play PerCL action is utilized.

Example code:

public ActionResult PlayRecordingCallAnswered (CallStatusCallback callStatusCallback) {
  // Create an empty PerCL script container
  PerCLScript script = new PerCLScript ();
  // Verify call is in the InProgress state
  if (callStatusCallback.getDialCallStatus == ECallStatus.InProgress) {
    // Create PerCL play script with US English as the language
    Play play = new Play (GetRecordingUrl ());

    // Add PerCL play script to PerCL container
    script.Add (play);
  }

  // Convert PerCL container to JSON and append to response
  return Content (script.toJson (), "application/json");
}

Successful completion of the Play PerCL action will result in the call being terminated. Upon termination of the call the statusCallbackUrl of the application provided in the initial asynchronous out dial receives a FreeClimb request and an empty response is provided.

Example code:

public ActionResult PlayRecordingCallStatus (CallStatusCallback callStatusCallback) {
  // Create an empty PerCL script container
  PerCLScript script = new PerCLScript ();
  return Content (script.toJson (), "application/json");
}