docs: update readme

Author: pr-Mais

firestore-dialogflow-fulfillment/POSTINSTALL.md

@@ -10,7 +10,7 @@ This will create a new DialogFlow agent named `${param:AGENT_NAME}` for you. You
 
 ## Setting up DialogFlow Fulfillment
 
-First, copy this URL `https://${param:LOCATION}-${param:PROJECT_ID}.cloudfunctions.net/ext-firestore-dialogflow-fulfillment-dialogflowFulfillment`, which is the URL of the DialogFlow webhook.
+First, copy this URL, which is the URL of the DialogFlow webhook: `https://${param:LOCATION}-${param:PROJECT_ID}.cloudfunctions.net/ext-firestore-dialogflow-fulfillment-dialogflowFulfillment`
 
 Next, go to the DialogFlow console [here](https://dialogflow.cloud.google.com/#/agent/${param:PROJECT_ID}/fulfillment), enable the Webhook and add this URL as the Fulfillment webhook URL.
 

firestore-dialogflow-fulfillment/README.md

@@ -1,22 +1,35 @@
 # Firestore DialogFlow Fulfillment
 
-This extension integrates with DialogFlow through Firestore.
+This extension integrates with DialogFlow through Firestore, it can book meetings on your calendar from a DialogFlow conversation.
+
+You don't need to interact with DialogFlow in your app as the extension do it for you and provide the conversation replies from DialogFlow in a Firestore collection.
 
 ## Install The Extension
 
-### Pre-requisites
+Make sure `firebase-tools` is installed: `npm i -g firebase-tools`.
 
-1. Make sure `firebase-tools` is installed: `npm i -g firebase-tools`.
-2. You are using Node 14 (`nvm use 14`).
+To install the extension, run:
 
-#### Install
+```bash
+firebase ext:install path/to/extension --project=extensions-testing
+```
 
-To install the extension, run:
+### DialogFlow agent setup
+
+Before you can use the extension, you need to have a DialogFlow agent. The extension provides you with a HTTP function that you can call to create an agent for you, so you don't to do it manually.
+
+To create and agent, you can call the `ext-firestore-dialogflow-fulfillment-createDialogflowAgent` function through the [Google Cloud CLI](https://cloud.google.com/sdk/gcloud):
 
 ```bash
-firebase ext:install . --project=extensions-testing
+gcloud config set project PROJECT_ID
+gcloud config set functions/region LOCATION
+gcloud functions call ext-firestore-dialogflow-fulfillment-createDialogflowAgent --data '{"data":""}'
 ```
 
+This will create a new DialogFlow agent for you. You can find the agent in the DialogFlow console [here](https://dialogflow.cloud.google.com/#/agents).
+
+### Setting up DialogFlow Fulfillment
+
 The extension will deploy a HTTP function that will be used as a Fullfilment webhook for DialogFlow. The function will look like this, with the `PROJECT_ID` replaced with your project ID, and the `LOCATION` replaced with your project's default Cloud Functions location:
 
 ```bash
@@ -25,32 +38,44 @@ https://{LOCATION}-{PROJECT_ID}.cloudfunctions.net/ext-firestore-dialogflow-fulf
 
 Provide the URL to DialogFlow as the Fulfillment webhook URL.
 
-### Development
+### Give the extension access to your calendar
 
-1. `cd firestore-dialogflow-fulfillment/functions` && `npm run build`
-2. `cd firestore-dialogflow-fulfillment/demo` && `npm run dev`
-3. `cd _emulator` && `firebase emulators:start`
+To allow the extension to create events, you need to give it access to the calendar `${param:CALENDAR_ID}`. To do this, copy the extension service account principal email address from the [Service Accounts page](https://console.cloud.google.com/iam-admin/serviceaccounts) in the Google Cloud Console, which starts with `ext-firestore-dialogflow`. Then, go to your calendar Sharing settings, and add the email with **Make changes to events** permission.
 
-## DialogFlow
+## Using the extension
 
-https://dialogflow.cloud.google.com/#/agent/extensions-testing/editIntent/334a55e8-3280-4651-b1d8-109ceb78cfd4/
+Call `newConversation` with a `message` to start a new conversation, which will return a `conversationId` that you can use to send messages to the same conversation.
 
-- Agent = Overall agent who will handle the conversation
-- Intent = Based on user input, dialogflow will match to an intent based on the settings in that intent
- - We are trying to get a DATE & TIME from the user (to do something with, e.g. add something to Google calendar)
- - If DialogFlow doesn't have both parameters, it will ask the user for them (based on ML and the data in the intent config)
+```ts
+export async function newConversation(message: string): Promise<string> {
+  const result = await httpsCallable<{ message: string }, string>(
+    functions,
+    "ext-firestore-dialogflow-fulfillment-newConversation"
+  )({ message });
+  return result.data;
+}
+```
 
-- Each time DialogFlow gets a message, it'll send it through the webhook (https://dialogflow.cloud.google.com/#/agent/extensions-testing/fulfillment)
- - In our webhook logic, if the intent matches one we care about AND we have both DATE & TIME parameters, we'll send a message to the user, otherwise just let DialogFlow handle it.
- - At this point we'll go and do some API task and respond to the user (e.g. "I've added that to our calendar, see you on X at Y")
+To add new messages to the conversation, call `newMessage` with the `conversationId` and `message`.
+
+```ts
+export async function newMessage(
+  conversationId: string,
+  message: string
+): Promise<void> {
+  await httpsCallable<{ conversationId: string; message: string }, void>(
+    functions,
+    "ext-firestore-dialogflow-fulfillment-newMessage"
+  )({ conversationId, message });
+}
+```
 
-(Note: Been using https://ngrok.com/ to pipe the webhook messages to the emulator - just needs installing and setting up on the port functions are running on).
+## Development
 
-The current general flow for the extension is:
+1. `cd firestore-dialogflow-fulfillment/functions` && `npm run build`
+2. `cd firestore-dialogflow-fulfillment/demo` && `npm run dev`
+3. `cd _emulator` && `firebase emulators:start`
 
-- `newConversation` - Callable Function. Takes a message, creates a new conversation and adds a doc to a subcollection, and returns the ID (which the user can use to listen to new messages).
-- `newMessage` - adds a new user message to the conversation 
-- `onNewMessage` - a firestore trigger that listens for new messages. If it's from the user, we'll send a message to dialog flow and wait for a response. Once we have that, add a message to the conversation.
-- `dialogflowFulfillment` - HTTP function (ignores auth for now), which DialogFlow calls - here we can respond with our own messages to the user if we want.
+(Note: Been using https://ngrok.com/ to pipe the webhook messages to the emulator - just needs installing and setting up on the port functions are running on).
 
 Use `lsof -t -i:4001 -i:8080 -i:9000 -i:9099 -i:9199 -i:8085 | xargs kill -9` to kill emulators.