Integrations API

The Integrations API manages connections to external services including email providers, messaging platforms, e-commerce systems, and data import tools.

Integration Object

{
  id: string;                    // UUID
  organization_id: string;       // UUID of the organization
  channel_type: string;          // Integration type
  name: string;                  // Display name
  config: object;                // Integration-specific configuration
  credentials?: object;          // Encrypted credentials (write-only)
  enabled: boolean;              // Whether the integration is active
  created_at: string;            // ISO timestamp
  updated_at: string;            // ISO timestamp
}

Channel Types

List Integrations

Retrieve all integrations for the organization.

Procedure: integrations.list

Authentication: Required

Input: None

Example:

curl -X GET "https://your-domain.com/api/trpc/integrations.list" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": [
        {
          "id": "uuid",
          "channel_type": "shopify",
          "name": "Main Store",
          "config": {
            "shop": "my-store.myshopify.com"
          },
          "enabled": true,
          "created_at": "2024-01-01T00:00:00.000Z"
        }
      ]
    }
  }
}

Notes:

• Credentials are never returned in list responses

Get Integration

Retrieve a single integration by ID.

Procedure: integrations.get

Authentication: Required

Input:

{
  id: string;  // Integration UUID
}

Example:

curl -X GET "https://your-domain.com/api/trpc/integrations.get?input=%7B%22id%22:%22integration-uuid%22%7D" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "channel_type": "shopify",
        "name": "Main Store",
        "config": {
          "shop": "my-store.myshopify.com",
          "accessToken": "shpat_xxx..."
        },
        "enabled": true,
        "created_at": "2024-01-01T00:00:00.000Z"
      }
    }
  }
}

Create Integration

Create a new integration.

Procedure: integrations.create

Authentication: Required

Input:

{
  channelType: 'email' | 'slack' | 'sms' | 'widget' | 'webhook' | 'shopify' | 'stripe' | 'whatsapp' | 'messenger' | 'dialpad' | 'amazon';
  name: string;              // 1-200 characters
  config?: object;           // Integration-specific configuration
  credentials?: object;      // Credentials (encrypted at rest)
  enabled?: boolean;         // default: true
}

Example:

curl -X POST "https://your-domain.com/api/trpc/integrations.create" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "channelType": "email",
      "name": "Support Email",
      "config": {
        "imapHost": "imap.gmail.com",
        "imapPort": 993,
        "smtpHost": "smtp.gmail.com",
        "smtpPort": 587
      },
      "credentials": {
        "email": "support@company.com",
        "password": "app-password"
      },
      "enabled": true
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "channel_type": "email",
        "name": "Support Email",
        "enabled": true,
        "created_at": "2024-01-15T10:30:00.000Z"
      }
    }
  }
}

Update Integration

Update an existing integration.

Procedure: integrations.update

Authentication: Required

Input:

{
  id: string;                // Required, integration UUID
  name?: string;             // 1-200 characters
  config?: object;           // Integration-specific configuration
  credentials?: object;      // New credentials
  enabled?: boolean;         // Enable/disable
}

Example:

curl -X POST "https://your-domain.com/api/trpc/integrations.update" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "id": "integration-uuid",
      "enabled": false
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "name": "Support Email",
        "enabled": false,
        "updated_at": "2024-01-15T11:00:00.000Z"
      }
    }
  }
}

Delete Integration

Permanently delete an integration.

Procedure: integrations.delete

Authentication: Required

Input:

{
  id: string;  // Integration UUID
}

Example:

curl -X POST "https://your-domain.com/api/trpc/integrations.delete" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"id":"integration-uuid"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true
      }
    }
  }
}

Get Availability

Check which integration types are available and their configuration status.

Procedure: integrations.getAvailability

Authentication: Required

Input: None

Example:

curl -X GET "https://your-domain.com/api/trpc/integrations.getAvailability" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "email": { "available": true, "configured": true },
        "slack": { "available": true, "configured": false },
        "sms": { "available": true, "configured": true },
        "widget": { "available": true, "configured": true },
        "shopify": { "available": true, "configured": true },
        "stripe": { "available": true, "configured": false },
        "whatsapp": { "available": true, "configured": false },
        "messenger": { "available": true, "configured": false },
        "dialpad": { "available": true, "configured": false },
        "amazon": { "available": true, "configured": false }
      }
    }
  }
}

Widget Integration

The widget is an embeddable chat interface for your website.

Get Widget Config

Retrieve widget configuration for the organization.

Procedure: integrations.getWidgetConfig

Authentication: Required

Input: None

Response:

{
  "result": {
    "data": {
      "json": {
        "enabled": true,
        "primaryColor": "#0066FF",
        "position": "bottom-right",
        "greeting": "Hi! How can we help you today?",
        "offlineMessage": "We're currently offline. Leave a message!",
        "requireEmail": true,
        "showBranding": false
      }
    }
  }
}

Update Widget Config

Update widget appearance and behavior.

Procedure: integrations.updateWidgetConfig

Authentication: Required

Input:

{
  enabled?: boolean;
  primaryColor?: string;      // Hex color code
  position?: 'bottom-right' | 'bottom-left';
  greeting?: string;
  offlineMessage?: string;
  requireEmail?: boolean;
  showBranding?: boolean;
}

Shopify Integration

Connect to Shopify stores for customer and order data.

Sync Shopify Customers

Import customers from a connected Shopify store.

Procedure: integrations.syncShopifyCustomers

Authentication: Required

Input:

{
  integrationId: string;  // Shopify integration UUID
}

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true,
        "customersImported": 150,
        "customersUpdated": 25
      }
    }
  }
}

Get Shopify Sync Status

Check the status of Shopify data synchronization.

Procedure: integrations.getShopifySyncStatus

Authentication: Required

Input:

{
  integrationId: string;  // Shopify integration UUID
}

Response:

{
  "result": {
    "data": {
      "json": {
        "lastSync": "2024-01-15T10:00:00.000Z",
        "status": "completed",
        "customersCount": 1500,
        "ordersCount": 3200
      }
    }
  }
}

Sync Shopify Data

Trigger a full data sync from Shopify (customers, orders, products).

Procedure: integrations.syncShopifyData

Authentication: Required

Input:

{
  integrationId: string;  // Shopify integration UUID
}

Re-register Shopify Webhooks

Re-register Shopify webhooks if they become disconnected.

Procedure: integrations.reregisterShopifyWebhooks

Authentication: Required

Input:

{
  integrationId: string;  // Shopify integration UUID
}

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true,
        "webhooksRegistered": ["orders/create", "orders/updated", "customers/create", "customers/update"]
      }
    }
  }
}

Stripe Integration

Connect to Stripe for payment and customer data.

Sync Stripe Data

Import customers and payment data from Stripe.

Procedure: integrations.syncStripeData

Authentication: Required

Input:

{
  integrationId: string;  // Stripe integration UUID
}

Get Stripe Sync Status

Check the status of Stripe data synchronization.

Procedure: integrations.getStripeSyncStatus

Authentication: Required

Input:

{
  integrationId: string;  // Stripe integration UUID
}

Response:

{
  "result": {
    "data": {
      "json": {
        "lastSync": "2024-01-15T10:00:00.000Z",
        "status": "completed",
        "customersCount": 500,
        "chargesCount": 1200
      }
    }
  }
}

Get Stripe Customer by Email

Look up a Stripe customer by their email address.

Procedure: integrations.getStripeCustomerByEmail

Authentication: Required

Input:

{
  integrationId: string;  // Stripe integration UUID
  email: string;          // Customer email address
}

Response:

{
  "result": {
    "data": {
      "json": {
        "customerId": "cus_xxx",
        "email": "customer@example.com",
        "name": "John Doe",
        "charges": [
          {
            "id": "ch_xxx",
            "amount": 9900,
            "currency": "usd",
            "status": "succeeded",
            "created": "2024-01-15T10:00:00.000Z"
          }
        ],
        "subscriptions": []
      }
    }
  }
}

Refund Stripe Charge

Issue a refund for a Stripe charge.

Procedure: integrations.refundStripeCharge

Authentication: Required

Input:

{
  integrationId: string;  // Stripe integration UUID
  chargeId: string;       // Stripe charge ID (ch_xxx)
  amount?: number;        // Amount in cents (optional, full refund if omitted)
  reason?: 'duplicate' | 'fraudulent' | 'requested_by_customer';
}

Example:

curl -X POST "https://your-domain.com/api/trpc/integrations.refundStripeCharge" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "integrationId": "stripe-integration-uuid",
      "chargeId": "ch_3MqLiD2eZvKYlo2C0xz8BFzH",
      "amount": 5000,
      "reason": "requested_by_customer"
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "refundId": "re_xxx",
        "amount": 5000,
        "status": "succeeded",
        "created": "2024-01-15T11:00:00.000Z"
      }
    }
  }
}

Email Integration

Configure email accounts for ticket creation and replies.

Sync Email IMAP

Manually trigger IMAP sync to check for new emails.

Procedure: integrations.syncEmailImap

Authentication: Required

Input:

{
  integrationId: string;  // Email integration UUID
}

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true,
        "newEmails": 5,
        "ticketsCreated": 3,
        "repliesMatched": 2
      }
    }
  }
}

Get Default Email

Get the default email integration for the organization.

Procedure: integrations.getDefaultEmail

Authentication: Required

Input: None

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "name": "Support Email",
        "config": {
          "email": "support@company.com"
        }
      }
    }
  }
}

Set Default Email

Set the default email integration for outgoing messages.

Procedure: integrations.setDefaultEmail

Authentication: Required

Input:

{
  integrationId: string;  // Email integration UUID
}

WhatsApp Integration

Connect to WhatsApp Business API for messaging.

Get WhatsApp Status

Check the status of WhatsApp Business API connection.

Procedure: integrations.getWhatsAppStatus

Authentication: Required

Input:

{
  integrationId: string;  // WhatsApp integration UUID
}

Response:

{
  "result": {
    "data": {
      "json": {
        "connected": true,
        "phoneNumberId": "123456789",
        "businessAccountId": "987654321",
        "verifiedName": "Company Support"
      }
    }
  }
}

List WhatsApp Phone Numbers

List available WhatsApp phone numbers.

Procedure: integrations.listWhatsAppPhoneNumbers

Authentication: Required

Input:

{
  integrationId: string;  // WhatsApp integration UUID
}

Response:

{
  "result": {
    "data": {
      "json": [
        {
          "id": "phone-number-id",
          "displayPhoneNumber": "+1 555-123-4567",
          "verifiedName": "Company Support",
          "qualityRating": "GREEN"
        }
      ]
    }
  }
}

List WhatsApp Templates

List approved message templates.

Procedure: integrations.listWhatsAppTemplates

Authentication: Required

Input:

{
  integrationId: string;  // WhatsApp integration UUID
}

Response:

{
  "result": {
    "data": {
      "json": [
        {
          "name": "order_confirmation",
          "status": "APPROVED",
          "category": "UTILITY",
          "language": "en",
          "components": [...]
        }
      ]
    }
  }
}

Sync WhatsApp Templates

Refresh the list of WhatsApp templates from Meta.

Procedure: integrations.syncWhatsAppTemplates

Authentication: Required

Input:

{
  integrationId: string;  // WhatsApp integration UUID
}

Delete WhatsApp Template

Delete a WhatsApp message template.

Procedure: integrations.deleteWhatsAppTemplate

Authentication: Required

Input:

{
  integrationId: string;  // WhatsApp integration UUID
  templateName: string;   // Template name to delete
}

Messenger Integration

Connect to Facebook Messenger for customer messaging.

Get Messenger Status

Check the status of Facebook Messenger connection.

Procedure: integrations.getMessengerStatus

Authentication: Required

Input:

{
  integrationId: string;  // Messenger integration UUID
}

Response:

{
  "result": {
    "data": {
      "json": {
        "connected": true,
        "pages": [
          {
            "id": "page-id",
            "name": "Company Page",
            "connected": true
          }
        ]
      }
    }
  }
}

List Messenger Pages

List Facebook pages available for Messenger.

Procedure: integrations.listMessengerPages

Authentication: Required

Input:

{
  integrationId: string;  // Messenger integration UUID
}

Update Messenger Page

Enable or disable Messenger for a Facebook page.

Procedure: integrations.updateMessengerPage

Authentication: Required

Input:

{
  integrationId: string;  // Messenger integration UUID
  pageId: string;         // Facebook page ID
  enabled: boolean;       // Enable/disable Messenger
}

Dialpad Integration

Connect to Dialpad for phone call and voicemail management.

Get Dialpad Status

Check the status of Dialpad connection.

Procedure: integrations.getDialpadStatus

Authentication: Required

Input:

{
  integrationId: string;  // Dialpad integration UUID
}

Response:

{
  "result": {
    "data": {
      "json": {
        "connected": true,
        "companyName": "My Company",
        "usersCount": 15,
        "webhooksConfigured": true
      }
    }
  }
}

Connect Dialpad API Key

Connect Dialpad using an API key.

Procedure: integrations.connectDialpadApiKey

Authentication: Required

Input:

{
  integrationId: string;  // Dialpad integration UUID
  apiKey: string;         // Dialpad API key
}

Side Effects:

• Validates the API key
• Configures webhooks for call events

List Dialpad Users

List users in the connected Dialpad account.

Procedure: integrations.listDialpadUsers

Authentication: Required

Input:

{
  integrationId: string;  // Dialpad integration UUID
}

Response:

{
  "result": {
    "data": {
      "json": [
        {
          "id": "user-id",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john@company.com",
          "phoneNumber": "+1 555-123-4567"
        }
      ]
    }
  }
}

List Dialpad Calls

List recent calls from Dialpad.

Procedure: integrations.listDialpadCalls

Authentication: Required

Input:

{
  integrationId: string;  // Dialpad integration UUID
  limit?: number;         // Max results (default: 50)
  startDate?: string;     // ISO date filter
  endDate?: string;       // ISO date filter
}

Response:

{
  "result": {
    "data": {
      "json": [
        {
          "id": "call-id",
          "direction": "inbound",
          "fromNumber": "+1 555-987-6543",
          "toNumber": "+1 555-123-4567",
          "duration": 245,
          "status": "completed",
          "recordingUrl": "https://...",
          "startedAt": "2024-01-15T10:00:00.000Z"
        }
      ]
    }
  }
}

List Dialpad Voicemails

List voicemails from Dialpad.

Procedure: integrations.listDialpadVoicemails

Authentication: Required

Input:

{
  integrationId: string;  // Dialpad integration UUID
  limit?: number;         // Max results (default: 50)
}

Response:

{
  "result": {
    "data": {
      "json": [
        {
          "id": "voicemail-id",
          "fromNumber": "+1 555-987-6543",
          "duration": 45,
          "transcription": "Hi, I'm calling about my order...",
          "audioUrl": "https://...",
          "createdAt": "2024-01-15T10:00:00.000Z"
        }
      ]
    }
  }
}

Sync Dialpad Now

Manually trigger a sync of Dialpad data.

Procedure: integrations.syncDialpadNow

Authentication: Required

Input:

{
  integrationId: string;  // Dialpad integration UUID
}

Configure Dialpad Webhooks

Re-configure Dialpad webhooks if they become disconnected.

Procedure: integrations.configureDialpadWebhooks

Authentication: Required

Input:

{
  integrationId: string;  // Dialpad integration UUID
}

Amazon Integration

Connect to Amazon Seller Central for order and customer data.

Get Amazon Status

Check the status of Amazon Seller Central connection.

Procedure: integrations.getAmazonStatus

Authentication: Required

Input:

{
  integrationId: string;  // Amazon integration UUID
}

Response:

{
  "result": {
    "data": {
      "json": {
        "connected": true,
        "sellerId": "AXXXXXXXXXXXXX",
        "marketplaces": ["ATVPDKIKX0DER", "A2EUQ1WTGCTBG2"],
        "lastSync": "2024-01-15T10:00:00.000Z"
      }
    }
  }
}

List Amazon Accounts

List connected Amazon seller accounts.

Procedure: integrations.listAmazonAccounts

Authentication: Required

Input:

{
  integrationId: string;  // Amazon integration UUID
}

List Amazon Orders

List orders from Amazon.

Procedure: integrations.listAmazonOrders

Authentication: Required

Input:

{
  integrationId: string;     // Amazon integration UUID
  sellerAccountId?: string;  // Filter by seller account
  status?: string[];         // Filter by order status
  limit?: number;            // Max results
  startDate?: string;        // ISO date filter
  endDate?: string;          // ISO date filter
}

Response:

{
  "result": {
    "data": {
      "json": [
        {
          "orderId": "123-4567890-1234567",
          "status": "Shipped",
          "purchaseDate": "2024-01-15T10:00:00.000Z",
          "buyer": {
            "email": "buyer@example.com",
            "name": "John Doe"
          },
          "items": [
            {
              "asin": "B0XXXXXXXXX",
              "title": "Product Name",
              "quantity": 2,
              "price": 29.99
            }
          ],
          "total": 59.98
        }
      ]
    }
  }
}

Sync Amazon Now

Manually trigger a sync of Amazon orders and customer data.

Procedure: integrations.syncAmazonNow

Authentication: Required

Input:

{
  integrationId: string;  // Amazon integration UUID
}

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true,
        "ordersImported": 25,
        "customersUpdated": 18
      }
    }
  }
}

Zendesk Import

Import data from Zendesk into Relay.

Get Zendesk Status

Check if Zendesk import is available and configured.

Procedure: integrations.getZendeskStatus

Authentication: Required

Input:

{
  integrationId: string;  // Zendesk integration UUID
}

List Zendesk Imports

List all Zendesk import jobs.

Procedure: integrations.listZendeskImports

Authentication: Required

Input: None

Response:

{
  "result": {
    "data": {
      "json": [
        {
          "id": "import-uuid",
          "status": "completed",
          "config": {
            "tickets": true,
            "users": true,
            "organizations": true
          },
          "progress": {
            "ticketsImported": 1500,
            "usersImported": 300,
            "organizationsImported": 50
          },
          "startedAt": "2024-01-15T10:00:00.000Z",
          "completedAt": "2024-01-15T10:30:00.000Z"
        }
      ]
    }
  }
}

Get Zendesk Import

Get details of a specific import job.

Procedure: integrations.getZendeskImport

Authentication: Required

Input:

{
  importId: string;  // Import job UUID
}

Start Zendesk Import

Start a new Zendesk data import.

Procedure: integrations.startZendeskImport

Authentication: Required

Input:

{
  integrationId: string;  // Zendesk integration UUID
  config: {
    tickets?: boolean;        // Import tickets (default: true)
    users?: boolean;          // Import users (default: true)
    organizations?: boolean;  // Import organizations (default: true)
    comments?: boolean;       // Import ticket comments (default: true)
    custom_fields?: boolean;  // Import custom fields (default: false)
    attachments?: boolean;    // Import attachments (default: false)
    tags?: boolean;           // Import tags (default: true)
  }
}

Example:

curl -X POST "https://your-domain.com/api/trpc/integrations.startZendeskImport" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "integrationId": "zendesk-integration-uuid",
      "config": {
        "tickets": true,
        "users": true,
        "organizations": true,
        "comments": true,
        "attachments": true,
        "tags": true
      }
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "importId": "import-uuid",
        "status": "running",
        "startedAt": "2024-01-15T10:00:00.000Z"
      }
    }
  }
}

Cancel Zendesk Import

Cancel a running Zendesk import.

Procedure: integrations.cancelZendeskImport

Authentication: Required

Input:

{
  importId: string;  // Import job UUID
}

Freshdesk Import

Import data from Freshdesk into Relay.

Get Freshdesk Status

Check Freshdesk import availability.

Procedure: integrations.getFreshdeskStatus

Authentication: Required

Input:

{
  integrationId: string;  // Freshdesk integration UUID
}

List Freshdesk Imports

List all Freshdesk import jobs.

Procedure: integrations.listFreshdeskImports

Authentication: Required

Input: None

Get Freshdesk Import

Get details of a specific Freshdesk import job.

Procedure: integrations.getFreshdeskImport

Authentication: Required

Input:

{
  importId: string;  // Import job UUID
}

Start Freshdesk Import

Start a new Freshdesk data import.

Procedure: integrations.startFreshdeskImport

Authentication: Required

Input:

{
  domain: string;       // Freshdesk domain (e.g., "company.freshdesk.com")
  apiKey: string;       // Freshdesk API key
  config: {
    tickets?: boolean;       // Import tickets (default: true)
    contacts?: boolean;      // Import contacts (default: true)
    companies?: boolean;     // Import companies (default: true)
    conversations?: boolean; // Import ticket conversations (default: true)
    attachments?: boolean;   // Import attachments (default: false)
  }
}

Example:

curl -X POST "https://your-domain.com/api/trpc/integrations.startFreshdeskImport" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "domain": "company.freshdesk.com",
      "apiKey": "your-freshdesk-api-key",
      "config": {
        "tickets": true,
        "contacts": true,
        "companies": true,
        "conversations": true,
        "attachments": false
      }
    }
  }'

Cancel Freshdesk Import

Cancel a running Freshdesk import.

Procedure: integrations.cancelFreshdeskImport

Authentication: Required

Input:

{
  importId: string;  // Import job UUID
}

OAuth Flows

Several integrations use OAuth for authentication. The OAuth flow endpoints are REST-based:

Shopify OAuth

1. Initiate: GET /api/shopify/install?shop=your-store.myshopify.com&organization_id=org-uuid
2. Callback: GET /api/shopify/callback (handled automatically)

WhatsApp OAuth

1. Initiate: GET /api/whatsapp/install?organization_id=org-uuid
2. Callback: GET /api/whatsapp/callback (handled automatically)

Messenger OAuth

1. Initiate: GET /api/messenger/install?organization_id=org-uuid
2. Callback: GET /api/messenger/callback (handled automatically)

Amazon OAuth

1. Initiate: GET /api/amazon/install?organization_id=org-uuid&marketplace=ATVPDKIKX0DER
2. Callback: GET /api/amazon/callback (handled automatically)

Zendesk OAuth

1. Initiate: GET /api/zendesk/connect?subdomain=your-subdomain&organization_id=org-uuid
2. Callback: GET /api/zendesk/callback (handled automatically)

Stripe Connect OAuth

1. Initiate: GET /api/stripe-connect/install?organization_id=org-uuid
2. Callback: GET /api/stripe-connect/callback (handled automatically)

Dialpad

Dialpad does not use OAuth in Relay. Connect via API key using connectDialpadApiKey.

Error Codes

Webhook Events

Integrations can trigger the following webhook events:

See Webhooks for configuration details.