Join the Actions on Google Developer Challenge to win a trip to Google I/O 2018 and more than 20 other prizes.

Fulfillment Hosting

You can use any web hosting platform to implement your fulfillment. You need to support HTTPS requests and responses, and parse the JSON payloads from API.AI or the Actions SDK. For your convenience, we provide a Node.js client library parses and generates the necessary JSON payloads for fulfillment requests.

If you don't already have a preferred hosting platform, we've outlined how to deploy to a local and production environment with Google Cloud Functions with one of our samples and generically with Google App Engine and Heroku.

Get the API.AI Silly Name Maker sample

If you don't already have a Google Cloud Functions fulfillment app, you can deploy any sample to test out the process. Run the following commands to get a simple fulfillment sample as an example:

git clone https://github.com/actions-on-google/apiai-silly-name-maker-webhook-nodejs
npm install

We'll refer to the directory that you cloned the sample to as <sample-dir>.

Deploying to Google Cloud Functions

  1. Download Google Cloud SDK.
  2. Download and install Node.js.
  3. In the Cloud Platform Console, go to the Projects page and select or create a new project. This should be the project you are using for your actions.
  4. Enable billing for your project. See the console help center for more information.
  1. Initialize the Cloud SDK with the following command:

    gcloud init
    
  2. Run the following commands to configure your Google Cloud project:

    gcloud config set project <project-id>
    
  3. Find the name of the cloud function in your index.js. For example, the function name in the sample is sillyNameMaker in the snippet below:

    exports.sillyNameMaker = (request, response) => { ...
    

    We'll refer to this name as <function_name>.

At this point, you can choose to deploy your Cloud Function locally (convenient for quick development and testing) or to production.

Deploy locally

Deploying fulfillment locally is useful for development and testing. To develop locally, you need ngrok and the Google Cloud Functions emulator:

  1. Download ngrok and unpack the zip file to any directory. We'll refer to this as <ngrok-dir>.
  2. Install the Google Cloud Functions emulator:

    npm install -g @google-cloud/functions-emulator
    
  3. Run the following commands to deploy the function.

    functions start
    functions deploy <function_name> --trigger-http
    

    The output of the commands displays a table of information. Make note of the URL specified by the Resource row. You'll need the port and path of that URL. For example, for http://localhost:8010/sillyNameMakerGoogleProject/us-central1/sillyNameMaker, the port is 8010 and the path is /sillyNameMakerGoogleProject/us-central1/sillyNameMaker.

  4. Run ngrok with the port specified by the Resource URL:

    <ngrok-dir>/ngrok http <port>
    

    Your fulfillment URL is the ngrok hostname appended with the path of the Resource URL. For example:

    https://d4b9db8d.ngrok.io/sillyNameMakerGoogleProject/us-central1/sillyNameMaker

Deploy to production

When you're ready to deploy fulfillment to production, you need to create a Google Cloud Functions storage bucket and use the gcloud CLI to deploy the function:

  1. Create a Storage Bucket for your Google Developer Project. Make a note of the storage bucket name.
  2. Deploy the Cloud Function with the following command:

    gcloud beta functions deploy <function_name> --trigger-http --stage-bucket <storage_bucket_name>
    

The output of the deploy command displays your fulfillment URL.

Other hosting options

The following sections describe deploying to other hosting options. However, we don't provide samples that support these hosting options.

Deploying to Google App Engine

  1. Download Google Cloud SDK.
  2. Download and install Node.js.
  3. In the Cloud Platform Console, go to the Projects page and select or create a new project. This should be the project you are using for your actions.
  4. Enable billing for your project. See the console help center for more information. Note: Note the Project ID, since it is used for configuration and deployment.

  5. Initialize the Cloud SDK with the following command:

    gcloud init
    
  6. Run the following commands to configure your Google cloud project:

    gcloud config set project <project-id>
    
  7. Deploy fulfillment:

    cd <fulfillment-app-dir>
    gcloud app deploy
    

    You should see a long response from the gCloud CLI (it may take a few minutes) with the final portion looking similar to:

    Updating service [default]...done.
    Deployed service [default] to your-appengine-url.appspot.com
    
    You can read logs from the command line by running:
      $ gcloud app logs read
    
    To view your application in the web browser run:
      $ gcloud app browse
    

Deploying to Heroku

See the Heroku documentation for full instructions on setting up a project and deploying it.

  1. Sign up for a Heroku account if you don’t already have one.
  2. In your Heroku Apps list, click New > Create New App in the top right and specify an app name.
  3. Download the Heroku CLI. To ensure it works, run heroku --version.
  4. If your project is not already in a Git repo, initialize your project directory:

    cd git init

  5. Type heroku login and enter your credentials to log in to the Heroku CLI.

  6. Run heroku git:remote -a <HEROKU_APP_NAME> to register your remote Heroku project repository with your local Git project. If you already have a Git repo in your Heroku project, then clone the repo with heroku git:clone -a <HEROKU_APP_NAME>.
  7. Add and commit your files if you haven’t already, using git add . and git commit -am "Initial commit"
  8. Use git push heroku master to push your local app to Heroku
  9. Make sure you set your Heroku app’s URL, found in your app’s settings, as the fulfillment Webhook URL in the Fulfillment page of API.AI.
  10. You can view your projects logs using with heroku logs