Call queues

Have you registered a callback URL to receive requests for your virtual number? Please click here.

Our gateway allows you to add incoming calls to a queue (with music being played in the background). You can then call a separate number to dequeue the calls one at a time.

Here is a sample response for enqueueing:

<Response>
  <Enqueue holdMusic="http://www.mymediaserver.com/audio/callWaiting.wav"/>
</Response>

Enqueue Attributes

The Enqueue element can take these attributes:
Attribute Description Required Default Value
holdMusic A valid URL that contains a link to the file to be played while the user is on hold. Note that we will cache the content after the first playback request, and will adhere to header information that indicates the need to re-download the file later on. No None
name You can put a call in a particular queue. eg. support, general, technical. This would help you dequeue it or know to the correct person. No None

Dequeueing is passing the calls enqueued to a separate number so that it can be handled eg by an agent. Here is a sample response for dequeueing:

<Response>
  <Dequeue phoneNumber="+254711082XXX"/>
</Response>

These actions together can be used to add call-center like abilities to your applications. All you need is two Africa's Talking phone numbers: One that enqueues incoming calls and one that members of your organization can call to dequeue

This is a terminal action if the call is picked. ie. No action will be executed after this if the call is picked.

Dequeue Attributes

The Dequeue element can take these attributes:
Attribute Description Required Default Value
phoneNumber The Phone number which users called to join the queue. Our gateway will check to see whether there is anyone in the queue that corresponds to that phone number and connect the two calls. If there is no one in the queue, the gateway just hangs up. Yes N/A
name This is the name of the queue you want to dequeue from. No N/A

Sample PHP Implementation

Assuming that you have configured the callback URL for your Africa's Talking Phone Number to point to callCenter.php. Below is an example of how you would handle an incoming call and add it to the queue that is associated with your Africa's Talking phone number, or connect two calls if the dialed number is for dequeuing calls.
<?php
// Save this code in callCenter.php. Configure the callback URL for BOTH phone numbers
// to point to the location of this script on the web
// e.g http://www.myawesomesite.com/callCenter.php

// Check to see whether this call is active
$isActive  = $_POST['isActive'];

if ($isActive == 1)  {
    // Check to see whether this is the enqueue or dequeue Africas Talking phone number    
    $destinationNumber =  $_POST['destinationNumber'];
    
    if ($destinationNumber == '+254711082XXX') {
        // Assuming this is the phone number you have advertised for people that want to
        // join the queue
       $response  = '<?xml version="1.0" encoding="UTF-8"?>';
       $response .= '<Response>';
       $response .= '<Enqueue url="http://www.mymediaserver.com/audio/callWaiting.wav"/>';
       $response .= '</Response>';
    } else {
       // This must be the phone number that people call to answer these calls. Dequeue
       // by specifying the phone number that adds people to the queue
       $response  = '<?xml version="1.0" encoding="UTF-8"?>';
       $response .= '<Response>';
       $response .= '<Dequeue phoneNumber="+254711082XXX"/>';
       $response .= '</Response>';
    }
         
      // Print the response onto the page so that our gateway can read it
      header('Content-type: text/plain');
      echo $response;

} else {
  
  // Read in call details (duration, cost). This flag is set once the call is completed.
  // In this example (enqueue and dequeue), this call will be made twice, when each caller
  // hangs up
  // Note that the gateway does not expect a properly formatted response

  $sessionId    = $_POST['sessionId']; 
  $duration     = $_POST['durationInSeconds'];
  $currencyCode = $_POST['currencyCode'];
  $amount       = $_POST['amount'];
  
  // You can then store this information in the database for your records

}