Notifications.sendRequest

From Facebook Developers Wiki

Jump to: navigation, search
⚠

Please note that this method was disabled on October 19, 2007, and is no longer available for use.

To send requests or invitations to users, use fb:request-form instead.

Send a request or invitation to a set of users. You can send requests to users that have added the application without any confirmation, or you can direct a user of your application to the URL returned by this function to send requests to users who have not yet added your application.

Contents

[edit] Parameters

Type Name Required Description
string api_key ✔ The application key associated with the calling application.
string session_key ✔ The session key of the logged in user.
float call_id ✔ The request's sequence number. Each successive call for any session must use a sequence number greater than the last. We suggest using the current time in milliseconds, such as PHP's microtime(true) function.
string sig ✔ An MD5 hash of the current request and your secret key, as described in the authentication guide.
string v ✔ This must be set to 1.0 to use this version of the API.
string format Desired response format. Either XML (default) or JSON.
string callback Name of a function to call. This is primarily to enable cross-domain JavaScript requests using the <script> tag, also known as JSONP, and works with both the XML and JSON formats. The function will be called with the response passed as the parameter.
array to_ids ✔ Comma-separated list of recipient ids. These must be friends of the logged-in user or people who have added your application.
string type ✔ The type of request/invitation - e.g. the word "event" in "1 event invitation."
string content ✔ Content of the request/invitation. This should be FBML containing only links and the special tag fb:req-choice to specify the buttons to be included in the request.
string image ✔ URL of an image to show beside the request. It will be resized to be 100 pixels wide. Note: this URL cannot be hosted on *.facebook.com.
bool invite ✔ Whether to call this an "invitation" (true) or a "request" (false).

[edit] Example return XML

<?xml version="1.0" encoding="UTF-8"?>
<notifications_sendRequest_response xmlns="http://api.facebook.com/1.0/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://api.facebook.com/1.0/ http://api.facebook.com/1.0/facebook.xsd">
    http://www.facebook.com/send_req.php?from=211031&id=6
</notifications_sendRequest_response>

[edit] Response

If a URL is returned, redirect the user to that URL to confirm sending of the request. If no URL is returned, either an error occurred or the request went through without requiring confirmation. We will eventually support some additional error codes for the error case.

[edit] Error codes

Code Description
1 An unknown error occurred. Please resubmit the request.
2 The service is not available at this time.
4 The application has reached the maximum number of requests allowed. More requests are allowed once the time window has completed.
5 The request came from a remote address not allowed by this application.
101 The api key submitted is not associated with any known application.
102 The session key was improperly submitted or has reached its timeout. Direct the user to log in again to obtain another key.
103 The submitted call_id was not greater than the previous call_id for this session.
104 Incorrect signature.

[edit] Usage

Each user can send up to 10 invitations per day.

[edit] Sample code

This will generate the standard confirmation page, allowing your users to invite their friends to use your app or whatever other useful things you can think of.

Note: replace things bolded and in brackets with whatever it should be.

// who is it going to? this can be a friend ID or a friend array
$to = [Friend/Friend Array];

// title of request/invitation, will say "1 [$title] invitation/request
$title = "[App Name]!";

// content of the message. Also include the accept button.
$content = "<fb:req-choice url=\"[target URL]\" label=\"[Button Label]\" />Come use [App Name] - it's the coolest thing since sliced bread. ";

// type of notification - either 'invitation' or 'request'
$request = [invitation/request];


// image to be displayed on the left side of your invitation, will be resized to 100x100, so shoot for this size
$image = "slicedbread.png";


// generate the message and return confirmation page
$confirmURL = $facebook->api_client->notifications_sendRequest($to, $title, $content, $image, $request);


// redirect to confirmation page
$facebook->redirect($confirmURL);

Also check out the example code of a fully implemented invite page in PHP.

Facebook will redirect the user back to the application's callback URL after displaying the confirmation dialog. By appending the &next=my-redirect string to the $confirmURL you can make it visit some other place within your callback namespace. This can, for instance, be used to redirect the user back to a proper canvas page.

Appending &canvas to the redirect url does the same, sends it automatically back to your canvas page. A code like this will do the trick: 

$confirmURL = $confirmURL."&canvas";

If doing this in a language in PHP, just make sure that you send the user to a processing page that will execute this API call. You will then be returned with one of the following:
- a URL to redirect the user to the confirmation page. Use <fb:redirect url="'''[URL returned]'''&canvas" /> to do the redirect and this will bring you back to your canvas page with &sent=1 as a URL param
- it will just send it (as it doesn't need a confirmation
- you will get an error, so do some error catching.

[edit] Bugs

  • There is no way to distinguish between a request that successfully went through without confirmation and a request that failed due to the daily limit.[possible bug?]
  • There should be a way to test to see how many invites a user has left for the time period.
  • The invite flag in the API DOES NOT WORK, instead use request = invitation / request
Retrieved from "http://wiki.developers.facebook.com/index.php/Notifications.sendRequest"
Navigation