Connect two users

As well as sending voice messages and receiving incoming calls, with the Voice API you can connect two users in a call. For example, to schedule a call between a customer and your sales team.

In this section you see how you can make a scheduled call to two users with Nexmo APIs:

  • Prerequisites - setup the Nexmo Application dedicated to this workflow
  • Connect your users - make an API request to call one user and provision the NCCO to call the other

Prerequisites

To follow the steps in this section you need:

Connect your users

To connect two users in a voice call, your app uses Voice API to initiate the Call. Nexmo places the call to your customer and follows the actions in your NCCO. The connect action in your NCCO calls your sales team so both are in communication.

Participant answer_url Participant Nexmo Participant App Participant Customer Participant Sales team Customer-> App: press "Call Sales" App->Nexmo: POST Call Nexmo->Customer: Initiate Call leg Nexmo->answer_url: Send Call info answer_url->Nexmo: Return NCCO with connect\n info for Sales team Nexmo->Sales team: Initiate Call leg Customer->Sales team: Hi. Sales team->Customer: Hi.
  1. When your Customer presses the Call button, your App makes an authenticated request to POST https://api.nexmo.com/v1/calls and initiates the first leg of the Call:

    <?php
    
    include 'application_generate_jwt.php';
    
    //Connection information
    $base_url = 'https://api.nexmo.com' ;
    $version = '/v1';
    $action = '/calls';
    
    //User and application information
    $application_id = "id-for-your-voice-application";
    
    //Mint your JWT
    $keyfile="application_secret_key.txt";
    
    $jwt = generate_jwt($application_id, $keyfile);
    
    //Add the JWT to the request headers
    $headers =  array('Content-Type: application/json', "Authorization: Bearer " . $jwt ) ;
    
    //Change the to parameter to the number you want to call
    $payload = '{
        "to":[{
            "type": "phone",
            "number": "441632960961"
        }],
        "from": {
            "type": "phone",
            "number": "441632960977"
        },
        "answer_url": ["https://www.example.com/call_sales.json"]
    }';
    
    //Create the request
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $base_url . $version . $action);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    
    $response = curl_exec($ch);
    
    echo $response;
    

  2. Your webhook endpoint at answer_url receives the Call info and returns the call_sales.json NCCO with the connect action to call your sales representative:

    [
      {
        "action": "talk",
        "text": "Please wait while we connect you"
      },
      {
        "action": "connect",
        "eventUrl": ["https://example.com/events","https://example.com/backup"],
        "timeout": "45",
        "from": "447700900007",
         "endpoint": [
          {
            "type": "phone",
            "number": "447700900000"
          }
        ]
      }
    ]
    

    Ensure that answer_url for your Application is pointing to the webhook endpoint providing your NCCO. If not, use the Nexmo CLI or Application API to update answer_url.

  3. Nexmo initiates the second leg of the Call and your users are connected in a Voice call.

And that is it. You have connected two of your users with a single Call.