Try the snippets: Import, deploy, and explore code snippets in context using a new Dialogflow agent.
Explore in Dialogflow
Click Continue to import our Notifications sample in Dialogflow. Then, follow the steps below to deploy and test the sample:
- Enter an agent name and create a new Dialogflow agent for the sample.
- After the agent is done importing, click Go to agent .
- From the main navigation menu, go to Fulfillment .
- Enable the Inline Editor , then click Deploy . The editor contains the sample code.
- From the main navigation menu, go to Integrations , then click Google Assistant .
- In the modal window that appears, enable Auto-preview changes and click Test to open the Actions simulator.
- In the simulator, enter
Talk to my test appto test the sample!
Your Action can push notifications to users whenever relevant, such as sending a reminder when the due date for a task is near.
In this guide, we use the Actions on Google tips sample as a reference to show you how to set up push notifications for your Action. When users invoke this Action, it asks whether they want to hear a tip about developing their own Action. Users can choose either a specific or randomly selected category for the tip, or they can choose to hear the most recent tip.
Supported surfaces
Push notifications are available on Android and iOS devices (iOS devices must have the Assistant app installed to receive push notifications). They are not currently supported on voice-activated speakers, smart displays, or other surfaces.
Prerequisites
At least one of the Actions in your Actions project must be configured as a triggering intent which will be invoked when the user taps a notification received from the Assistant.
Your Actions cannot be configured to trigger the Default Welcome Intent from a push notification.
Console setup
To add support for push notifications to your Action:
-
Go to the Actions console and navigate to Build > Actions.
-
Click the Action that matches the additional triggering intent you want to enable push notifications for.
For the Actions on Google tips sample, you would select "tell_latest_tip".
-
Scroll down to the User engagementsection and turn on Would you like to send push notifications.
-
Enter a Content title.
For the Actions on Google tips sample, the title could be "New tip added".
-
Click Save.
Imports
For the purposes of the next sections, in your fulfillment code, you will need to declare the following imports:
const { dialogflow , UpdatePermission , Suggestions , } = require ( 'actions-on-google' );
const { actionssdk , UpdatePermission , Suggestions , } = require ( 'actions-on-google' );
Opt-in users
Before you can send push notifications to users, you must ask for them to opt-in. You can do this by showing them a suggestion chip to ask for their permission. When they grant permission, you receive an update user ID to send push notifications to that user.
Show suggestion chips for opt-in
Before users can receive push notifications from your Action, you must show them a suggestion chip to invite them to opt-in for push notifications.
The following code snippet sends the user an 'Alert me of new tips' suggestion chip alongside a text response.
conv.ask('I can send you push notifications. Would you like that?'); conv.ask(new Suggestions('Send notifications'));
conv.ask(' I can send you push notifications. Would you like that?'); conv.ask(new Suggestions('Send notifications'));
responseBuilder .add("I can send you push notifications. Would you like that?") .addSuggestions(new String[] { "Send notifications" });
responseBuilder .add("I can send you push notifications. Would you like that?") .addSuggestions(new String[] { "Send notifications" });
Note that the JSON below describes a webhook response.
{ "payload" : { "google" : { "expectUserResponse" : true , "richResponse" : { "items" : [ { "simpleResponse" : { "textToSpeech" : "Hi! Welcome to Push Notifications!" } }, { "simpleResponse" : { "textToSpeech" : "I can send you push notifications. Would you like that?" } } ], "suggestions" : [ { "title" : "Send notifications" } ] } } } }
Note that the JSON below describes a webhook response.
{ "expectUserResponse" : true , "expectedInputs" : [ { "possibleIntents" : [ { "intent" : "actions.intent.TEXT" } ], "inputPrompt" : { "richInitialPrompt" : { "items" : [ { "simpleResponse" : { "textToSpeech" : "Hi! Welcome to Push Notifications!" } }, { "simpleResponse" : { "textToSpeech" : " I can send you push notifications. Would you like that?" } } ], "suggestions" : [ { "title" : "Send notifications" } ] } } } ] }
After they tap the chip, you must ask for the UPDATE
permission.
The following code shows you how to do this with the askForUpdatePermission
function of the Node.js client library.
- Open your agent in the Dialogflow console and select the intent you're configuring for updates.
- Scroll down to Response and open the Google Assistant tab.
- Click Add message content and select Suggestion chips .
- Set the chip text to something that invites the user to opt-in. In the Actions on Google tips sample we set the chip to Alert me of new tips .
- Add another Dialogflow intent, called for example setup_push , and set a corresponding action, for example setup.push . The user expression of this intent must match the text of the opt-in chip, in our example Alert me of new tips .
app . intent ( 'Subscribe to Notifications' , ( conv ) = > { conv.ask(new UpdatePermission({ intent : 'Notification' , } )); } );
You should configure your NLU solution to trigger a function that asks the permission if the user expression matches the value of the push notifications opt-in prompt. Here's a very basic example based on string matching:
conv . ask ( new UpdatePermission ( { intent : 'Notification' , } ));
- Open your agent in the Dialogflow console and select the intent you're configuring for updates.
- Scroll down to Response and open the Google Assistant tab.
- Click Add message content and select Suggestion chips .
- Set the chip text to something that invites the user to opt-in. In the Actions on Google tips sample we set the chip to Alert me of new tips .
- Add another Dialogflow intent, called for example setup_push , and set a corresponding action, for example setup.push . The user expression of this intent must match the text of the opt-in chip, in our example Alert me of new tips .
@ForIntent ( "Subscribe to Notifications" ) public ActionResponse subscribeToNotifications ( ActionRequest request ) { ResponseBuilder responseBuilder = getResponseBuilder ( request ); responseBuilder . add ( new UpdatePermission (). setIntent ( "Notification" )); return responseBuilder . build (); }
You should configure your NLU solution to trigger a function that asks the permission if the user expression matches the value of the push notifications opt-in prompt. Here's a very basic example based on string matching:
ResponseBuilder responseBuilder = getResponseBuilder(request); responseBuilder.add(new UpdatePermission().setIntent("Notification")); return responseBuilder.build();
Note that the JSON below describes a webhook response using Dialogflow.
{ "payload" : { "google" : { "expectUserResponse" : true , "systemIntent" : { "intent" : "actions.intent.PERMISSION" , "data" : { "@type" : "type.googleapis.com/google.actions.v2.PermissionValueSpec" , "permissions" : [ "UPDATE" ], "updatePermissionValueSpec" : { "intent" : "tell_latest_tip" } } } } } }
Note that the JSON below describes a webhook response using Actions SDK.
{ "expectUserResponse" : true , "expectedInputs" : [ { "possibleIntents" : [ { "intent" : "actions.intent.PERMISSION" , "inputValueData" : { "@type" : "type.googleapis.com/google.actions.v2.PermissionValueSpec" , "permissions" : [ "UPDATE" ], "updatePermissionValueSpec" : { "intent" : "tell_latest_tip" } } } ] } ] }
Finalize the subscription
To finalize the subscription from your Node.js webhook, you need to save the user's notifications ID and the intent they selected. Both are passed as arguments if the user grants the permission.
If your Action is built with Dialogflow, you need to:
- Add an intent that handles the
actions_intent_PERMISSION. - Specify the intent's Actionname to something that your webhook can filter for later.
The following code shows how to handle a Dialogflow intent with an intent
named finish_push_setup
with an Action name of finish.push.setup
:
app . intent ( 'Confirm Notifications Subscription' , ( conv ) = > { if ( conv . arguments . get ( 'PERMISSION' )) { const updatesUserId = conv . arguments . get ( 'UPDATES_USER_ID' ); // Store user ID in database for later use conv . close ( ` Ok , I 'll start alerting you.`); } else { conv . close ( ` Ok , I won 't alert you.`); } });
app . intent ( 'actions.intent.PERMISSION' , ( conv ) = > { if ( conv . arguments . get ( 'PERMISSION' )) { const updatesUserId = conv . arguments . get ( 'UPDATES_USER_ID' ); // Store user ID in database for later use conv . close ( ` Ok , I 'll start alerting you.`); } else { conv . close ( ` Ok , I won 't alert you.`); } });
@ForIntent ( "Confirm Notifications Subscription" ) public ActionResponse confirmNotificationsSubscription ( ActionRequest request ) { // Verify the user has subscribed for push notifications ResponseBuilder responseBuilder = getResponseBuilder ( request ); if ( request . isPermissionGranted ()) { Argument userId = request . getArgument ( ConstantsKt . ARG_UPDATES_USER_ID ); if ( userId != null ) { // Store the user 's ID in the database } responseBuilder.add("Ok, I' ll start alerting you . "); } else { responseBuilder.add(" Ok , I won ' t alert you . " ); } responseBuilder . endConversation (); return responseBuilder . build (); }
@ForIntent ( "actions.intent.PERMISSION" ) public ActionResponse confirmNotificationsSubscription ( ActionRequest request ) { // Verify the user has subscribed for push notifications ResponseBuilder responseBuilder = getResponseBuilder ( request ); if ( request . isPermissionGranted ()) { Argument userId = request . getArgument ( ConstantsKt . ARG_UPDATES_USER_ID ); if ( userId != null ) { // Store the user 's ID in the database } responseBuilder.add("Ok, I' ll start alerting you . "); } else { responseBuilder.add(" Ok , I won ' t alert you . " ); } responseBuilder . endConversation (); return responseBuilder . build (); }
Note that the JSON below describes a request to the webhook.
{ "responseId" : "ee9e7ed5-fa1a-48c6-aac7-f9fbe94f1f58-712767ed" , "queryResult" : { "queryText" : "actions_intent_PERMISSION" , "action" : "confirm.subscription" , "parameters" : {}, "allRequiredParamsPresent" : true , "fulfillmentMessages" : [ { "text" : { "text" : [ "" ] } } ], "outputContexts" : [ { "name" : "projects/PROJECT_ID/agent/sessions/ABwppHGIgmmU3zBcYMF_vWoHaM4JUo3wniYBHdbUF25l63G7EQWjRnlne8Ar7AOcRHWn1lrEKGy8qdP0UXLcWDBq93k/contexts/actions_capability_screen_output" }, { "name" : "projects/PROJECT_ID/agent/sessions/ABwppHGIgmmU3zBcYMF_vWoHaM4JUo3wniYBHdbUF25l63G7EQWjRnlne8Ar7AOcRHWn1lrEKGy8qdP0UXLcWDBq93k/contexts/actions_capability_account_linking" }, { "name" : "projects/PROJECT_ID/agent/sessions/ABwppHGIgmmU3zBcYMF_vWoHaM4JUo3wniYBHdbUF25l63G7EQWjRnlne8Ar7AOcRHWn1lrEKGy8qdP0UXLcWDBq93k/contexts/actions_capability_media_response_audio" }, { "name" : "projects/PROJECT_ID/agent/sessions/ABwppHGIgmmU3zBcYMF_vWoHaM4JUo3wniYBHdbUF25l63G7EQWjRnlne8Ar7AOcRHWn1lrEKGy8qdP0UXLcWDBq93k/contexts/actions_capability_audio_output" }, { "name" : "projects/PROJECT_ID/agent/sessions/ABwppHGIgmmU3zBcYMF_vWoHaM4JUo3wniYBHdbUF25l63G7EQWjRnlne8Ar7AOcRHWn1lrEKGy8qdP0UXLcWDBq93k/contexts/actions_capability_web_browser" }, { "name" : "projects/PROJECT_ID/agent/sessions/ABwppHGIgmmU3zBcYMF_vWoHaM4JUo3wniYBHdbUF25l63G7EQWjRnlne8Ar7AOcRHWn1lrEKGy8qdP0UXLcWDBq93k/contexts/google_assistant_input_type_keyboard" }, { "name" : "projects/PROJECT_ID/agent/sessions/ABwppHGIgmmU3zBcYMF_vWoHaM4JUo3wniYBHdbUF25l63G7EQWjRnlne8Ar7AOcRHWn1lrEKGy8qdP0UXLcWDBq93k/contexts/actions_intent_permission" , "parameters" : { "PERMISSION" : true , "text" : "yes" , "UPDATES_USER_ID" : "ABwppHHssyPbvEBF1mgN7Ddwb7mkhiVohW9PZ--I_svqy7zFElA4DHkf9pn04UBd5gwZo26_RfXCQ8otcztyIfe6MCQ" } } ], "intent" : { "name" : "projects/PROJECT_ID/agent/intents/c7f7b30b-5b88-4bb5-b0b8-1cd0862d1dd2" , "displayName" : "Confirm Notifications Subscription" }, "intentDetectionConfidence" : 1 , "languageCode" : "en" }, "originalDetectIntentRequest" : { "source" : "google" , "version" : "2" , "payload" : { "user" : { "permissions" : [ "UPDATE" ], "locale" : "en-US" , "userVerificationStatus" : "VERIFIED" }, "conversation" : { "conversationId" : "ABwppHGIgmmU3zBcYMF_vWoHaM4JUo3wniYBHdbUF25l63G7EQWjRnlne8Ar7AOcRHWn1lrEKGy8qdP0UXLcWDBq93k" , "type" : "ACTIVE" , "conversationToken" : "[]" }, "inputs" : [ { "intent" : "actions.intent.PERMISSION" , "rawInputs" : [ { "inputType" : "KEYBOARD" , "query" : "yes" } ], "arguments" : [ { "name" : "PERMISSION" , "boolValue" : true , "textValue" : "true" }, { "name" : "text" , "rawText" : "yes" , "textValue" : "yes" }, { "name" : "UPDATES_USER_ID" , "textValue" : "ABwppHHssyPbvEBF1mgN7Ddwb7mkhiVohW9PZ--I_svqy7zFElA4DHkf9pn04UBd5gwZo26_RfXCQ8otcztyIfe6MCQ" } ] } ], "surface" : { "capabilities" : [ { "name" : "actions.capability.SCREEN_OUTPUT" }, { "name" : "actions.capability.ACCOUNT_LINKING" }, { "name" : "actions.capability.MEDIA_RESPONSE_AUDIO" }, { "name" : "actions.capability.AUDIO_OUTPUT" }, { "name" : "actions.capability.WEB_BROWSER" } ] }, "availableSurfaces" : [ { "capabilities" : [ { "name" : "actions.capability.AUDIO_OUTPUT" }, { "name" : "actions.capability.SCREEN_OUTPUT" }, { "name" : "actions.capability.WEB_BROWSER" } ] } ] } }, "session" : "projects/PROJECT_ID/agent/sessions/ABwppHGIgmmU3zBcYMF_vWoHaM4JUo3wniYBHdbUF25l63G7EQWjRnlne8Ar7AOcRHWn1lrEKGy8qdP0UXLcWDBq93k" }
Note that the JSON below describes a request to the webhook.
{ "user" : { "permissions" : [ "UPDATE" ], "locale" : "en-US" , "userVerificationStatus" : "VERIFIED" }, "conversation" : { "conversationId" : "ABwppHEP6OAFZHkSGEiZ5HYM9qrlk8YtIH1DQmJ52cxXELSPvM-kSc_tMJ_5O6ITbgVJlY9i2FIsKWjE_HXLke48" , "type" : "NEW" }, "inputs" : [ { "intent" : "actions.intent.PERMISSION" , "rawInputs" : [ { "inputType" : "KEYBOARD" , "query" : "yes" } ], "arguments" : [ { "name" : "PERMISSION" , "boolValue" : true , "textValue" : "true" }, { "name" : "text" , "rawText" : "yes" , "textValue" : "yes" }, { "name" : "UPDATES_USER_ID" , "textValue" : "ABwppHFvBKC-tMYUsUjJkm3YECgZvd6A3sOc7KuQvO4ZdQX3bGLmyoQ41dh4Zmtlzv_kaOKBt1Sf6eRpNbayynrl" } ] } ], "surface" : { "capabilities" : [ { "name" : "actions.capability.AUDIO_OUTPUT" }, { "name" : "actions.capability.WEB_BROWSER" }, { "name" : "actions.capability.SCREEN_OUTPUT" }, { "name" : "actions.capability.ACCOUNT_LINKING" }, { "name" : "actions.capability.MEDIA_RESPONSE_AUDIO" } ] }, "availableSurfaces" : [ { "capabilities" : [ { "name" : "actions.capability.AUDIO_OUTPUT" }, { "name" : "actions.capability.SCREEN_OUTPUT" }, { "name" : "actions.capability.WEB_BROWSER" } ] } ] }
Send notifications
You can send push notifications to users using the Actions API. To use this API, you need to activate the API in your Google Cloud project and setup and download a JSON service account key. See step #8 in the instructions in the code sample here .
You can then use the Google OAuth2 client library to exchange the service account key for an access token and use the token to authenticate your requests to the Actions API.
Get a service account key
- Go to this URL, replacing "example-project-1" at the end with your project ID in the Actions console: https://console.developers.google.com/apis/api/actions.googleapis.com/overview?project=example-project-1
- If you see an Enablebutton, click it. Otherwise, proceed to step 3.
- Go to this URL, replacing "example-project-1" at the end with your project ID in the Actions console: https://console.developers.google.com/apis/credentials?project=example-project-1
- Click Create credentials > Service Account Key.
- Click the Select box under Service Accountand click New Service Account.
- Give the Service Account a name like "notifications" and the Roleof Project Owner .
- Select the JSON key type and click Create. A JSON service account key is downloaded to your local machine.
Exchange the key for an access token and send a notification
To send a notification through the Actions API, you need to exchange the service account key for an access token. We recommend using a Google API client library for this. In the series of code snippets that follow, we are using the Google API Node.js client library.
- Install the Google API client library and request:
npm install googleapis request --save - Use the following code to get an access token from the service account key and send a push notification:
const { google } = require ( 'googleapis' ); const request = require ( 'request' ); const jwtClient = new google . auth . JWT ( serviceAccount . client_email , null , serviceAccount . private_key , [ 'https://www.googleapis.com/auth/actions.fulfillment.conversation' ], null ); jwtClient . authorize (( err , tokens ) = > { if ( ! err ) { request . post ( 'https://actions.googleapis.com/v2/conversations:send' , { auth : { bearer : tokens . access_token , }, json : true , body : { customPushMessage : { userNotification : { title : 'Push Notification Title' , }, target : { userId : '<UPDATES_USER_ID>' , intent : 'Notification Intent' , }, }, isInSandbox : true , }, }, ( err , httpResponse , body ) = > { console . log ( ` $ { httpResponse . statusCode }: $ { httpResponse . statusMessage } ` ); }); } });
const { google } = require ( 'googleapis' ); const request = require ( 'request' ); const jwtClient = new google . auth . JWT ( serviceAccount . client_email , null , serviceAccount . private_key , [ 'https://www.googleapis.com/auth/actions.fulfillment.conversation' ], null ); jwtClient . authorize (( err , tokens ) = > { if ( ! err ) { request . post ( 'https://actions.googleapis.com/v2/conversations:send' , { auth : { bearer : tokens . access_token , }, json : true , body : { customPushMessage : { userNotification : { title : 'Push Notification Title' , }, target : { userId : '<UPDATES_ORDER_ID>' , intent : 'Notification Intent' , }, }, isInSandbox : true , }, }, ( err , httpResponse , body ) = > { console . log ( ` $ { httpResponse . statusCode }: $ { httpResponse . statusMessage } ` ); }); } });
final class Notification { private final String title ; Notification ( String title ) { this . title = title ; } String getTitle () { return title ; } } final class Target { private final String userId ; private final String intent ; private final String locale ; Target ( String userId , String intent , String locale ) { this . userId = userId ; this . intent = intent ; this . locale = locale ; } String getUserId () { return userId ; } String getIntent () { return intent ; } String getLocale () { return locale ; } } final class PushMessage { private final Notification userNotification ; private final Target target ; PushMessage ( Notification userNotification , Target target ) { this . userNotification = userNotification ; this . target = target ; } Notification getUserNotification () { return userNotification ; } Target getTarget () { return target ; } } final class PushNotification { private final PushMessage customPushMessage ; private boolean isInSandbox ; PushNotification ( PushMessage customPushMessage , boolean isInSandbox ) { this . customPushMessage = customPushMessage ; this . isInSandbox = isInSandbox ; } PushMessage getCustomPushMessage () { return customPushMessage ; } boolean getIsInSandbox () { return isInSandbox ; } } private PushNotification createNotification ( String title , String userId , String intent , String locale ) { Notification notification = new Notification ( title ); Target target = new Target ( userId , intent , locale ); PushMessage message = new PushMessage ( notification , target ); boolean isInSandbox = true ; return new PushNotification ( message , isInSandbox ); } private ServiceAccountCredentials loadCredentials () throws IOException { String actionsApiServiceAccountFile = this . getClass () . getClassLoader () . getResource ( "service-account.json" ) . getFile (); InputStream actionsApiServiceAccount = new FileInputStream ( actionsApiServiceAccountFile ); ServiceAccountCredentials serviceAccountCredentials = ServiceAccountCredentials . fromStream ( actionsApiServiceAccount ); return ( ServiceAccountCredentials ) serviceAccountCredentials . createScoped ( Collections . singleton ( "https://www.googleapis.com/auth/actions.fulfillment.conversation" )); } private String getAccessToken () throws IOException { AccessToken token = loadCredentials () . refreshAccessToken (); return token . getTokenValue (); } public void sendNotification ( String title , String userId , String intent , String locale ) throws IOException { Preconditions . checkNotNull ( title , "title cannot be null." ); Preconditions . checkNotNull ( userId , "userId cannot be null." ); Preconditions . checkNotNull ( intent , "intent cannot be null." ); Preconditions . checkNotNull ( locale , "locale cannot be null" ); PushNotification notification = createNotification ( title , userId , intent , locale ); HttpPost request = new HttpPost ( "https://actions.googleapis.com/v2/conversations:send" ); String token = getAccessToken (); request . setHeader ( "Content-type" , "application/json" ); request . setHeader ( "Authorization" , "Bearer " + token ); StringEntity entity = new StringEntity ( new Gson () . toJson ( notification )); entity . setContentType ( ContentType . APPLICATION_JSON . getMimeType ()); request . setEntity ( entity ); HttpClient httpClient = HttpClientBuilder . create () . build (); httpClient . execute ( request ); }
final class Notification { private final String title ; Notification ( String title ) { this . title = title ; } String getTitle () { return title ; } } final class Target { private final String userId ; private final String intent ; Target ( String userId , String intent ) { this . userId = userId ; this . intent = intent ; } String getUserId () { return userId ; } String getIntent () { return intent ; } } final class PushMessage { private final Notification userNotification ; private final Target target ; PushMessage ( Notification userNotification , Target target ) { this . userNotification = userNotification ; this . target = target ; } Notification getUserNotification () { return userNotification ; } Target getTarget () { return target ; } } final class PushNotification { private final PushMessage customPushMessage ; private boolean isInSandbox ; PushNotification ( PushMessage customPushMessage , boolean isInSandbox ) { this . customPushMessage = customPushMessage ; this . isInSandbox = isInSandbox ; } PushMessage getCustomPushMessage () { return customPushMessage ; } boolean getIsInSandbox () { return isInSandbox ; } } private PushNotification createNotification ( String title , String userId , String intent ) { Notification notification = new Notification ( title ); Target target = new Target ( userId , intent ); PushMessage message = new PushMessage ( notification , target ); boolean isInSandbox = true ; return new PushNotification ( message , isInSandbox ); } private ServiceAccountCredentials loadCredentials () throws IOException { String actionsApiServiceAccountFile = this . getClass () . getClassLoader () . getResource ( "service-account.json" ) . getFile (); InputStream actionsApiServiceAccount = new FileInputStream ( actionsApiServiceAccountFile ); ServiceAccountCredentials serviceAccountCredentials = ServiceAccountCredentials . fromStream ( actionsApiServiceAccount ); return ( ServiceAccountCredentials ) serviceAccountCredentials . createScoped ( Collections . singleton ( "https://www.googleapis.com/auth/actions.fulfillment.conversation" )); } private String getAccessToken () throws IOException { AccessToken token = loadCredentials () . refreshAccessToken (); return token . getTokenValue (); } public void sendNotification ( String title , String userId , String intent ) throws IOException { Preconditions . checkNotNull ( title , "title cannot be null." ); Preconditions . checkNotNull ( userId , "userId cannot be null." ); Preconditions . checkNotNull ( intent , "intent cannot be null." ); PushNotification notification = createNotification ( title , userId , intent ); HttpPost request = new HttpPost ( "https://actions.googleapis.com/v2/conversations:send" ); String token = getAccessToken (); request . setHeader ( "Content-type" , "application/json" ); request . setHeader ( "Authorization" , "Bearer " + token ); StringEntity entity = new StringEntity ( new Gson () . toJson ( notification )); entity . setContentType ( ContentType . APPLICATION_JSON . getMimeType ()); request . setEntity ( entity ); HttpClient httpClient = HttpClientBuilder . create () . build (); httpClient . execute ( request ); }
