Integrations Frequently Asked Questions

Common questions about connecting and managing third-party integrations in Zipper. Find answers to questions about OAuth connections, social media integrations, business tool connections, and integration management.

Product Capabilities and What It Can Do

Q: What integrations can I connect?

A: You can connect:

• Social Media: Facebook Pages, Instagram, LinkedIn
• Business Tools: Google Business, Calendly, Jobber
• Communication: Twilio (for SMS)
• Other Services: Additional integrations as available

Each integration extends Zipper's capabilities in different ways.

Q: Can I connect multiple social media accounts?

A: Yes! You can:

• Connect multiple Facebook Pages
• Connect Instagram accounts
• Connect LinkedIn profiles/pages
• Choose which pages/profiles to use for publishing

This allows you to manage multiple social media accounts from one place.

Q: How do OAuth connections work?

A: OAuth connections:

• Use secure OAuth authentication
• Store long-lived tokens for connected services
• Automatically refresh expired tokens
• Maintain connections without re-authenticating

OAuth provides secure, standard authentication for integrations.

Q: Can I publish content to social media?

A: Yes! Once connected, you can:

• Publish content library items to Facebook Pages
• Post to Instagram accounts
• Share on LinkedIn profiles/pages
• Schedule posts across platforms

This helps you share marketing content automatically.

Q: What happens if an integration connection fails?

A: If a connection fails:

• Integration status is updated
• You'll see connection errors
• You can reconnect the integration
• Tokens can be refreshed automatically

The system handles connection issues gracefully and allows reconnection.

How to Use the Product

Getting Started

Q: What do I need before I can connect integrations?

A: Before connecting integrations, you should have:

• An active organization account at https://app.joinzipper.com
• Organization owner or admin permissions (you need the "manage-org-integrations" permission)
• Accounts for the services you want to connect

You can start connecting integrations immediately once you have the required permissions.

Q: How do I get started connecting integrations?

A: To connect integrations:

1. Log in to https://app.joinzipper.com
2. Go to Organization Management → Integrations
3. Find the integration you want to connect
4. Click Connect or Authorize
5. Follow the OAuth flow to authorize
6. Complete connection setup

Your integration will be connected and ready to use.

Common Tasks

Q: How do I connect Facebook Pages?

A: To connect Facebook:

1. Go to Integrations → Facebook
2. Click Connect Facebook
3. Authorize Zipper to access Facebook
4. Select which pages to connect
5. Complete connection

Once connected, you can publish to your Facebook Pages.

Q: How do I connect Instagram?

A: To connect Instagram:

1. Go to Integrations → Instagram
2. Click Connect Instagram
3. Authorize Zipper to access Instagram
4. Select which account/profile to connect
5. Complete connection

Once connected, you can post to Instagram.

Q: How do I connect LinkedIn?

A: To connect LinkedIn:

1. Go to Integrations → LinkedIn
2. Click Connect LinkedIn
3. Authorize Zipper to access LinkedIn
4. Select which profile/page to connect
5. Complete connection

Once connected, you can post to LinkedIn.

Q: How do I connect Google Business?

A: To connect Google Business:

1. Go to Integrations → Google Business
2. Click Connect Google Business
3. Authorize Zipper to access Google Business
4. Select which locations to connect
5. Complete connection

Once connected, you can manage Google Business listings.

Q: How do I disconnect an integration?

A: To disconnect:

1. Go to Integrations
2. Find the integration you want to disconnect
3. Click Disconnect or Remove
4. Confirm disconnection

The integration will be removed, and tokens will be deleted.

Configuration and Settings

Q: How do I select which pages to connect?

A: When connecting social media:

1. Start the connection process
2. After authorization, you'll see available pages/profiles
3. Select which ones to connect
4. Complete connection

You can connect multiple pages/profiles per service.

Q: How do I manage integration tokens?

A: Tokens are managed automatically:

• Tokens are stored securely
• Expired tokens are refreshed automatically
• You can view token status in integration settings
• Tokens are deleted when integrations are disconnected

You generally don't need to manage tokens manually.

Troubleshooting

Q: Why can't I connect an integration?

A: You might not be able to connect if:

• You don't have "manage-org-integrations" permission
• OAuth authorization failed
• Service account doesn't have required permissions
• Integration isn't available

Solution: Check your permissions, ensure OAuth authorization completes successfully, verify service account permissions, and check if the integration is available.

Q: Why is my integration not working?

A: Integration might not work if:

• Connection has been disconnected
• Tokens have expired and refresh failed
• Service account permissions changed
• Integration service is unavailable

Solution: Check integration status, reconnect if needed, verify service account permissions, and check service availability.

Q: Why don't I see my Facebook Pages?

A: Facebook Pages might not appear if:

• Pages aren't connected to your Facebook account
• You don't have admin access to pages
• OAuth authorization didn't include page permissions
• Pages need to be reconciled

Solution: Ensure you have admin access to pages, re-authorize with page permissions, and reconcile pages if needed.

Q: Why can't I publish to social media?

A: Publishing might fail if:

• Integration isn't connected
• Selected page/profile isn't connected
• Tokens have expired
• Content doesn't meet platform requirements

Solution: Verify integration is connected, check page/profile selection, refresh tokens if needed, and ensure content meets platform requirements.

Edge Cases and Advanced Usage

Q: Can I connect the same service multiple times?

A: Depending on the service:

• Social Media: You can connect multiple pages/profiles
• Business Tools: Typically one connection per organization
• Communication: May support multiple connections

Check integration-specific documentation for details.

Q: What happens if I disconnect an integration?

A: When you disconnect:

• Integration is removed from your account
• Tokens are deleted
• Connected resources are no longer accessible
• Published content remains (but new publishing stops)

You can reconnect later if needed.

Q: Can I use integrations for multiple organizations?

A: Integrations are typically:

• Connected per organization
• Stored with organization-specific tokens
• Accessible only within that organization

Each organization manages its own integrations independently.

Q: How do I reconcile Facebook Pages?

A: To reconcile pages:

1. Go to Integrations → Facebook
2. Find Reconcile Pages option
3. Click to reconcile
4. System updates available pages

Reconciliation ensures your connected pages are up to date.

Q: Can I schedule posts through integrations?

A: Yes! Once connected:

• Schedule posts to Facebook Pages
• Schedule posts to Instagram
• Schedule posts to LinkedIn
• Manage scheduled posts

Scheduling helps you plan social media content in advance.

Q: What permissions do integrations need?

A: Required permissions vary by integration:

• Facebook: Page management, posting permissions
• Instagram: Posting permissions
• LinkedIn: Profile/page posting permissions
• Google Business: Business profile management
• Calendly: Calendar access
• Jobber: Service data access
• Twilio: SMS sending permissions

Permissions are requested during OAuth authorization.

Q: How do I know if an integration is working?

A: To check integration status:

1. Go to Integrations
2. View integration status
3. Check for connection errors
4. Test integration functionality

Status indicators show if integrations are connected and working.

Webhooks

Q: What are webhooks?

A: Webhooks allow Zipper to send real-time notifications to your external systems when events occur. When a customer registers for an event, books an appointment, or makes a purchase, Zipper can automatically notify your other systems via HTTP POST requests.

Q: What events can trigger webhooks?

A: Webhooks can be triggered by:

• Event Registrations: Signups and cancellations for events
• Appointment Scheduling: Appointments booked or cancelled
• Purchases: When purchases are completed

You can configure which events each webhook URL receives.

Q: How do I set up webhooks?

A: To set up webhooks:

1. Go to Organization Management → Integrations → Webhooks
2. Click "Add Webhook"
3. Enter your webhook URL (must be HTTPS)
4. Select which events to receive
5. Save the webhook
6. Copy your webhook signature secret

You can configure up to 3 webhook URLs per organization.

Q: How do I verify webhooks are from Zipper?

A: Each webhook request includes an HMAC-SHA256 signature in the X-Webhook-Signature header. To verify:

1. Get your webhook signature secret from the webhooks settings
2. Compute HMAC-SHA256 of the request body using your secret
3. Compare with the signature in the header

Example verification code (Node.js):

const crypto = require('crypto');
const expectedSignature = crypto
  .createHmac('sha256', webhookSecret)
  .update(requestBody)
  .digest('hex');
const isValid = signature === expectedSignature;

Q: What happens if my webhook endpoint is down?

A: Currently, webhook delivery is best-effort:

• Webhooks timeout after 10 seconds
• Failed deliveries are logged but not retried
• Your system should handle missed webhooks gracefully
• Consider checking for missing data periodically

Webhook retry logic may be added in a future update.

Q: Can I regenerate my webhook secret?

A: Yes! If you need to rotate your webhook secret:

1. Go to Organization Management → Integrations → Webhooks
2. Find your webhook configuration
3. Click "Regenerate Secret"
4. Update your receiving system with the new secret

The old secret will stop working immediately after regeneration.

Public API

Q: What is the Public API?

A: The Public API provides programmatic access to your Zipper data for external integrations. You can:

• Read and update customer roster records
• Access report data
• Integrate Zipper data with your other systems

The API is authenticated using API tokens.

Q: How do I get an API token?

A: To generate an API token:

1. Go to Organization Management → Integrations → API
2. Click "Generate API Token"
3. Copy and securely store your token
4. Use the token in the X-API-TOKEN header for all requests

Keep your API token secure - it provides access to your organization's data.

Q: What endpoints are available in the Public API?

A: Currently available endpoints include:

Roster:

• GET /roster/:rosterId - Get customer details
• PATCH /roster/:rosterId - Update customer record
• POST /roster/:rosterId/notes - Add note to customer

Reports:

• GET /reports - Access report data with date range filters

Full API documentation with OpenAPI specification is available at your public API URL.

Q: Is there API documentation?

A: Yes! The Public API includes:

• Swagger UI: Interactive documentation at /swagger
• OpenAPI Spec: Download at /openapi.yaml
• Example requests: Included in the documentation

The documentation shows all available endpoints, parameters, and response formats.

Q: Are there rate limits on the API?

A: Yes, the API has rate limits to ensure service reliability:

• Standard rate limiting per organization
• Requests exceeding limits receive 429 responses
• Implement exponential backoff for retries

Contact support if you need higher rate limits for your use case.