Handle Action Requests

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

The following example adds a ConfirmAction button to an email about an expense report:

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "EmailMessage",
  "potentialAction": {
    "@type": "ConfirmAction",
    "name": "Approve Expense",
    "handler": {
      "@type": "HttpActionHandler",
      "url": "https://myexpenses.com/approve?expenseId=abc123"
    }
  },
  "description": "Approval request for John's $10.13 expense for office supplies"
}
</script>

<div itemscope itemtype="http://schema.org/EmailMessage">
  <div itemprop="potentialAction" itemscope itemtype="http://schema.org/ConfirmAction">
    <meta itemprop="name" content="Approve Expense"/>
    <div itemprop="handler" itemscope itemtype="http://schema.org/HttpActionHandler">
      <link itemprop="url" href="https://myexpenses.com/approve?expenseId=abc123"/>
    </div>
  </div>
  <meta itemprop="description" content="Approval request for John's $10.13 expense for office supplies"/>
</div>

When the user clicks on the button, an HTTP request will be issued from Google to your service, recording the confirmation. Your service receives the following HTTP request from Google:

POST /approve?expenseId=abc123 HTTP/1.1
Host: your-domain.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)

confirmed=Approved

The rest of this page describes what the service at https://your-domain.com/approve?expenseId=abc123 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://your-domain.com/approve?expenseId=abc123 is encouraged to check:

• Limited Use Access Token - To protect against replay attacks.
• User Agent - To make sure the request comes from Google.
• Bearer Token - To guarantee the request coming from Google is intended to the service.

The User Agent for all Action requests is Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions).

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 whose names correspond with the properties of Action. For example, ConfirmAction has the property confirmed.

Step 3: Return 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:

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

• Securing Actions