Super Quick Start
From Telephone Developer Documentation
Contents |
Overview
This tutorial shows you how to get two users (John and Mike)
on a random multi-user web application talking using our API library.
Specifically, how to:
- get an API key , secret and application name (App Name)
- install and configure the API PHP library used to voice-enable your Web Application
- add a launch and a call button on John's (and Mike's) user browsing pages
- launch Mike and John's Telephone's to automatically register and add each other as friends in their phonebook so they can start talking and IM-ing
- we wrap it up with a summary of what you have to do to get your users engaged using our API
Get your key, secret and choose an App Name
- go to the Developer's website, click on Register Now and follow the steps. You must choose an App Name. Make sure it's only made up of alphanumerics ([A-Za-z0-9]+) . Example: mywebsite123
- take note of these three values because you'll need them next!
Installation and configuration
- Download and unpack the demo files in your web directory (this demo assumes you don't move the files into separate directories)
- Here are the files and a brief description of each (see the diagram)
- john.php and mike.php - represents two different users looking at each others list of friends (one for simplicity) on two separate web pages
- controller.php - is a simple script that handles Telephone launch requests from each browser and uses API methods from the babytel_api class (explained next)
- babytel_api.php - Contains a number of API methods to:
- create a new user (register a user with Babytel's Telephone)
- add a friend to that user (so that the friend shows up in the user's phonebook)
- launch the phone on behalf of that user
- place a call from the user to friend
- OAuth.php - Library used by babytel_api.php to authenticate with the TelephoneAPI server
- deleteUsers.php - Run this script to delete John and Mike from the system (useful to repeat the demo from scratch)
- babytel_api.js - Not included in the files but must be referenced in john.php and mike.php since it facilitates launching of Telephone through AJAX calls whenever the LAUNCH or CALL button is clicked on
- In both john.php and mike.php, change the 'consumer_portal_url' to the URL that points to wherever you placed controller.php (e.g. http://www.example.com/controller.php)
- In controller.php, go to the end of the file and replace the following strings with the developer key, secret, and app name you recorded when you registered.
- <developer_key_here>
- <developer_secret_here>
- <developer_app_name_here>
Registering John and Mike with Babytel's Telephone
- Before John and Mike can talk, they have to:
- be registered with Telephone (an account has to be generated on the TelephoneAPI server)
- they have to each be added as a friend on the Telephone system
To register:
- John has to start his phone by clicking on the Launch button on the page
a close look at john.php shows that the launch button looks like the following.:
<img src="images/launch.jpg"
class="bbt_element"
data-bbt_op="launch"
data-bbt_user_id="u111212"
data-bbt_new_user="1"
/>
The main difference between John and Mike's view is the value of data-bbt_user_id, which is John's Native User Id. That value gets pushed by our Javascript to the controller.php after John clicks on the button (see diagram above).
- a close look at controller.php shows a method preTelephoneLaunch() that takes the Native User Id and (for brevity) assumes we already have that user's first name, last name, etc. in preparation for registration:
if ($user_id == 'u111212') {
$user['username'] = "jono";
$user['first_name'] = "John";
$user['last_name'] = "Doe";
$user['email'] = "john@dot.com"; // this is optional
}
$user['user_id'] = $user_id; // the user's internal user id
$user['timezone'] = "America/New_York";
- that data is fed to our API in order to create the user on Telephone's server:
$result = $this->userCreate($user);
To add a friend relationship on Telephone system:
- after registration, API calls are made in babytel_api.php to see if Mike (u111213) is already registered too. And if he is, we add him as a friend
if ($user_id == 'u111212') {
if ( $this->userExists('u111213') && !$this->isFriend('u111212', 'u111213') ) {
$this->friendCreate('u111212', 'u111213');
}
}
- finally, Telephone is launched-- preloaded with any friends who might have registered
NOTE: For the purposes of the demo, Mike has to also launch the phone to register in this way. In our scenario, as soon as Mike is registered behind the scenes, each of them will appear on the other's phonebook in an "on-line" state---allowing them to start talking.
John calling Mike from the Call Button
A user can also leave a message or call by clicking on the Call button below their profile:
<img src="images/callme.jpg"
class="bbt_element"
data-bbt_op="call"
data-bbt_from="u111212"
data-bbt_to="u111213"
data-bbt_new_user="1"
/>
Notice the data-bbt_from and data-bbt_to attributes. A similar path is followed in controller.php:
public function preTelephoneCall($user_id, $target_id) {
...
return true;
}
NOTE: in the demo we don't do validation of the user or the relationship between a caller and the recipient. In a live system, you would use preTelephoneCall() and preTelephoneLaunch() to do that validation.
How to Extend this solution to Your Multi-user site
The key to integrating Telephone on your system lies in:
- the launch button you would place somewhere on your navigation header
- the call button placed next to each displayed user on your system
- placing the code in controller.php wherever it makes sense on your system. You don't need to use the same name or even a script with an extension of .php . So long as your consumer_portal_url points to a URL that will run the same AJAX-handling logic, it will work.
- Also, the code in controller.php is simplified for the Demo. Obviously you don't need to make the user launch the phone to register. You could auto-register your users upon their regular login. Simply instantiate babytel_api and call the userCreate() method.
- security must be maintained. All interacts between your user's browser and the logic in controller.php should take place in the context of the same authentication scheme you use when your logged in users move around your site. So controller.php logic has to stay in the same domain as your web application.
More to come!
