> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect Zendesk, Jira, Calendly, DocuSign, Slack, Zapier, and n8n
> One connect-and-activate runbook per integration: prerequisites, the Connect click, field mapping and scope, a test-send verify, and the failure modes operators actually hit.
# Connect Zendesk, Jira, Calendly, DocuSign, Slack, Zapier, and n8n
Five of these integrations connect the same way — Zendesk, Jira, Calendly, DocuSign, and Slack each run the same loop: **Connect → syncs activate → verify one record → troubleshoot.** Zapier and n8n take a different route: you download a per-tenant app definition from **Developer → Connectors** and authenticate it with your own API key. This page is the numbered runbook for all seven.
The endpoint map behind every step below is [`/api-reference/integrations`](/api-reference/integrations) — this page is the "do this, then this" walkthrough for the same surface.
## Prerequisites (all seven)
1. An **owner or admin role** on your Orbit organization — connect and disconnect are the only tenant-owned controls that touch provider credentials.
2. An Orbit API key with the `integrations:write` scope, and `integrations:read` for the status checks. Connect via API with `POST /api/v1/integrations/connect` — the dashboard's Connect button calls the same route.
3. A working account on the provider side, with one provider-specific prerequisite per section below.
OAuth flows (Zendesk, Jira, Calendly, DocuSign, Slack) open the provider's consent screen and store the resulting tokens on Orbit's encrypted connection record. Zapier and n8n skip OAuth entirely — you authenticate the downloaded app with your own `dv_live_sk_…` API key instead. No step in this page asks you to paste a provider credential into a plain-text field.
***
## Zendesk — tickets and end-users into Orbit
**What it does end to end.** Connecting Zendesk starts two syncs: **tickets** (Zendesk tickets land on the linked Orbit contact's timeline) and **users** (Zendesk end-users import as Orbit contacts). From then on, ticket state and requester history sit next to every messaging channel in the inbox.
### Step 1 — Connect and authorize
1. In Orbit, go to **Settings → Integrations** and find Zendesk.
2. Click **Connect**, sign in to Zendesk, and authorize the requested scopes.
3. Back on the integrations page, Zendesk flips from Not connected to Connected once the token exchange completes.
### Step 2 — How the data maps
| Zendesk object | Lands in Orbit as | Notes |
| -------------- | ------------------------------------------------------------------- | ------------------------------------------------- |
| Ticket | A ticket entry on the linked contact's timeline and in Customer 360 | Linked through the requester's imported user |
| End-user | An Orbit contact | Updates re-sync and converge on the same contact |
| Requester | Contact linkage on each ticket | Tickets join to contacts by the requester mapping |
Re-running Connect is safe — re-syncs converge on the same ticket and contact rows, never duplicates.
Create one test ticket in Zendesk with a known requester email, wait for the sync, then open the matching Orbit contact. The ticket should appear on the contact's timeline and in Customer 360.
### Step 3 — Troubleshooting
| Symptom | Cause | Fix |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Connected, but no tickets appear | Sync still catching up on the first run, or the new ticket post-dates the last sync | Wait for the next sync, then re-check the contact timeline. An initial backfill takes longer than incremental runs. |
| `403` when the API starts OAuth | API key missing `integrations:write`, or the caller is not an owner/admin | Mint or promote the key under Settings → API Keys, or use the dashboard Connect button as an owner/admin. |
| Ticket exists in Zendesk but never shows on a contact | The requester was never imported as an end-user | Confirm the user actually exists as a Zendesk end-user, then re-check after the next sync run. |
| Consent screen succeeds but the card stays Not connected | Token exchange failed on the provider side | Re-run Connect — the flow retries the exchange and re-confirms in place. |
***
## Jira — issues linked to conversations
**What it does end to end.** Connecting Jira starts three syncs: **projects**, **issues**, and **users**. Jira issues then surface inside the Orbit inbox, so an agent can attach the exact issue a customer is asking about to the conversation — and an AI agent can open or update an issue on behalf of a rep.
### Step 1 — Connect and authorize
1. Have your Atlassian Cloud site URL ready.
2. In Orbit, go to **Settings → Integrations**, find Jira, and click **Connect**.
3. Sign in to Atlassian, authorize the requested scopes (Atlassian asks you to pick the Jira site during consent), and return to the integrations page.
### Step 2 — How the data maps
| Jira object | Lands in Orbit as | Notes |
| ----------- | ------------------------------------------------- | ----------------------------------------- |
| Issue | A linkable issue in the inbox side-panel | Agents attach it to the open conversation |
| Project | The issue groupings filters show | Pick the right project when linking |
| User | Assignee and reporter identities on linked issues | Keeps issue ownership readable |
Open any inbox conversation, open the Jira side-panel, and attach one existing issue from a synced project. The issue should display its key, summary, and status on the conversation.
### Step 3 — Troubleshooting
| Symptom | Cause | Fix |
| -------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `JIRA_OAUTH_ERROR` on the consent screen | Authorization declined, or the wrong Jira site was picked | Restart the flow from Settings → Integrations and pick the site your team actually uses. |
| Jira Cloud site missing in consent | No product-access on that site for the authorizing account | Connect from an Atlassian account that holds product access to the site. |
| No issues offer themselves when linking | The site check is right but projects have not synced yet | Confirm the site URL, then wait for the project/issue sync to complete. |
| Data stops refreshing after a password or rotation event | The OAuth token expired | Re-run Connect — reconnecting refreshes the stored token in place. |
***
## Calendly — booking events that trigger messaging flows
**What it does end to end.** On connect, Orbit runs `integrations/calendly/connect-complete`: it reads your Calendly user and organization URIs, registers a webhook subscription on Calendly pointing at Orbit's receiver (`POST /api/v1/integrations/webhooks/calendly?org=`), and stores the signing key on your connection record so inbound events verify by HMAC. Every `invitee.created` and `invitee.canceled` event then upserts an Orbit contact (linked on the invitee URI) and dispatches a tenant webhook `calendly.invitee.created` / `calendly.invitee.canceled`, which your booking flows — SMS/WhatsApp reminders, no-show recovery, reschedule links — consume.
### Step 1 — Connect and authorize
1. In Orbit, go to **Settings → Integrations**, find Calendly, and click **Connect**.
2. Sign in to Calendly and authorize the requested scopes.
3. Return to the integrations page — the connect-complete step runs automatically once the OAuth callback lands.
### Step 2 — How the data maps
| Calendly object | Lands in Orbit as | Notes |
| --------------- | ------------------------------------------------------------------ | ----------------------------------------------- |
| Invitee | An Orbit contact (`provider: calendly`, linked on the invitee URI) | The same invitee re-syncs onto the same contact |
| Scheduled event | Recorded onto the contact's Calendly attributes | Drive your reminder and no-show flows off it |
| Cancellation | Recorded onto the same contact's attributes | Use it to gate no-show recovery |
The webhook receiver deduplicates deliveries per event, so Calendly's retry bursts never duplicate the tenant webhook. The raw payload lands in the `calendly_webhook_events` audit log for the tenant.
Book a real test meeting on a Calendly event type your account owns with a test email. The invitee should appear as an Orbit contact, and a `calendly.invitee.created` tenant webhook should fire on your configured outbound webhook endpoint.
### Step 3 — Troubleshooting
| Symptom | Cause | Fix |
| ------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `503` on the webhook receiver | Calendly subscription not registered for this tenant | Re-run the connect-complete step (re-run Connect); the receiver fails closed with `Calendly webhook subscription is not registered for this tenant` until the signing key is stored. |
| Events arrive but the signature rejects | Stored signing key drifted from Calendly's current one | Re-run Connect — it re-registers and refreshes the stored signing key in place. |
| New bookings create no contacts | Receiver registered but the subscription was removed on the Calendly side | Re-run Connect — setup lists your existing subscriptions and re-registers idempotently, so reconnecting never double-subscribes. |
| Tenant webhook never fires on your endpoint | Your `webhooks` endpoint is not subscribed to the `calendly.*` verbs | Add the verbs to the webhook subscription under Settings → Webhooks. |
***
## DocuSign — envelope events and signer notifications
**What it does end to end.** Connecting DocuSign starts two syncs: **envelopes** and **recipients**. Recipients — signers, cc'd parties, agents — project into the Orbit contacts table, so an envelope's signer becomes a contact whose timeline carries the envelope state. Orbit can then push signer notifications onto SMS and WhatsApp instead of leaving delivery to DocuSign's email-only channel, and envelope status tracks alongside the rest of the contact's conversation history.
### Step 1 — Connect and authorize
1. Have a DocuSign account with API access.
2. In Orbit, go to **Settings → Integrations**, find DocuSign, and click **Connect**.
3. Sign in to DocuSign, authorize the requested scopes, and return to the integrations page.
### Step 2 — How the data maps
| DocuSign object | Lands in Orbit as | Notes |
| ----------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------- |
| Envelope | Envelope status visible alongside the contact's conversation history | Sent, delivered, signed, completed |
| Recipient (signer, cc, agent) | An Orbit contact | Recipients converge on the same contact across envelopes |
| Signer | The notified party when the SMS/WhatsApp flow is enabled | Signer-notification flow targets this contact |
Send a test envelope to an email and phone you control, wait for the recipient sync, then open the matching Orbit contact. The envelope status should appear on the contact, and (with the signer-notification flow enabled) an SMS or WhatsApp nudge should go out on the envelope event.
### Step 3 — Troubleshooting
| Symptom | Cause | Fix |
| -------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| No recipients import as contacts | Recipients only project after the first envelopes sync completes | Wait for the recipient sync to finish, then re-check a known signer. |
| Connected, but envelope status never updates | Consent completed but the sync hasn't run yet for a new account | Check `GET /api/v1/integrations` for the connection state; DocuSign syncs on the same hourly cadence as the other providers. |
| Signer never receives the SMS/WhatsApp nudge | The signer-notification flow is not enabled on the integration card | Enable it in the DocuSign integration's settings after connecting. |
| DocuSign scopes change mid-integration | The consent screen no longer reflects the granted set | Re-run Connect — reconnecting re-issues consent and refreshes the token in place. |
***
## Slack — real-time alerts and reply-from-thread
**What it does end to end.** Connecting Slack installs the Orbit app into your workspace and syncs **channels**. From then on, the integration routes Orbit alerts — new conversations, campaign completion, SLA breaches — to a Slack channel you pick, and an agent can reply to a customer conversation directly from its Slack thread.
### Step 1 — Connect and authorize
1. In Orbit, go to **Settings → Integrations**, find Slack, and click **Connect** to start Orbit's Slack install flow.
2. Choose your Slack workspace and authorize the requested channels and scopes.
3. Return to the integrations page — the Orbit app installs into the workspace on the OAuth callback.
### Step 2 — Pick the notification channel and map events
The integration card's settings expose one channel picker and three independent toggles:
| Event | Default | Toggle |
| ------------------------------------ | ------- | ----------------------- |
| New conversation | On | New conversation alerts |
| Campaign completion | On | Campaign alerts |
| SLA breach (about-to-breach warning) | On | SLA alerts |
Replies from a Slack thread flow back onto the linked conversation in the Orbit inbox — writeback failures are logged and audited but never block the primary send.
Send yourself an inbound test message that opens a conversation, and confirm a new-conversation alert lands in the channel you picked. Reply from the Slack thread — the reply should appear on the conversation in the Orbit inbox.
### Step 3 — Troubleshooting
| Symptom | Cause | Fix |
| ----------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Alerts stop after a workspace admin removes the app | The workspace revoked the install | Re-run the install flow from Settings → Integrations. |
| Nothing posts into the chosen channel | The Orbit app is not a member of that channel | Invite the app (`/invite @orbit`) in Slack, or pick a public channel on the integration card. |
| `invalid_auth` on the callback | The workspace token is no longer valid | Reconnect — reconnecting refreshes the stored token in place. |
| SLA alerts missing but new-conversation alerts arrive | The SLA toggle is off | Enable the SLA toggle in the integration's settings. |
For the operator runbook on inbound threads and reply-from-Slack once connected, see [Slack onboarding](/guides/slack-onboarding).
***
## Zapier — a per-tenant app definition you push yourself
**What it does end to end.** Orbit does not connect to Zapier over OAuth. The **Developer → Connectors** page generates a ready-to-publish Zapier app definition, pre-wired to your tenant's API host, authenticated with your own secret API key. From then on, Zapier exposes the same trigger catalog Orbit webhooks emit and the same action set Orbit's public API accepts — no new auth, scopes, or provider routing.
### Step 1 — Create the API key
1. Open **Settings → API Keys** and generate a secret key (`dv_live_sk_…`).
2. Keep it somewhere safe — you paste it into Zapier once, after import. Use a dedicated key per tool so rotating or revoking one integration does not break others.
### Step 2 — Download and import the app
1. Open **Developer → Connectors** and download the Zapier app definition (`orbit-.zapier-app.json`).
2. Push it with the Zapier Platform CLI:
```bash theme={null}
npm install -g zapier-platform-cli
zapier login
zapier push
```
3. When Zapier asks for the API key, paste your `dv_live_sk_` secret. The bundled authentication test calls `GET /api/v1/me` with your `X-API-Key` header, so Zapier verifies the key before a Zap runs.
### Step 3 — Wire a Zap and verify
Each trigger (New Inbound Message, Message Delivered, Message Failed, New Contact, Contact Updated, Call Completed, Verification Approved, Campaign Completed) subscribes a REST hook via `POST /webhooks` and tears it down via `DELETE /webhooks/:id` — the same webhook CRUD the dashboard uses. Actions (Send SMS, Send WhatsApp Message, Send Email, Create Contact, Create Voice Call, Start Verification) POST to the matching `/api/v1` endpoint.
Build a one-step Zap with the New Inbound Message trigger, then send an inbound message to one of your numbers. The Zap should fire within seconds and show the message payload in Zapier's task history.
### Step 4 — Troubleshooting
| Symptom | Cause | Fix |
| --------------------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| Zapier rejects the key at connect time | The API key is wrong, revoked, or lacks the webhook CRUD it needs | Mint a fresh `dv_live_sk_` key and re-auth the app with it. |
| Triggers subscribe but never fire | The webhook was created in Orbit but your Zap is paused, or the event never occurred | Check the webhook subscription under Settings → Webhooks, and confirm the Zap is on in Zapier. |
| Deleted Zaps leave orphaned Orbit webhooks | Deleting a Zap does not call `DELETE /webhooks/:id` | Remove the webhook under Settings → Webhooks — the trigger's teardown only runs on Zap disable, not delete. |
| Rotating the API key breaks every Zap at once | All Zaps keyed on the same secret | Use a dedicated key per tool, and update it once in Zapier's app settings. |
For the full catalog plus the Make and n8n siblings, see [Connector downloads](/guides/connectors-download).
***
## n8n — the community node pack for self-hosted and Cloud
**What it does end to end.** Like Zapier, n8n skips OAuth. **Developer → Connectors** generates the definition behind the `n8n-nodes-orbit` community node pack — an Orbit trigger node plus send/create action nodes, authenticated with your Orbit API key. Teams that already run n8n get first-class Orbit nodes instead of hand-wired HTTP requests.
### Step 1 — Create the API key
Same as Zapier — one dedicated `dv_live_sk_` secret under **Settings → API Keys**, kept safe for the one paste below.
### Step 2 — Install the node pack and add the credential
1. Open **Developer → Connectors** and download the n8n node definition (`orbit-.n8n-nodes.json`).
2. Install the `n8n-nodes-orbit` community pack into your n8n instance — self-hosted or n8n Cloud, same pack.
3. In n8n, create a credential of type **Orbit API** and paste your `dv_live_sk_` secret. The pack's trigger and action nodes read that credential.
### Step 3 — Build a workflow and verify
* The **Orbit trigger node** subscribes to one Orbit webhook event (the same catalog the Zapier triggers use) and starts the workflow on it.
* The **action nodes** send SMS, WhatsApp, or email and create or update contacts — the same public endpoints the Zapier actions call.
Add an Orbit trigger node subscribed to a New Inbound Message event, wire it to an n8n **Set** node that echoes the payload, and activate the workflow. Send an inbound message — the execution should show the payload within seconds.
### Step 4 — Troubleshooting
| Symptom | Cause | Fix |
| --------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| n8n reports an invalid credential | The API key is wrong, revoked, or lacks the needed scopes | Re-paste a fresh `dv_live_sk_` key into the Orbit API credential. |
| Workflow activates but never triggers | The underlying webhook was never created, or the wrong event was picked | Check the subscription under Settings → Webhooks, and confirm the workflow is Active (not just saved) in n8n. |
| Deleting a workflow leaves the webhook behind | Workflow deletion does not tear down the webhook | Remove the webhook under Settings → Webhooks. |
| Pack update breaks node definitions | A community-pack version bump changed node shape | Pin the pack version in your n8n environment, and re-test the workflow after any upgrade. |
For the full catalog plus the Zapier and Make siblings, see [Connector downloads](/guides/connectors-download).
***
## Ahead-of-time notes that apply to every one
* **API-route parity.** Every dashboard operation above maps to a public route in [`/api-reference/integrations`](/api-reference/integrations). `POST /api/v1/integrations/connect` returns an `auth_url`; `GET /api/v1/integrations` reports each integration's connection state; `POST /api/v1/integrations/disconnect` severs the connection and clears stored credentials.
* **Tenant-owned controls only.** Orbit never asks you to share a provider credential out-of-band, and never exposes one through an API or UI surface. Rotation and revocation are your controls.
* **Inbound vs outbound.** These integrations move data *into* Orbit or *between* Orbit and the tool — none of them change how outbound messaging routes. (That is deliberate; outbound stays on the Devotel softswitch.)
## Related reading
* [Integrations API reference](/api-reference/integrations) — endpoint map for the connect/status surface, scopes, and the Calendly webhook receiver.
* [Connector downloads: Zapier, Make, and n8n](/guides/connectors-download) — the app-definition catalog the Zapier and n8n sections lean on.
* [Connect HubSpot & Salesforce end to end](/guides/hubspot-salesforce-integration) — the same connect → sync → verify → troubleshoot pattern for CRM providers.
* [Slack onboarding](/guides/slack-onboarding) — the operator runbook for Slack threads once the integration is connected.
* [Zendesk CRM migration](/guides/crm-migration-zendesk) — for moving history out of Zendesk, not just connecting it.