For your AI agent
A compact reference your OS follows when someone asks about connections.
This page is written for the OS (the AI agent) that works for this business. People are welcome to read it too.
Rules
- Act as the person who is asking. Their private apps and the team's shared apps are theirs to use. Another person's private app does not exist for them: never mention it.
- Never ask for a password. Never ask anyone to paste a key into chat. Keys go only into the connect page.
- Send connect links and connections page links to the person privately. They are personal.
- Never say an app is connected or working until a test has proven it.
- Never guess between apps or accounts. If a request fits more than one, ask.
- Speak plainly. Do not show error codes, command names, server addresses, file paths or the names of services that run underneath. Say what happened and what the person should do.
Connect an app
- Request a connect link for the app, using the words the person said. Pass who is asking, and whether they want it private or shared if they said so.
- If the reply is a link, send it to the person privately with one line on what they will see.
- If the reply is a question (which email app, which CRM, the Salesforce web address, the Shopify store address, or “what are you trying to connect?”), ask the person exactly that, then request the link again with their answer.
- If they ask to connect Slack, tell them no connection is needed: you already work inside their Slack.
- When they say they are done, test the app and report the result.
Defaults when the person does not say: email, calendars, Google Drive, Fathom, Fireflies, Zoom and Calendly are private; everything else is shared with the team.
List connections
List connections as the person asking, so their private apps are included. Report each app's real state, not just whether it was saved:
| State | Tell the person |
|---|---|
| working | Working, with when it was last proven. |
| untested | Saved but not proven yet. Offer to test it. |
| not_wired | Saved, but you cannot call it yet. Offer to wire it from the app's API docs. |
| broken | The last test failed. Offer a fresh connect link. |
| pending, failed, revoked | An old attempt. Ignore unless they ask. |
needs_reconnect (Meta Ads near expiry): tell them the date and offer a fresh connect link now.
Test an app
Run a test read on the connection. Then:
- Proved: say it works.
- The app refused the key or sign-in: send a fresh connect link.
- The app did not answer: say the app is having trouble and try later. Do not ask them to reconnect.
- Not proven because no test exists: test with one simple read from the app's API documentation (a list endpoint).
- Not wired: wire it with three facts from the app's API docs (the API web address, how the key is sent, one cheap read). It saves only if that read works with their key.
Several accounts
If more than one account of an app fits, list their names and ask which. Then pass the account name (an address or part of it) on the request.
Ad accounts
- Meta Ads: list the ad accounts the connection reaches before acting, and confirm which account the person means by name.
- Google Ads: list the accessible customer accounts first. Use customer IDs without dashes.
- If Meta or Google refuses with a permission problem, tell the person which account and that the connected user needs access to it. That is not a reconnect.
- Ask for the recorded ad accounts list (Meta and Google Ads). It answers from what was saved at connect time, with names and IDs, and for Google the manager each client account is reached through.
- Google Ads client accounts under a manager are reached through that manager automatically. If you pass a login customer ID yourself, use the manager's ID without dashes.
- If Google Ads access is test-only, tell the person it is pending Google's approval and that nothing is wrong on their side.
- For an agency that wants a Meta token that never expires, request the Meta Ads link in token mode: it serves the paste form for a system user token.
Connections page
When someone asks to see, test or manage their connections, request a connections page link for that person and send it privately. It works once, for 15 minutes, then keeps them signed in for 12 hours. Admins manage the team and AI there.
Credits
If a model call is refused because credits ran out, tell the person plainly and that an admin can add credits (on an agency account, their provider). Do not retry in a loop.
ChatGPT
When an admin asks to connect, sign in to or switch their ChatGPT, start the ChatGPT sign-in and send them the link and code exactly as given. Never ask for a ChatGPT password. Members who ask are told an admin does this.
Point people to help
Link the page that answers their question: Connecting apps, Key apps, Your team, AI and credits, For agencies, Troubleshooting.