Handle action requests

As described in Declare 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:

JSON-LD

<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>

Microdata

<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 the button, Google sends an HTTP request 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

We recommend that the service at https://your-domain.com/approve?expenseId=abc123 verify the following:

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 body and is encoded using the x-www-form-urlencoded format. The information is set in properties whose names correspond with the properties of the action. For example, ConfirmAction has the property confirmed.

Step 3: Return a response code

After the service processes and records the action successfully, return response code 200 (OK). You can use the following response codes in error situations:

Response Code Treatment
400 (Bad Request) Google marks the action as failed.
401 (Unauthorized) Google marks the action as failed.
404 (Not Found) Google marks the action as failed.
408 (Request Timeout) Google retries later.

For permanent failures, Google informs the user that the action failed and that they should follow alternative instructions inside the email.

Further reading