Webhook Format

You communicate with API.AI through its own, standard webhook format and not the Actions on Google conversation webhook. API.AI adds additional fields in its own request and response formats when you use Actions on Google as an integration, and they're described in this document.

Format of request to the webhook

In the request to your fulfillment, you receive data formatted in the standard API.AI webhook request format with an additional originalRequest field that contains Actions on Google specific information.

  • The originalRequest.data object matches the format described by the conversation webhook request format.
  • The originalRequest.version field describes whether or not the request is an Actions on Google v1 (1) or v2 (2) request.
  • The Content-type for this request is application/json.

Verifying the request

When enabling fulfillment for an API.AI agent, the console offers two main options for request verification and authentication. The first is standard HTTP authentication using a header with the following format: authorization: "Basic <encrypted_credentials>" where the encrypted credentials consist of a username/password combination entered in API.AI.

The second option is custom request headers. API.AI allows you to enter a custom header key and value that will be sent in the HTTP POST request to the webhook.

Format of response from the webhook

The response format of the API.AI webhook contains the standard API.AI webhook response contents and a data.google object that closely resembles a standard conversation webhook response with the following general differences:

API.AI webhook Conversation webhook
Contexts Actions on Google uses a conversationToken to allow data persistance. However, API.AI contexts offer much more functionality, so the conversationToken is not used in API.AI's webhook.
data.google.expectUserResponse expectUserResponse
data.google.isSsml The ssml field in a SimpleResponse
data.google.speech The textToSpeech field in a SimpleResponse
data.google.systemIntent expectedInputs.possibleIntents
data.google.richResponse A RichResponse in an expectedInputs.inputPrompt.richInitialPrompt
data.google.finalResponse finalResponse

Here's an example of what an API.AI webhook response looks like:

'data': {
  'google': {
    'expectUserResponse': true,
    'isSsml': false,
    'noInputPrompts': [],
    'richResponse': {
      'items': [
        {
          'simpleResponse': {
            'textToSpeech': 'hello',
            'displayText': 'hi'
          }
        }
      ],
      'suggestions': [
        {
          'title': 'Say this'
        },
        {
          'title': 'or this'
        }
      ]
    },
    'systemIntent': {
      'intent': 'actions.intent.OPTION',
      'data': {
        '@type': 'type.googleapis.com/google.actions.v2.OptionValueSpec',
        'listSelect': {
          'items': [
            {
              'optionInfo': {
                'key': 'key1',
                'synonyms': [
                  'key one'
                ]
              },
              'title': ''
            },
            {
              'optionInfo': {
                'key': 'key2',
                'synonyms': [
                  'key two'
                ]
              },
              'title': ''
            }
          ]
        }
      }
    }
  }
}