Handle Action Requests

As described in Declaring Actions, when a user interacts with an Inline Actions, Google sends an HTTP request to a URL declared in the action.

For example, imagine a company called events-organizer.com, which deals with Birthday Party invites. They send event invitations over email, and declare an Event with an inline RSVP Action within the email using the following markup:

JSON-LD

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Event",
  "name": "John's Birthday Party",
  ... information about the event ...
  "potentialAction": {
    "@type": "RsvpAction",
    "actionHandler": {
      "@type": "HttpActionHandler",
      "url": "https://events-organizer.com/rsvp?eventId=123",
      "method": "POST",
      "requiredProperty": "rsvpStatus",
    }
  }
}
</script>

Microdata

<div itemscope itemtype="http://schema.org/Event">
  <meta itemprop="name" content="John's Birthday Party"/>
  ... information about the event ...
  <div itemprop="potentialAction" itemscope itemtype="http://schema.org/RsvpAction">
    <div itemprop="actionHandler" itemscope itemtype="http://schema.org/HttpActionHandler">
      <meta itemprop="url" content="https://events-organizer.com/rsvp?eventId=123"/>
      <link itemprop="method" href="http://schema.org/HttpRequestMethod/POST"/>
      <div itemprop="requiredProperty" itemscope itemtype="http://schema.org/Property">
        <meta itemprop="name" content="rsvpStatus"/>
      </div>
    </div>
  </div>
</div>

Once the inline Action is completed by the user, events-organizer.com receives the following HTTP request from Google:

POST /rsvp?eventId=123 HTTP/1.1
Host: events-organizer.com
Authorization: Bearer AbCdEf123456
Content-Type: application/x-www-form-urlencoded
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions)

rsvpStatus=YES

The rest of this page describes what the service at https://events-organizer.com/rsvp?eventId=123 needs to do to handle the action properly. This includes:

  • Verifying the Request
  • Processing the payload
  • Returning a response code

Step 1: Verify the Request

The service at https://events-organizer.com/rsvp?eventId=123 is encouraged to check:

If all checks pass, the service can proceed to the next step.

Step 2: Process the Action

The service should process the action as specified in the URL parameters as well as additional information collected from the user.

Additional information from the user resides in the request's body, and is encoded using the x-www-form-urlecoded encoding. The information is set in properties who's names correspond with the properties of Action. For example, RsvpAction has the properties rsvpStatus and comment.

Returning a Response Code

Once the service processed and recorded the action successfully, it should return a response code 200 (OK). The following response codes can be used in error situations:

Response Code Treatment
400 (Bad Request) Google will fail the action.
401 (Unauthorized) Google will fail the action.
404 (Not Found) Google will fail the action.
408 (Request Timeout) Google will retry again later.

In case of permanent failure, Google will tell the user that action has failed and that the user should follow alternative instructions inside the email.

Further Reading

Send feedback about...

Email Markup
Email Markup
Need help? Visit our support page.