Dial

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

You can use this element to connect the user who called your phone number to an external phone number. For example, if you use your Africa's Talking phone number for customer service queries, you can forward calls received on that phone number with an actual phone line located in your office.

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

Here is a sample response:

<Response>
  <Dial phoneNumbers="+254711XXXYYY,+254733YYYZZZ,test@ke.sip.africastalking.com" ringbackTone="http://mymediafile.com/playme.mp3" record="true" sequential="true"/>
</Response>

Attributes

The Dial element can take these attributes:
Attribute Description Required Default Value
phoneNumbers A comma separated list of phone numbers (in international format) to call.
An AfricasTalking sip number can be include here.
Yes N/A
record Record the conversation (true or false). The URL for the recording will be sent to you once the call is complete. No false
sequential If more than one phone number is provided, this determines whether the phone numbers will be dialed one after the other, or whether they will all ring at the same time. If they ring at the same time, the first one to pick up wins. No N/A
callerId This contains your AfricasTalking number you want to dial out with. It is mainly important when the caller used a sip number. If not specified in this case, the default number will be used. The number called by the user will be used if its not specified for normal numbers No N/A
ringBackTone This contains a URL location of a media playback you would want the user to listen to when the call has been placed before its picked up. No N/A
maxDuration This contains the maximum amount of time in seconds a call should take. No N/A

Sample PHP Implementation

Assuming that you have configured the callback URL for your Africa's Talking Phone Number to point to customerService.php. Below is an example of how you would handle an incoming call and forward it to a list of customer service representatives, one after the other. The call is also recorded.
<?php
// Save this code in customerService.php. Configure the callback URL for your phone number
// to point to the location of this script on the web
// e.g http://www.myawesomesite.com/customerService.php

// First read in a couple of POST variables passed in with the request

// This is a unique ID generated for this call
$sessionId = $_POST['sessionId'];

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

if ($isActive == 1)  {  
  // Forward by dialing customer service numbers and record the conversation
  // Compose the response
  $response  = '<?xml version="1.0" encoding="UTF-8"?>';
  $response .= '<Response>';
  $response .= '<Dial record="true" sequential="true" phoneNumbers="+254711XXXYYY,+254733YYYZZZ,test@ke.sip.africastalking.com" ringbackTone="http://mymediafile.com/playme.mp3" />';
  $response .= '</Response>';
  
  // Print the response onto the page so that our gateway can read it
  header('Content-type: application/xml');
  echo $response;

} else {
  
  // Read in call details (duration, cost). This flag is set once the call is completed.
  // Note that the gateway does not expect a response in thie case
  
  $duration     = $_POST['durationInSeconds'];
  $currencyCode = $_POST['currencyCode'];
  $amount       = $_POST['amount'];

  // Be sure to read in the URL of the recorded conversation
  $recording    = $_POST['recordingUrl'];
  
  // You can then store this information in the database for your records

}