Phweet Developer
 
Search this site

Navigation

Recent site activity

Phweet API Introduction

Phweet exposes functionality to enable Twitter clients to easily support Phweet telephony via an Application Programming Interface (API). This document is a reference for that functionality, and aims to serve as a reference for developers building tools that talk to Phweet.

Smart Links are the new way to talk. Phweet enables voice conversations through unique hyperlinks which expire when the session ends. It is a completely new form of telephony. A Phweet is a link to an external directory listing (like Twitter).  Phweets simply enables voice conversations between two or more profiles without sharing any additional information between the parties.  Today, Phweet exclusively supports Twitter although in the future, Phweet will support other such networks.

Quick Summary

Adding voice telephony functionality to a Twitter client is made simple with the Phweet API. The API is used to create a Phweet URL which is a meeting place for participants to conduct voice communications. The client then sends the user to that URL like any other URL. This should be familiar to Twitter client developers, somewhat analogous to TinyURL type services.

There are two options for developers to create the URL and setup the Phweet. There is a one-step approach and a two-step approach. In both cases, the goal is to instruct Phweet to setup a Phweet URL which consists of a "host" (caller) and a "recipient" twitter account, as well as a context for the request (what the conversations is about).

The one-step process is essentially:
  1. User clicks Phweet button (somewhat similar to a Direct message button)
  2. User enters (or selects) recipient username, provides a brief "context" for the call and selects whether the Phweet is private (direct) or not
  3. Twitter client invokes the phweeturl.xml API service to generate a Phweet URL
  4. Twitter client opens user's browser into that URL
At step 3 above, Phweet generates a Phweet-formatted status update (tweet) on behalf of the user. As can be seen above, this (hopefully) requires very little additional coding for the Twitter client and uses a model similar to services and functions already performed by Twitter clients (such as shortening URLs through services like tinyurl.com)

The two-step process is similar, but breaks the process down into two phases, first generating the Phweet URL, then initiating it fully with "context" (essentially the "body" of the tweet that gets sent by Phweet), as follows:

  1. User clicks a Phweet button
  2. User enters (or selects) recipient username choses whether the Phweet is private (direct) or not
  3. Twitter client invokes the phweeturl.xml API service to generate a Phweet URL
  4. User supplies the context for the call (body of tweet)
  5. Twitter client invokes the start.xml API service to activate the Phweet URL
  6. Twitter client opens user's browser into that URL
In step 4 above, Phweet sends a Phweet-formatted status update (tweet) on behalf of the user. The Twitter client should not send a status update, but should see one coming in, similar to if the user entered a status update from a second client or via the web.

Reference

Methods

phweeturl.xml

Starts a new Phweet and generates a corresponding Phweet URL. The Phweet URL is returned.

URL: http://phweet.com/api/phweeturl.xml

Parameters:
  • from. Required. Screen name of the user initiating the Phweet (aka the "host")
  • pw. Required. Password for the above account
  • to. Required. Screen name of the user to be sent the Phweet (aka the "recipient")
  • context. Optional. Context for the Phweet (what the conversation is about).
  • pvt. Optional. Set to 1 if this Phweet is private (direct messages will be used). Default is public (@ messages).
  • debug. Optional. If set, then public tweets are not sent.

Notes:

Requires HTTP POST request.

If the context parameter is not provided, then the URL is created but it is not activated. The start.xml API below has to be used to finalized the instantiation of the Phweet URL in that case. 

The oneclick value may be used by the Twitter client to deliver the user directly to the Phweet URL, without requiring further sign-in. This URL should not be exposed directly to the user or in the Twitter stream - it for use by the client to send the user to the Phweet URL in the browser. This value is only returned if the context is provided, resulting in a live/active Phweet.  The oneclick URL is only valid from the same IP address of the Twitter client making the API service call and is only active for 60 seconds.

Example response:


<?xml version="1.0" encoding="UTF-8"?>
<phweet>
  <phweeturl>http://phweet.com/5xRy</phweeturl>
  <oneclick>http://phweet.com/oneclick.cgi?sid=A16211C0497B8998435791A615032F6E</oneclick>
</phweet>

start.xml

Creates a Phweet URL. The Phweet URL is returned.

URL: http://phweet.com/api/start.xml

Parameters:
  • from. Required. Screen name of the user initiating the Phweet (aka the "host")
  • pw. Required. Password for the above account
  • id. Required. The Phweet URL id obtained from phweeturl.xml (tail of URL, e.g. 5xRy)
  • context. Required. Context for the Phweet (what the conversation is about).
  • pvt. Optional. Set to 1 if this Phweet is private (direct messages will be used). Default is public (@ messages).
  • debug. Optional. If set, then public tweets are not sent.

Notes:

Requires HTTP POST request.

Example response:


<?xml version="1.0" encoding="UTF-8"?>
<phweet>
  <phweeturl>http://phweet.com/5xRy</phweeturl>
  <oneclick>http://phweet.com/oneclick.cgi?sid=A16211C0497B8998435791A615032F6E</oneclick>
</phweet>

phweetup.xml

Creates a new "undirected" Phweet and generates a corresponding Phweet URL. The Phweet URL is returned.

URL: http://phweet.com/api/phweetup.xml

Parameters:
  • from. Required. Screen name of the user initiating the Phweet (aka the "host")
  • pw. Required. Password for the above account
  • context. Required. Context for the Phweet (what the conversation is about).
  • aa. Optional. If set to 1, visitors to this Phweet URL are automatically accepted. Default is normal host acceptance controls.
  • debug. Optional. If set, then public tweets are not sent.

Notes:

Requires HTTP POST request.

Phweets are normally directed to a specific individual, the recipient, and the Phweet live exchange does not begin until the recipient accepts the request. The phweetup.xml service creates a slightly different kind of Phweet exchange. An "undirected" Phweet is one that is not sent to any one in particular. It is created and immediately made active to others to join. It stays active until the host (creator of the Phweet) ends it.  However, unlike normal (directed) Phweets, the "undirected" Phweet URL stays active if the host leaves (but does not "end") the Phweet URL. Participants may use the URL and continue their conversation even if the host is not present. All "undirected" phweets are "public" - that is to say they do not use "d" messages.

Undirected Phweets can be started in "auto-accept" mode with the above "aa" parameter, where any visitor to the URL is "auto-approved" and immediately joins the Phweet. The host can still "kick" them out. Otherwise, normal request/approve controls are in place, where the host must approve (once) those users that want to join, the same way it works for normal Phweets. Hosts can also "invite" specific users to join, which essentially pre-approves those specific users.

Example response:


<?xml version="1.0" encoding="UTF-8"?>
<phweet>
  <phweeturl>http://phweet.com/olVQ</phweeturl>
  <oneclick>http://phweet.com/oneclick.cgi?sid=A16211C0497B8998435791A615032F6E</oneclick>
</phweet>

Curl Example

If your system has curl (and it should!), you’ve already got a great way to test the Phweet API. Here is an example:

  • Initiate a Phweet and get the URL for it: curl -d "from=yourscreenname&pw=yourpassword&to=theirscreename&context=help+me+make+spaghetti" http://phweet.com/api/phweeturl.xml

Discussion Group


Join the Phweet Development Talk Google Group. Join the group, get help from Phweet and the developer community and help define the Phweet API.