API Endpoints

Overview & Getting Started

Resources

Agent CapabilitiesPrompt Best PracticesE-commerce IntegrationHealthcare Integration

E-commerce Integration Guide

Learn how to integrate SparkCo's AI agents with your Shopify store to provide personalized customer interactions based on shopping behavior.

Overview

This guide shows you how to set up automated customer communications triggered by various Shopify events:

  • Cart abandonment follow-ups
  • Post-purchase support
  • Product browsing assistance
  • Order status updates

1. Install the SparkCo App

First, install our Shopify app to enable webhook integration and customer data synchronization:

  1. Visit the Shopify App Store
  2. Search for "SparkCo AI Customer Service"
  3. Click Install and follow the authentication process
  4. Configure your webhook preferences in the app settings

2. Set Up Event Handlers

Create event handlers for different Shopify webhooks. Here's an example using Express:

// server.js
const express = require('express');
const app = express();

app.post('/webhooks/cart/update', async (req, res) => {
  const { customer, cart, products } = req.body;
  
  // Create or update recipient
  const recipient = await createOrUpdateRecipient(customer);
  
  // Update conversation context
  await updateContext(recipient.id, {
    cart_items: products,
    total_value: cart.total_price,
    abandoned_at: new Date().toISOString()
  });
  
  // Schedule a follow-up
  await scheduleReminder({
    recipient_id: recipient.id,
    agent_id: process.env.CART_AGENT_ID,
    message: generateCartReminder(products),
    scheduled_time: getOptimalTime()
  });
  
  res.sendStatus(200);
});

app.post('/webhooks/orders/create', async (req, res) => {
  const { customer, order } = req.body;
  
  // Create or update recipient
  const recipient = await createOrUpdateRecipient(customer);
  
  // Update context with order details
  await updateContext(recipient.id, {
    recent_order: {
      id: order.id,
      items: order.line_items,
      total: order.total_price
    }
  });
  
  // Schedule a thank you call
  await scheduleCall({
    recipient_id: recipient.id,
    agent_id: process.env.SUPPORT_AGENT_ID,
    scheduled_time: getThankYouCallTime(),
    purpose: 'Post-purchase follow-up'
  });
  
  res.sendStatus(200);
});

3. Helper Functions

Implement these helper functions to manage recipient data and communications:

// helpers.js
const { SparkCoClient } = require('@sparkco/api');
const client = new SparkCoClient(process.env.SPARKCO_API_KEY);

async function createOrUpdateRecipient(customer) {
  const { data } = await client.post('/recipients', {
    name: `${customer.first_name} ${customer.last_name}`,
    phone_number: customer.phone,
    email: customer.email,
    metadata: {
      shopify_id: customer.id,
      total_orders: customer.orders_count,
      total_spent: customer.total_spent
    }
  });
  return data;
}

async function updateContext(recipientId, context) {
  const { data } = await client.post(`/recipients/${recipientId}/context`, {
    context_data: context
  });
  return data;
}

async function scheduleReminder(params) {
  const { data } = await client.post('/reminders', params);
  return data;
}

async function scheduleCall(params) {
  const { data } = await client.post('/schedules', params);
  return data;
}

function getOptimalTime() {
  // Calculate optimal time based on customer timezone
  // and typical response rates
  return new Date(Date.now() + 30 * 60 * 1000).toISOString();
}

function generateCartReminder(products) {
  return `We noticed you left some great items in your cart! Would you like help completing your purchase of ${products.map(p => p.title).join(', ')}?`;
}

4. Configure Agent Knowledge

Upload product information to your agent's knowledge base to enable informed conversations:

// sync-products.js
async function syncProducts() {
  const products = await shopify.product.list();
  
  for (const product of products) {
    await client.post('/knowledge', {
      title: product.title,
      content: JSON.stringify({
        description: product.body_html,
        variants: product.variants,
        price_range: getPriceRange(product),
        categories: product.tags,
        features: extractFeatures(product)
      })
    });
  }
}

Common Integration Patterns

Cart Abandonment

  1. Detect cart update/abandonment via webhook
  2. Create/update recipient with customer data
  3. Update context with cart contents
  4. Schedule a reminder for optimal time
  5. Follow up with a call if needed

Post-Purchase

  1. Receive order creation webhook
  2. Update recipient's purchase history
  3. Schedule thank you call/message
  4. Set up delivery status updates
  5. Schedule satisfaction follow-up

Product Browsing

  1. Track product page views
  2. Identify browsing patterns
  3. Update agent context with interests
  4. Trigger proactive assistance
  5. Schedule personalized recommendations

Best Practices

  • Implement retry logic for webhook handlers
  • Store customer timezone for optimal contact times
  • Keep product knowledge base updated
  • Respect customer contact preferences
  • Monitor interaction success rates
  • A/B test message timing and content
  • Implement proper error handling

Testing

Use our sandbox environment to test your integration:

# Set up test environment
export SPARKCO_API_KEY=sk_test_...
export SHOPIFY_WEBHOOK_SECRET=whsec_test_...

# Run test suite
npm run test:integration