Skip to main content

Global Integrations

Global Integrations allow your organization to securely connect external tools, social media platforms, email providers, and communication channels to Orbit Resolve.

By configuring integrations at the Global (Organization) Level, you establish default connections that are made available to all projects by default unless overridden. This means an administrator only needs to authenticate a corporate Gmail or Slack workspace once, and project teams can immediately consume those connections for automated emails, ChatOps, or social media publishing.

1. Navigating to Integrations​

To access Global Integrations:

  1. Open the Orbit Command Center (Cockpit).
  2. Navigate to Settings (or Organization Settings).
  3. Select the Integrations tab.

The visible URL for this page is: /org/settings?tab=integrations

The main Integrations dashboard showing various connection providers and their current status.

The Integration Lifecycle​

Understanding how an integration moves from disconnected to active is crucial:

  1. Choose Provider: An admin selects a provider (e.g., Slack or Gmail).
  2. Authorization: The admin completes an OAuth flow (logging into the provider) or enters manual API credentials.
  3. Scopes Granted: Orbit requests strict permissions (e.g., Mail.Send).
  4. Account Stored: The backend securely stores the OAuth tokens or encrypted credentials.
  5. Resources Synced: Sub-resources (like Facebook Pages, WhatsApp Phone Numbers, or specific email addresses) are mapped.
  6. Consumption: Other features in Orbit (like VOX Telephony, Marketing Analytics, or Automated Notifications) securely use these connections to perform actions on your behalf.

2. Supported Providers​

Based on Orbit's architecture, providers fall into three categories: OAuth (requires login), Credentials (requires API keys/passwords), and Webhook (configured elsewhere).

OAuth Providers (Click to Connect)​

  • LinkedIn Company: Connects your corporate LinkedIn page. Used for social media publishing and marketing analytics. Requests scopes for reading pages and posting.
  • Facebook Pages: Connects business pages. Used for publishing and social analytics.
  • Facebook Ads: Connects ad accounts. Used for ad campaign management and performance tracking.
  • WhatsApp Business: Connects a WABA (WhatsApp Business Account) and its associated phone numbers. Used for conversational AI, marketing broadcasts, and VOX Telephony.
  • Office 365 Outlook: Connects Microsoft email accounts. Used for sending automated project emails, calendar invites, and parsing intake forms.
  • Gmail: Connects Google Workspace email accounts for outbound mailing and calendar sync.
  • Jira: Connects Atlassian Jira workspaces. Requests scopes like read:jira-work and write:jira-work to sync tickets and project tasks.

Credential Providers (Manual Form)​

  • Custom SMTP: A generic email provider. Instead of a popup login, this opens a secure modal where you must provide a Host, Port, Username, and Password to connect custom mail servers.

Webhook Providers​

  • Slack / Microsoft Teams: If a provider is listed but clicking "Connect" shows a message like "Configured per-channel in Resolve → Settings → ChatOps," it means the integration relies on incoming webhooks rather than a central OAuth token.

3. Connected Accounts Hierarchy​

An integration doesn't just represent "one thing." A single authentication can grant access to multiple sub-resources.

When you expand the Connected Accounts dropdown (using the chevron icon), you will see the exact hierarchy returned by the provider:

Expanding a connected provider reveals the hierarchy of accessible resources.

Hierarchy Examples:

  • WhatsApp Business: OAuth Connection → WABA (Business Account) → Phone Numbers (e.g., "1 WABA • 4 Phone Numbers")
  • Facebook: OAuth Connection → Business Manager → Facebook Pages (e.g., "1 Business • 8 Pages")
  • Email (Gmail/O365): OAuth Connection → Specific Email Addresses

Project vs. Global Badges​

Inside the expanded list, each connection carries a badge:

  • 🌐 GLOBAL — Created here in Organization Settings. Available to everyone.
  • 📁 PROJECT — A project manager created this connection locally inside their project. It overrides the global default for that specific project.

4. Field & Action Documentation​

  • Action: Filter categories by name or key...
  • What it does: Instantly filters the visible integration cards. It searches against both the provider name (e.g., "Outlook") and the internal system key. It is case-insensitive.

Connect / Add Another Account​

  • What it does: Initiates the connection flow. If the provider is NOT_CONNECTED, the button says Connect. If already connected, it says + Add Another Account (allowing multiple authenticated workspaces simultaneously).
  • What happens: For OAuth, it opens a secure popup window. For Credentials, it opens a configuration modal.

Edit Connection (Pencil Icon)​

  • When it appears: Only on Credential-based integrations (like Custom SMTP).
  • What it does: Opens the configuration modal.
  • Security Note: Sensitive fields (like passwords) are hidden. If you leave the password field blank during an edit, the backend will safely preserve the existing password.

Test Email / Invite (Flask Icon)​

  • When it appears: On Email/Calendar integrations (Office 365, Gmail, Custom SMTP).
  • What it does: Opens a testing panel on the right side of the screen.
  • Fields:
    • Recipient Email (Required): Where to send the test.
    • Subject: Defaults to "Test Email from OptimaOrbit".
    • Email Body: The content of the test message.
  • What happens: Sends a live test payload (POST /org/integrations/{id}/action). A green success banner confirms if the provider accepted the email.

Disconnect (Trash Icon)​

  • What it does: Permanently removes the OAuth token or credentials for a specific account.
  • Warning: If VOX agents or Project notifications are relying on this specific connection, those automated features will fail until a new account is connected.

5. Connecting Custom SMTP (Credential Example)​

When you click Connect on a Credential provider like Custom SMTP, the Dynamic Integration Modal appears.

The Dynamic Integration Modal for Credential-based providers.

Configuration Fields​

  • Connection Name (Optional): A human-readable label (e.g., "Marketing Sendgrid").
  • Host (Required): The SMTP server address (e.g., smtp.sendgrid.net).
  • Port (Required): The server port, typically 465 (SSL) or 587 (TLS).
  • Username (Required): Your API key or login email.
  • Password (Required on creation): Your secure credential. Hidden behind a visibility toggle.
  • Encryption Type: Dropdown selecting None, SSL, or STARTTLS.

What happens next? Clicking Connect Integration submits the payload to the backend. The UI will show a spinning "Saving..." state. Upon success, a green toast notification appears, the modal closes, and the new connection appears in the list.

6. The OAuth Data Flow & Mechanics​

Orbit utilizes a sophisticated window-messaging system for OAuth providers (like Office 365 or LinkedIn).

  1. Initialization: Clicking Connect triggers GET /org/config/integrations/auth-url. The backend generates a secure authorization URL containing a state parameter.
  2. Popup Authorization: A popup window opens to the provider (e.g., Microsoft). You log in and grant the requested scopes.
  3. The Callback: The provider redirects the popup back to Orbit's callback URL (/api/v1/org/integrations/callback).
  4. Message Passing: The popup securely passes an OAUTH_CALLBACK message back to the main Orbit window using window.postMessage.
  5. Completion: The main window receives the success status, automatically closes the popup, and refreshes the integration list to display the newly connected account.

(Note: If the popup is accidentally closed prematurely, the connection is safely cancelled with no corrupted data).

⚠️ Special Requirement: Office 365 & Azure Admin Consent​

The implementation includes a specific warning for Office 365. Because Orbit requests deep access (Offline_access, User.Read, Mail.Send, Calendars.ReadWrite), Microsoft requires an Azure Organization Admin to grant "Admin Consent". If a non-admin attempts to connect Office 365 globally without this Azure-side configuration, Microsoft will block the connection with an "Admin Approval Required" error.

7. Downstream Impact​

Once connected here, these global integrations fuel features across the entire Orbit ecosystem:

  1. VOX Telephony / AI Agents: Connected WhatsApp numbers become available in the AI & Intelligence → VOX Telephony tab to attach AI voice/text agents to real phone numbers.
  2. Marketing Analytics: Connected Facebook and LinkedIn pages feed real-time engagement data into the organization's cross-project dashboards.
  3. Notification Routing: Connected Email (Gmail/O365/SMTP) accounts are consumed by the Notification Routing engine to dispatch automated project alerts and customer invitations.

8. Failure & Edge Cases​

  • Popup Blocked: If a browser blocks the OAuth popup, Orbit displays a red error: "Popup blocked. Please allow popups for this site." You must whitelist the domain.
  • Token Expiration/Revocation: If a user logs into LinkedIn and manually revokes Orbit's access, the integration will remain visibly "CONNECTED" in the UI, but downstream actions (like publishing) will fail with a 401 error. You must click Disconnect and reconnect.
  • Test Email Failure: If SMTP credentials are wrong, the Test Email panel will gracefully catch the backend error and display a red "Connection test failed" alert inline, rather than crashing the page.