{"id":13747372,"url":"https://github.com/armilam/google-assistant-ruby","last_synced_at":"2025-05-09T08:32:35.622Z","repository":{"id":56874836,"uuid":"77558416","full_name":"armilam/google-assistant-ruby","owner":"armilam","description":"A ruby gem for creating Google Assistant actions","archived":false,"fork":false,"pushed_at":"2017-06-02T17:50:29.000Z","size":73,"stargazers_count":90,"open_issues_count":8,"forks_count":7,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-05-11T22:03:06.292Z","etag":null,"topics":["google-actions","google-assistant","google-assistant-ruby"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/armilam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-12-28T20:09:14.000Z","updated_at":"2024-01-09T23:16:49.000Z","dependencies_parsed_at":"2022-08-20T10:11:13.719Z","dependency_job_id":null,"html_url":"https://github.com/armilam/google-assistant-ruby","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armilam%2Fgoogle-assistant-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armilam%2Fgoogle-assistant-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armilam%2Fgoogle-assistant-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armilam%2Fgoogle-assistant-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/armilam","download_url":"https://codeload.github.com/armilam/google-assistant-ruby/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253025333,"owners_count":21842409,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["google-actions","google-assistant","google-assistant-ruby"],"created_at":"2024-08-03T06:01:26.653Z","updated_at":"2025-05-09T08:32:35.265Z","avatar_url":"https://github.com/armilam.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# Google Assistant Ruby\n\nWrite Google Assistant actions in Ruby.\n\nGoogleAssistant parses Google Assistant requests and provides the framework to respond appropriately. It works with the Google Assistant API v1.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```rb\ngem \"google_assistant\"\n```\n\n## Get started\n\n### Rails 4 and higher\n\nIn your routes file, allow a `POST` request to your action. All requests from Google Assistant will come here.\n\n```rb\nRails.application.routes.draw do\n  post \"/google_assistant\" =\u003e \"google_assistant#conversation\"\nend\n```\n\nWrite your controller to handle the request. Use GoogleAssistant to respond to the requests.\n\n```rb\nclass GoogleAssistantController \u003c ApplicationController\n\n  def conversation\n    assistant_response = GoogleAssistant.respond_to(params, response) do |assistant|\n      assistant.intent.main do\n        assistant.ask(\n          prompt: \"\u003cspeak\u003eHi there! Say something, please.\u003c/speak\u003e\",\n          no_input_prompt: [\n            \"\u003cspeak\u003eIf you said something, I didn't hear you.\u003c/speak\u003e\",\n            \"\u003cspeak\u003eDid you say something?\u003c/speak\u003e\"\n          ]\n        )\n      end\n\n      assistant.intent.text do\n        assistant.tell(\"\u003cspeak\u003eI can respond, too!\u003c/speak\u003e\")\n      end\n    end\n\n    render json: assistant_response\n  end\nend\n```\n\n## Usage\n\nGoogleAssistant parses the request from the Google Assistant API and helps you build your response. It takes the `params` and `response` objects in Rails and Sinatra.\n\n```rb\nassistant_response = GoogleAssistant.respond_to(params, response) do |assistant|\n  # Response logic goes here\nend\n```\n\nThe Google Assistant API sends a request using the `MAIN` intent for the initial request from the user. This is when the user says \"OK Google, talk to #{name_of_your_app}\".\n\n```rb\nassistant_response = GoogleAssistant.respond_to(params, response) do |assistant|\n  assistant.intent.main do\n    # Initial request's response goes here. You may want to introduce the app here.\n  end\nend\n```\n\nThe Google Assistant API sends a request using the `TEXT` intent for subsequent requests from the user. When your app asks for input from the user, the conversation continues. When the user finishes the conversation with \"Goodbye\" or your app finishes the conversation with a `tell` response, the conversation ends and any new conversations start again with the `MAIN` intent.\n\n```rb\nassistant_response = GoogleAssistant.respond_to(params, response) do |assistant|\n  assistant.intent.text do\n    # Respond to user input here.\n  end\nend\n```\n\n### Ask\n\nRequest user input by sending an `ask` response. Send a prompt and a set of follow-up prompts for when the user fails to respond.\n\n```rb\nassistant.intent.main do\n  assistant.ask(\n    prompt: \"\u003cspeak\u003eHi there! Say something, please.\u003c/speak\u003e\",    # The voice prompt the user will hear.\n    no_input_prompt: [\n      \"\u003cspeak\u003eIf you said something, I didn't hear you.\u003c/speak\u003e\", # You can provide a number of \"no input prompts\". A random\n      \"\u003cspeak\u003eDid you say something?\u003c/speak\u003e\"                     # one will be spoken if the user takes too long to respond.\n    ]\n  )\nend\n```\n\n### Tell\n\nSend a final response, ending the conversation.\n\n```rb\nassistant.intent.text do\n  assistant.tell(\"\u003cspeak\u003eThanks for talking! Goodbye!\u003c/speak\u003e\")   # Both SSML and plain text work here and anywhere you send a prompt.\nend\n```\n\n### SSML\n\nSSML is Google Assistant's markup language for text to speech. It provides options to pause, interpret dates and numbers, and more. You can provide SSML responses or plain text. See [Google's documentation on SSML](https://developers.google.com/actions/reference/ssml).\n\n### User input\n\nGoogleAssistant allows you to read the user's input using `assistant.arguments` so that you can respond appropriately.\n\n```rb\nassistant.intent.text do\n  case assistant.arguments[0].text_value.downcase\n  when \"hello\"\n    respond_with = \"Hi there!\"\n  when \"goodbye\"\n    respond_with = \"See you later!\"\n  else\n    respond_with \"I heard you say #{assistant.arguments[0].text_value}, but I don't know what that means.\"\n  end\n\n  assistant.tell(respond_with)\nend\n```\n\n### Conversation state and data\n\nYou can keep data on the Conversation object. This data will be sent to the Google Assistant API, which will return that data back when the user responds. This way, you can keep ongoing information about the conversation without having to use a database to store that information.\n\nYou can also send a state value with your responses to keep track of where your conversation is at.\n\n```rb\nGoogleAssistant.respond_to(params, response) do |assistant|\n  assistant.intent.main do\n    assistant.conversation.state = \"asking favorite color\"\n\n    assistant.ask(\n      prompt: \"What is your favorite color?\",\n      no_input_prompt: [\"What did you say your favorite color is?\"]\n    )\n  end\n\n  assistant.intent.text do\n    if assistant.conversation.state == \"asking favorite color\"\n      assistant.conversation.data[\"favorite_color\"] = assistant.arguments[0].text_value\n\n      assistant.conversation.state = \"asking lucky number\"\n\n      assistant.ask(\n        prompt: \"What is your lucky number?\",\n        no_input_prompt: [\"What did you say your lucky number is?\"]\n      )\n    elsif assistant.conversation.state == \"asking lucky number\"\n      favorite_color = assistant.conversation.data[\"favorite_color\"]\n      lucky_number = assistant.arguments[0].text_value\n\n      assistant.tell(\"Your favorite color is #{favorite_color} and your lucky number is #{lucky_number}. Neat!\")\n    end\n  end\nend\n```\n\n### User ID\n\nYou can get the user's ID. This will allow you to identify the user across conversations. It works much in the same way a cookie might work; it is possible for the user to reset that ID, so don't rely on it too much.\n\n```rb\n# Get the user's ID\nassistant.user.id\n```\n\n### Permissions\n\nYou can request information about the user and their device. Google handles collecting this information, but you can provide a prompt to let the user know why you need this information. The Google Assistant API responds with the `permission` intent after a permission request.\n\n#### Name\n\nRequest the user's name. This will result in a prompt to the user like:\n\u003e So that I can address you by name, I'll just need to get your name from Google. Is that ok?\n\n```rb\nassistant.intent.main do\n  # Request the user's name\n  assistant.ask_for_permission(context: \"So that I can address you by name\", permissions: GoogleAssistant::Permission::NAME)\nend\n\nassistant.intent.permission do\n  if assistant.permission_granted?\n    # Get the user's name from the response\n    given_name = assistant.user.given_name\n    family_name = assistant.user.family_name\n    display_name = assistant.user.display_name\n  else\n    # The user denied permission\n  end\nend\n```\n\n#### Coarse Location\n\nRequest the device's zip code and city. This will result in a prompt to the user like:\n\u003e To provide weather information for where you live, I'll just need to get your zip code from Google. Is that ok?\n\n```rb\nassistant.intent.main do\n  # Request the device's zip code and city\n  assistant.ask_for_permission(context: \"To provide weather information for where you live\", permissions: GoogleAssistant::Permission::DEVICE_COARSE_LOCATION)\nend\n\nassistant.intent.permission do\n  if assistant.permission_granted?\n    # Get the device's location from the response\n    zip_code = assistant.device.zip_code\n    city = assistant.device.city\n  else\n    # The user denied permission\n  end\nend\n```\n\n#### Precise Location\n\nRequest the device's precise location. This will result in a prompt to the user like:\n\u003e So that I can find out where you sleep at night, I'll just need to get your street address from Google. Is that ok?\n\n```rb\nassistant.intent.main do\n  # Request the device's precise location\n  assistant.ask_for_permission(context: \"So that I can find out where you sleep at night\", permissions: GoogleAssistant::Permission::DEVICE_PRECISE_LOCATION)\nend\n\nassistant.intent.permission do\n  if assistant.permission_granted?\n    # Get the device's location from the response\n    zip_code = assistant.device.zip_code\n    city = assistant.device.city\n    formatted_address = assistant.device.formatted_address\n    latitude = assistant.device.latitude\n    longitude = assistant.device.longitude\n  else\n    # The user denied permission\n  end\nend\n```\n\n### Testing your assistant\n\nYou can use any hosting platform.\n\n1. [Download the `gactions` CLI](https://developers.google.com/actions/tools/gactions-cli) and add it to your PATH.\n    - Or if you'd rather not put it in your path, you'll simply need to call it by referencing its full path.\n2. Visit the [Google Cloud Console projects page](https://console.cloud.google.com/project). Create a project and make note of the project ID for configuration and deployment.\n3. Deploy your app to the web. Heroku is a good choice. See [Heroku's documentation](https://devcenter.heroku.com/articles/getting-started-with-ruby#introduction) for more info on how to do this.\n4. Add an `action.json` file at the root of your project.\n\n    ```json\n    {\n      \"versionLabel\": \"1.0.0\",\n      \"agentInfo\": {\n        \"languageCode\": \"en-US\",\n        \"projectId\": \"your-google-project-id\",\n        \"voiceName\": \"male_1\"\n      },\n      \"actions\": [\n        {\n          \"initialTrigger\": {\n            \"intent\": \"assistant.intent.action.MAIN\"\n          },\n          \"httpExecution\": {\n            \"url\": \"https://yourapp.domain.com/path-to-your-assistant\"\n          }\n        }\n      ]\n    }\n    ```\n\n5. Run the following command from the root directory of your project. The `invocation_name` is what you will use to activate your assistant. For example, \"OK Google, talk to my action\". Name it something unique.\n\n    ```\n    gactions preview -action_package=action.json -invocation_name=\"my action\"\n    ```\n\n    - `gactions` will ask to access your account and Google developer project. Follow the onscreen instructions to do so.\n\n6. Use the [web simulator](https://developers.google.com/actions/tools/web-simulator) to simulate. Or better yet, if your Google Home device is logged into the same account you're using to build your action, you can say \"OK Google, talk to my action\" to test it out directly on your device.\n\n## Authentication\n\nYou can require users to log in to your service before using your assistant. Read about it in [Google's documentation](https://developers.google.com/actions/develop/identity/oauth2-code-flow). The basic flow is this:\n\n1. User tries to talk to your assistant\n2. Google tells the user they need to sign in, which they can do via the Home app on their phone\n3. The Home app links the user to your Oauth endpoint\n4. User signs in to your app\n5. Google stores the user's Oauth access and refresh tokens\n6. For each subsequent request the user makes to your assistant, Google sends the user's access token so you can identify the user\n\nIn order to set this up in your assistant, the basic instructions are as follows. Read Google's documentation for the full details.\n\n1. Implement Oauth in your application\n2. Set up an Oauth client in the [Google Developer Console](https://console.developers.google.com)\n3. In the application's `action.json` file, set up account linking according to [Google's Instructions](https://developers.google.com/actions/develop/identity/account-linking#enabling_account_linking)\n4. Use `assistant.user.access_token` to identify the user\n\n## More information\n\nCheck out Google's instructions at https://developers.google.com/actions/develop/sdk/getting-started for more detail on writing and testing a Google Assistant action.\n\nCheck out https://github.com/armilam/google_assistant_example for a simple example of this gem in action.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farmilam%2Fgoogle-assistant-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farmilam%2Fgoogle-assistant-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farmilam%2Fgoogle-assistant-ruby/lists"}