Connect a Call to a Second Person Using PHP

Overview

You may want to have an application dial out for someone, so that it calls them on their phone, then connects them to the number they want. This involves three tasks:

  1. Make an outbound call to a caller.
  2. When the call recipient answers the phone, place a new call to a different number (second user).
  3. Bridge the calls (first and second user) after the second user answers.

Common use cases for this practice include click to call, where a server application directs a call to a person who clicks on a web link, then connects them with a company representative.

This guide shows how to code connecting a user to second person on the Plivo platform, either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below.

You can create and deploy a PHLO to have an application call someone then connect them to a third party, and you can trigger the PHLO with a few lines of code.

Prerequisites

To get started, you need a Plivo account — sign up with your work email address if you don’t have one already. If this is your first time using Plivo APIs, follow our instructions to set up a PHP development environment and a web server and safely expose that server to the internet.

Create the PHLO

To create a PHLO, visit the PHLO page of the Plivo console. If this is your first PHLO, the PHLO page will be empty.

  • Click Create New PHLO.
  • In the Choose your use case pop-up, click Build my own. The PHLO canvas will appear with the Start node.
    Note: The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request.

  • Click the Start node to open the Configuration tab, and then enter the information to retrieve from the HTTP Request payload — in this case key names for the From and To numbers and the second user‘s number.

  • Validate the configuration by clicking Validate. Do the same for each node as you go along.

  • From the list of components on the left side, drag and drop the Initiate Call component onto the canvas. This adds an Initiate Call node onto the canvas. When a component is placed on the canvas it becomes a node.

  • Draw a line to connect the Start node’s API Request trigger state to the Initiate Call node.

  • In the Configuration tab of the Initiate Call node, give the node a name. To enter values for the From and To fields, enter two curly brackets to view all available variables, and choose the appropriate ones. The values for the numbers will be retrieved from the HTTP Request payload you defined in the Start node.

  • From the list of components on the left side, drag and drop the Play Audio component onto the canvas. Draw a line to connect the Answered trigger state of the Initiate Call node with the Play Audio node.

  • Configure the Play Audio node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane. Enter a static message — for example, “Please wait while we connect your call to the second number.”

  • From the list of components on the left side, drag and drop the Call Forward component onto the canvas.

  • Draw a line to connect the Prompt Completed trigger state of the Play Audio with the Call Forward node.

  • In the Configuration tab of the Call Forward node, give the node a name. To enter values for the From and To fields, enter two curly brackets to view all available variables, and choose the appropriate ones. The values for the numbers will be retrieved from the HTTP Request payload you defined in the Start node.

  • After you complete and validate the node configurations, give the PHLO a name by clicking in the upper left, then click Save.

Your complete PHLO should look like this:

Connect Second User

Your PHLO is now ready to test.

Trigger the PHLO

You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or, as we do here, define a dynamic payload by passing values through parameters when you trigger the PHLO from your application.

With dynamic payload

To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code to the PHLO when you trigger it.

With Dynamic Payload

Code

Create a file called TriggerPhlo.php and paste into it this code.

1
2
3
4
5
6
7
8
9
10
11
12
13

<?php
require 'vendor/autoload.php';
use Plivo\Resources\PHLO\PhloRestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new PhloRestClient("<auth_id>", "<auth_token>");

$phlo = $client->phlo->get("<phlo_id>");
try {
    $response = $phlo->run(["from" => "<caller_id>", "to" => "<destination_number>", "second_user" => "<second_number>"]);
    print_r($response);
} catch (PlivoRestException $ex) {
    print_r($ex);
}

Replace the auth placeholders with your authentication credentials from the Plivo console. Replace the phlo_id placeholder with your PHLO ID from the Plivo console. Replace the phone number placeholders with actual phone numbers in E.164 format (for example, +12025551234).

Test

Save the file and run it.

php TriggerPhlo.php
Note: If you’re using a Plivo Trial account, you can make calls only to phone numbers that have been verified with Plivo. You can verify (sandbox) a number by going to the console’s Phone Numbers > Sandbox Numbers page.

Here‘s how to connect a call to a second person using XML.

Prerequisites

To get started, you need a Plivo account — sign up with your work email address if you don’t have one already. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the Numbers page of the Plivo console, or by using the Numbers API. If this is your first time using Plivo APIs, follow our instructions to set up a PHP development environment and a web server and safely expose that server to the internet.

Create a Laravel controller to connect calls to a second person

Change to the project directory and run this command to create a Laravel controller for inbound calls.

$ php artisan make:controller VoiceController

This generates a controller named VoiceController in the app/http/controllers/ directory. Now, Edit app/http/controllers/voiceController.php and paste into it this code.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

<?php
namespace App\Http\Controllers;
require '../../vendor/autoload.php';
use Plivo\XML\Response;
use Plivo\RestClient;

class VoiceController extends Controller
{
    public function outboundCall()
    {
        $host = request()->getHttpHost();
        $client = new RestClient('<auth_id>','<auth_token>');
        $response = $client->calls->create(
            '<caller_id>',
            ['<destination_number>'],
            'https://'.$host.'/connect',);
        echo json_encode($response);
    }

    public function connect()
    {       
            $response = new Response();
            $response->addSpeak('Please wait while we connect your call');
            $dial = $response->addDial();
            $dial->addNumber('<second_number>');
            Header('Content-type: text/xml');
            echo ($response->toXML());
    }
}

Replace the auth placeholders with your authentication credentials from the Plivo console. Replace the phone number placeholders with actual phone numbers (for example, 12025551234).

Note: We recommend that you store your credentials in the auth_id and auth_token environment variables, to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch them from the environment variables. You can use $_ENV or putenv/getenv functions to store environment variables and fetch them when initializing the client.

Add a route

Add a route for the forward function in VoiceController. Edit the routes/web.php file and add these lines.

Route::match(['get','post'], '/outboundCall', 'App\Http\Controllers\VoiceController@outboundCall');
Route::match(['get','post'], '/connect', 'App\Http\Controllers\VoiceController@connect');

Start the Laravel server.

php artisan serve

You should see your basic server application in action at http://localhost:8000/outboundCall/.

Set up ngrok to expose your local server to the internet.

Test

Have your application make a call to a regular mobile phone. Plivo will send a request to your answer URL requesting a valid XML response and connect the call to a second user.

Note: If you are using a Plivo Trial account for this example, you can only make calls to phone numbers that have been verified with Plivo. Phone numbers can be verified at the Sandbox Numbers page.