Google Chat
Post missed calls, voicemails, queue alerts, call summaries, faxes and SMS to Google Chat spaces, and let people work the phone from Chat: call a number or a colleague, switch do not disturb, see who is available and who is on the phone, and list new voicemails.
Open Admin > Integrations > Google Chat (/admin/integrations/google-chat). You need integrations:read to see it and integrations:write to change it. The user list on the page also needs users:read.
What people get in Chat
| In Chat | What happens | Needs (PBX role of the person) |
|---|---|---|
/call +52 55 1234 5678 or /call Ana Ruiz | The person's own phone rings first, then MonoPbx dials the number or the colleague's extension, through the normal dial plan and calling permissions. The call is audited (call.chat_click_to_call). | self:call (and directory:read for a name) |
| Call back on a missed-call or voicemail card | The same, for the caller on the card. | self:call |
/dnd on, /dnd off | Switches the person's do-not-disturb status (calls go to voicemail). | an active PBX user with an extension |
/presence | Who is available now, including Available on mobile (reachable through the mobile app), with a Who's on the phone button. | directory:read (a department-limited grant shows those departments) |
/onphone | The Who's on the phone card. | directory:read |
/voicemail | The person's new voicemails with the start of each transcript, a Call back button and a link to listen in the console. | an active PBX user |
A Chat user acts as the active PBX user with the same e-mail address. When two PBX users share an address, or nobody has it, Chat answers that the command cannot run. Answers in a shared space are private: only the person who asked sees them. In a direct message with the app you can also type the words without the slash (presence, dnd on, a phone number).
Notifications
Each event goes to the space you choose for it; an event without a space is not posted.
| Event | Posted when | On the card |
|---|---|---|
| Missed call | An inbound call nobody answered ends. | Caller, number called, time, Call back |
| Voicemail | A caller leaves a message (posted about 45 seconds later, so the transcript is ready). | Caller, mailbox, time, the first 300 characters of the transcript, Call back, Open in MonoPbx |
| Queue alert | A caller waits longer than the queue's service level target, a wait passes 2 minutes (or twice the target), or a caller hangs up while waiting. At most one alert per queue and reason every 10 minutes. | Queue, callers waiting, longest wait |
| AI summary, Transcript | The AI summary of a recorded call is ready. | The summary or transcript, Open in MonoPbx |
| Fax received, SMS received | A fax or an SMS arrives on a company number. The SMS text is not posted. | Sender, number, Open in MonoPbx |
The links point to https://<your PBX> (the server's public name).
Set up in Google Cloud (owner)
You do this once per Google Workspace. You need a Google Cloud project and a Workspace administrator.
- Create or pick a project in the Google Cloud console. Note its project number (Dashboard, Project info).
- Enable the Google Chat API: APIs and services, Library, Google Chat API, Enable.
- Create a service account: IAM and admin, Service accounts, Create service account (for example
monopbx-chat). No project roles are needed. Open it, Keys, Add key, JSON. Keep the downloaded file safe: it is the app's credential. - Configure the Chat app: APIs and services, Google Chat API, Configuration:
-
App name
MonoPbx, an avatar URL and a description. -
Functionality: Receive 1:1 messages and Join spaces and group conversations.
-
Connection settings: HTTP endpoint URL, then paste the address from the MonoPbx page (step 2 below),
https://<your PBX>/hooks/int/gchat/<install_key>. -
Authentication audience: Project number.
-
Slash commands (the IDs matter; MonoPbx also reads the command name):
Command ID Name Description 1 /callCall a number or a colleague 2 /dndDo not disturb on or off 3 /presenceWho is available 4 /voicemailMy new voicemails 5 /onphoneWho is on the phone -
Visibility: the people or groups of your domain who may use the app.
-
- Add the app to spaces: in Google Chat, open a space, Apps and integrations, Add apps, MonoPbx. The app can only post to spaces it was added to.
- Optional: publish the app to your domain in the Google Workspace Marketplace SDK so everyone can find it.
Screenshot placeholder: the Chat API configuration page with the HTTP endpoint and the slash commands.
Connect MonoPbx
- Connection: choose the service-account key file (JSON) and press Connect. MonoPbx stores the key sealed with the company's key, exchanges it for short-lived tokens itself (renewed before they expire) and tests the connection.
- Chat app address: enter the project number and press Create address. Copy the address into the Chat app's HTTP endpoint URL (step 4 above). MonoPbx accepts a request only when it carries a token Google signed for this project (
chat@system.gserviceaccount.com, checked against Google's published keys). If you set the audience to HTTP endpoint URL instead, create the hook endpoint under Admin > Webhooks > Inbound hooks with scheme Google Chat token and the endpoint URL as the secret. - Spaces per event: press Load spaces (the spaces the app was added to), choose a space for each event and Save.
- Send test message to a space to check the connection end to end.
- Who acts as whom: press Show to see which PBX users Chat users map to, whether their roles allow calls and which addresses are shared.
Screenshot placeholder: the Google Chat page of the console with the spaces per event.
Troubleshooting
| Symptom | Check |
|---|---|
Test connection fails with auth_failed | The key file belongs to the project where the Chat API is enabled; the key was not deleted. |
| Load spaces is empty | The app was not added to any space yet. |
| Commands do nothing | Admin > Webhooks > Inbound hooks: the delivery log shows each Chat request. A 401 in Google's logs means the audience or project number does not match. |
| "your chat e-mail address is not a MonoPbx user" | The person's Google address must equal their PBX user's e-mail (case does not matter) and be unique. |
| "your MonoPbx role does not allow it" | The person's PBX role lacks self:call or directory:read. |
Error codes: MPBX-INT-UPSTREAM (Google refused a console action), MPBX-INT-HOOK-UNAUTHORIZED (a request without a valid Google token).