Skip to main content

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 ChatWhat happensNeeds (PBX role of the person)
/call +52 55 1234 5678 or /call Ana RuizThe 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 cardThe same, for the caller on the card.self:call
/dnd on, /dnd offSwitches the person's do-not-disturb status (calls go to voicemail).an active PBX user with an extension
/presenceWho 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)
/onphoneThe Who's on the phone card.directory:read
/voicemailThe 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.

EventPosted whenOn the card
Missed callAn inbound call nobody answered ends.Caller, number called, time, Call back
VoicemailA 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 alertA 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, TranscriptThe AI summary of a recorded call is ready.The summary or transcript, Open in MonoPbx
Fax received, SMS receivedA 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.

  1. Create or pick a project in the Google Cloud console. Note its project number (Dashboard, Project info).
  2. Enable the Google Chat API: APIs and services, Library, Google Chat API, Enable.
  3. 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.
  4. 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 IDNameDescription
      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.

  5. 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.
  6. 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​

  1. 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.
  2. 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.
  3. Spaces per event: press Load spaces (the spaces the app was added to), choose a space for each event and Save.
  4. Send test message to a space to check the connection end to end.
  5. 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​

SymptomCheck
Test connection fails with auth_failedThe key file belongs to the project where the Chat API is enabled; the key was not deleted.
Load spaces is emptyThe app was not added to any space yet.
Commands do nothingAdmin > 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).