Self-hosted guide
Self-host Google Chat.
Create your own Google Chat app and connect it securely to Just Arrived.
- Time
- About 25 minutes
- You need
- Google Workspace admin with access to Google Cloud Console
- Best for
- Organisations that cannot install the Marketplace app
- Updated
- 22 September 2026
Set it up
Create a Google Cloud project
Open console.cloud.google.com/projectcreate while signed in as a Google Workspace administrator. Give the project a name, make sure your organisation (your Workspace domain) is selected as the parent, and click Create. Wait for the notification that the project is ready, then pick it in the project selector at the top of the page. Everything in the following steps happens inside this project.Any project name works — the pictures use Your Company Chat. The name is only shown inside Google Cloud; your employees never see it.
Enable the Google Chat API
In the left menu choose APIs & Services → Library, search for "Google Chat API" and open it. Click Enable. When it has been enabled the blue button changes to Manage, as in the picture, and a green "API Enabled" tick appears.
Give the Chat app a name and avatar
Click Manage (or open APIs & Services → Enabled APIs & services → Google Chat API) and open the Configuration tab. Under Application info enter App name: Just Arrived, Avatar URL: https://justarrived.io/icon-512.png, and Description: Visitor arrival notifications. The App name is what your employees see in Google Chat, so keep it "Just Arrived" unless your organisation has a naming policy.Note the Project number (App ID) shown above the fields — you will need it again in step 9.
Switch on interactive features
Scroll down to Interactive features and switch on Enable Interactive features. Under Functionality tick Join spaces and group conversations.Join spaces and group conversations lets the app post arrival notices to a shared reception space later. Direct messages to hosts work regardless.
Connect the app to Just Arrived
Under Connection settings choose HTTP endpoint URL. Under Triggers keep "Use a common HTTP endpoint URL for all triggers" and enter exactly https://justarrived.io/api/public/gchat/events in the HTTP endpoint URL field. Leave Commands and Link previews empty.Google fills in the Service Account Email automatically — leave it as it is. Just Arrived only needs the endpoint URL.
Decide who can use the app, then save
Under Visibility tick Make this Chat app available to specific people and groups in <your organisation> and enter the email address of a Google Group that contains everyone who should receive arrival messages (for example all-staff@yourcompany.com). Individual addresses work too, separated by commas. Leave Log errors to Logging ticked. Click Save at the bottom of the page.Group changes can take up to 24 hours to take effect; individual addresses are immediate. Add your own address directly if you want to test straight away.
Create a service account
Just Arrived sends messages on behalf of your Chat app, and Google requires a service account for that. In the left menu choose IAM & Admin → Service Accounts → Create service account. Enter a name (the pictures use "Your Company Chat"); the ID fills in automatically. Skip the optional Permissions and Principals steps and click Create and close.The service account needs no roles — skip Permissions and Principals. Just Arrived only uses its key to send messages as your Chat app.
Download a JSON key for the service account
Open the service account you just created, go to the Keys tab, click Add key → Create new key, choose JSON and click Create. A file downloads to your computer; you will upload it to Just Arrived in step 10.Treat the key file like a password: it is the only copy, and anyone holding it can send messages as your Chat app. Delete the downloaded file once it has been uploaded in step 10.Add key greyed out? Your Google Cloud organisation blocks service-account keys (the policy isiam.disableServiceAccountKeyCreation). Ask your Google Cloud administrator to allow key creation for this project only.
Find the project number
In the left menu choose IAM & Admin → Settings and copy the Project number.Copy the Project number (11–12 digits), not the Project ID, which contains letters. It is the same number shown as App ID in step 3.
Enter the credentials in Just Arrived
In Just Arrived open Connections → Google Chat and choose the Advanced tab. Paste the project number from step 9, upload the JSON key file from step 8 (or paste its contents), and click Save credentials.Both values must come from the same Google Cloud project. Just Arrived checks the key immediately — Platform credentials shows OK when it is accepted.
Say hi, then test
In Google Chat, open Apps (or the "+" next to Direct messages), find Just Arrived and send it "hi". The app replies and links your account by email; the Connections page updates to show the installation. Ask each host to do the same. Then check in a test visitor on a kiosk with yourself as host: the message arrives in Google Chat within a few seconds, and your reply appears on the kiosk.Anyone who was not matched automatically can be linked under Connections → Google Chat → Link people manually, or by correcting their employee email so it matches Google Workspace. To switch Google Chat on for everyone at once: Employees → Select → Select everyone → Google Chat.
If something doesn’t work
The app doesn't appear in Google Chat
Visibility (step 6) does not include your account, or a group change is still propagating (up to 24 hours). Add your own address directly to test.
"Platform credentials" shows an error in Just Arrived
The JSON key belongs to a different project than the project number, or the key was deleted in Google Cloud. Check that both come from the same project (steps 8 and 9), or create a new key.
The app answers "hi" but arrivals never arrive
The host's Google Chat toggle is off on the Employees page, or the host has not yet messaged the app once. Both are visible under Connections → Google Chat → Matched hosts.
The workspace is unclaimed
Use Claim for this organisation on the Google Chat connection.
A person is unmatched
Use Link people manually or correct their employee email to match Google Workspace.