Welcome to Nexmo Developer

We are improving our Documentation, API references, learning resources & tooling to help you more effectively use our services. We want to help you find everything you need to integrate Nexmo APIs into your code.

As we start this transition, we’d love to hear from you with thoughts & suggestions. If you’ve got something, positive or negative, to tell us, please tell us using the feedback tool at the bottom of each guide or file an issue on GitHub. - Nexmo

Create conferences

A Conversation is the collection of one or more inbound calls to the virtual number associated to your Voice app. A named Conversation is a conference. The conversation NCCO is used to create a standard or moderated conference for the callers. A standard conference starts when the first caller calls in and ends when the last caller hangs up. A moderated conference starts and ends when the moderator calls in and hangs up. Before a moderated conference starts, you can send an audio stream to the waiting participants. When a conference starts, all audio from all inbound calls is mixed into it. You can record standard and moderated conferences.

The workflow for a conference is:

conference workflow

  1. Your users call the virtual number associated with your app.
  2. Nexmo retrieves an NCCO from your answer_url webhook endpoint.
  3. Nexmo follows the actions in your NCCO.
  4. Nexmo sends status information to your webhook endpoint at event_url.

To create a conference with the Voice API:

  1. Create a Nexmo application. Set answer_url to the URL of server that provides your NCCOs.
  2. Create the NCCOs for the business logic you are implementing in your Voice app:

    [
      {
        "action": "conversation",
        "name": "nexmo-conference-standard",
        "record": "true"
      }
    ]
    

  3. Create the webhook that provides the NCCO for your conference. The following code examples use the request parameters sent to answer_url to deliver one NCCO to the moderator and another to all other attendees:

    <?php
    
    $method = $_SERVER['REQUEST_METHOD'];
    $request = array_merge($_GET, $_POST);
    
    switch ($method) {
      case 'GET':
    
        //Retrieve with the parameters in this request
        $to = $request['to']; //The endpoint being called
        $from = $request['from']; //The endpoint you are calling from
        $uuid = $request['uuid']; //The unique ID for this Conversation
    
        //Send the header
        header('Content-Type: application/json');
    
        //For more advanced Conversations you use the paramaters to personalize the NCCO
        //Dynamically create the NCCO to run a moderated conversation from your virtual number
        if( $from == "441632960960")
          $ncco='[
                  {
                    "action": "conversation",
                    "name": "nexmo-conference-moderated",
                    "endOnExit": "true",
                    "record": "true"
                  }
                 ]';
        else
          $ncco='[
            {
              "action": "talk",
              "text": "Welcome to a Nexmo moderated conference",
              "voiceName": "Amy"
            },
            {
              "action": "conversation",
              "name": "nexmo-conference-moderated",
              "startOnEnter": "false",
              "musicOnHoldUrl": ["https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3"]
            }
          ]';
    
        echo $ncco;
        break;
      default:
        //Handle your errors
        handle_error($request);
        break;
    }
    

  4. Handle the call state changes at event_url. If you record your Conversations, the download URL for the mp3 recording is sent to this webhook endpoint when status is complete. The following code examples show you how to handle changes in Conversation state:

    <?php
    /*
     *  Place this script at event_url for your Nexmo application
     */
    $method = $_SERVER['REQUEST_METHOD'];
    // work with get or post
    $request = array_merge($_GET, $_POST);
    
    /*
     *  Do something for changed call status
    */
    function handle_call_status()
    {
      $decoded_request = json_decode(file_get_contents('php://input'), true);
      // Work with the call status
      if (isset($decoded_request['status'])) {
        switch ($decoded_request['status']) {
          case 'ringing':
              echo("Handle conversation_uuid, this return parameter identifies the Conversation");
              break;
          case 'answered':
              echo("You use the uuid returned here for all API requests on individual calls");
              break;
          case 'complete':
              //if you set eventUrl in your NCCO. The recording download URL
              //is returned in recording_url. It has the following format
              //https://api.nexmo.com/media/download?id=52343cf0-342c-45b3-a23b-ca6ccfe234b0
              //Make a GET request to this URL using a JWT as authentication to download
              //the Recording. For more information, see Recordings.
              break;
          default:
              break;
      }
          return;
      }
    }
    
    /*
     *  Handle errors
    */
    function handle_error($request){
         //code to handle your errors
    }
    
    /*
      Send the 200 OK to Nexmo and handle changes to the call
    */
    switch ($method) {
      case 'POST':
        //Retrieve your dynamically generated NCCO.
        $ncco = handle_call_status();
        header("HTTP/1.1 200 OK");
        break;
      default:
        //Handle your errors
        handle_error($request);
        break;
    }
    

    To inspect and debug state changes without writing your own server, create an online endpoint service such as requestb.in  or https://hookbin.com/  .

  5. Your conference starts when somebody calls the virtual number associated with the application.

Note: to dial somebody into the conference, make an outbound call to your user and set answer_url to the webhook endpoint providing the conference NCCO.

The maximum allowable calls is 50. Conversations can also be moderated and recorded.