Integrate WhatsApp With Shopify for AI Chatbots & Alerts

SYSTEM 1: INTERNAL STAFF ALERTS
Shopify Event → Trigger → WhatsApp message → Staff group/individual

SYSTEM 2: CUSTOMER-FACING AI CHATBOT
Customer visits storefront → Chat widget → AI processes message
→ Responds with product/order info → Escalates to human if needed

# Test your Meta Cloud API connection
curl -X POST \
  "https://graph.facebook.com/v18.0/YOUR_PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "RECIPIENT_PHONE_NUMBER",
    "type": "text",
    "text": { "body": "Test message from Shopify integration" }
  }'

{
  "name": "new_order_alert",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "🛒 New Order Alert"
    },
    {
      "type": "BODY",
      "text": "Order #{{1}} received from {{2}}.\nTotal: {{3}}\nItems: {{4}}\nShipping to: {{5}}",
      "example": {
        "body_text": [["1042"], ["Jane Smith"], ["$127.50"], ["Blue Jacket x1, Scarf x2"], ["London, UK"]]
      }
    },
    {
      "type": "FOOTER",
      "text": "View in Shopify Admin"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "text": "View Order",
          "url": "https://yourstore.myshopify.com/admin/orders/{{6}}"
        }
      ]
    }
  ]
}

curl -X POST \
  "https://graph.facebook.com/v18.0/YOUR_WABA_ID/message_templates" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @template.json

Trigger: Shopify — New Order
↓
Filter: Order total > $200 (optional — only alert for high-value orders)
↓
Action: WhatsApp Business — Send Template Message
  To: +1234567890 (staff member)
  Template: new_order_alert
  Variables:
    {{1}} = Order Number
    {{2}} = Customer Name
    {{3}} = Total Price
    {{4}} = Line Items Summary
    {{5}} = Shipping City, Country
    {{6}} = Order ID

[Shopify: Watch Orders]
    ↓
[Router] — branch by condition
    ├── Order > $500 → [WhatsApp: Alert Manager + Fulfillment Lead]
    ├── Order contains "WHOLESALE" tag → [WhatsApp: Alert Sales Team]
    ├── Order flagged high risk → [WhatsApp: Alert Fraud Team]
    └── Standard order → [WhatsApp: Alert Fulfillment Only]

Trigger: Order Created
Condition: Order risk level is HIGH
   OR
Condition: Order total price > 300
Action: HTTP Request (send to your webhook endpoint)
  Method: POST
  URL: https://your-server.com/whatsapp/alert
  Body (JSON):
  {
    "order_number": "{{ order.name }}",
    "customer_name": "{{ order.customer.firstName }} {{ order.customer.lastName }}",
    "total": "{{ order.totalPrice }}",
    "risk_level": "{{ order.risk.recommendation }}",
    "items_count": "{{ order.lineItems | size }}",
    "admin_url": "https://yourstore.myshopify.com/admin/orders/{{ order.id }}"
  }

// server/routes/whatsapp-alert.js
const express = require('express');
const router = express.Router();

const STAFF_NUMBERS = [
  '+1234567890',  // Fulfillment manager
  '+0987654321',  // Operations lead
];

router.post('/whatsapp/alert', async (req, res) => {
  const { order_number, customer_name, total, risk_level, items_count, admin_url } = req.body;

  // Verify request is from your Flow (add a secret header)
  if (req.headers['x-flow-secret'] !== process.env.FLOW_WEBHOOK_SECRET) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  const alertPromises = STAFF_NUMBERS.map(phoneNumber =>
    sendWhatsAppTemplate(phoneNumber, 'new_order_alert', [
      order_number,
      customer_name,
      total,
      `${items_count} item(s)`,
      risk_level || 'Normal',
      extractOrderId(admin_url)
    ])
  );

  await Promise.allSettled(alertPromises);
  res.status(200).json({ sent: STAFF_NUMBERS.length });
});

async function sendWhatsAppTemplate(to, templateName, variables) {
  const components = [{
    type: 'body',
    parameters: variables.map(value => ({
      type: 'text',
      text: String(value)
    }))
  }];

  // Add button URL parameter if needed
  components.push({
    type: 'button',
    sub_type: 'url',
    index: '0',
    parameters: [{ type: 'text', text: variables[5] }] // Order ID for URL
  });

  const response = await fetch(
    `https://graph.facebook.com/v18.0/${process.env.WHATSAPP_PHONE_ID}/messages`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.WHATSAPP_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        messaging_product: 'whatsapp',
        to: to.replace('+', ''),
        type: 'template',
        template: {
          name: templateName,
          language: { code: 'en_US' },
          components
        }
      })
    }
  );

  if (!response.ok) {
    const error = await response.json();
    console.error(`Failed to send to ${to}:`, error);
    throw new Error(`WhatsApp send failed: ${error.error?.message}`);
  }

  return response.json();
}

// Register webhooks via Admin API
const ALERT_WEBHOOKS = [
  { topic: 'orders/create', address: 'https://your-server.com/hooks/order-created' },
  { topic: 'orders/cancelled', address: 'https://your-server.com/hooks/order-cancelled' },
  { topic: 'orders/fulfilled', address: 'https://your-server.com/hooks/order-fulfilled' },
  { topic: 'inventory_levels/update', address: 'https://your-server.com/hooks/inventory-update' },
  { topic: 'refunds/create', address: 'https://your-server.com/hooks/refund-created' }
];

// Webhook handler with intelligent routing
app.post('/hooks/order-created', async (req, res) => {
  if (!verifyShopifyWebhook(req)) return res.status(401).send();

  const order = req.body;
  res.status(200).send('OK'); // Respond immediately — process async

  // Determine alert priority and recipients
  const alertConfig = determineAlertConfig(order);

  await Promise.allSettled(
    alertConfig.recipients.map(recipient =>
      sendWhatsAppTemplate(recipient, alertConfig.template, alertConfig.variables)
    )
  );
});

function determineAlertConfig(order) {
  const isHighValue = parseFloat(order.total_price) > 500;
  const isHighRisk = order.risks?.some(r => r.recommendation === 'cancel');
  const isWholesale = order.tags?.includes('wholesale');

  if (isHighRisk) {
    return {
      template: 'high_risk_order_alert',
      recipients: [STAFF.fraudManager, STAFF.storeOwner],
      variables: [order.name, order.total_price, order.customer?.email]
    };
  }

  if (isHighValue || isWholesale) {
    return {
      template: 'priority_order_alert',
      recipients: [STAFF.fulfillmentLead, STAFF.salesManager],
      variables: [order.name, order.total_price, order.customer?.first_name]
    };
  }

  return {
    template: 'standard_order_alert',
    recipients: [STAFF.fulfillmentTeam],
    variables: [order.name, order.total_price]
  };
}

You are Maya, a helpful shopping assistant for [Store Name].

You help customers with:
- Product recommendations based on their needs
- Size and fit questions (refer to our size guide at /pages/size-guide)
- Order tracking (ask for order number and email)
- Return policy questions (we offer 30-day free returns)
- Shipping questions (free shipping on orders over $75)

Always be warm and helpful. If a customer is upset, empathize first.

Do NOT:
- Make promises about specific delivery dates
- Offer discounts without a valid promotion code
- Discuss competitor products

If you cannot answer confidently, say: "Let me connect you with one of our team members who can help with that."

// server/chatbot/whatsapp-ai-handler.js
const OpenAI = require('openai');
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// WhatsApp incoming message webhook
app.post('/webhooks/whatsapp/incoming', async (req, res) => {
  res.status(200).send('OK'); // Acknowledge immediately

  const entry = req.body.entry?.[0];
  const changes = entry?.changes?.[0];
  const message = changes?.value?.messages?.[0];

  if (!message) return;

  const from = message.from; // Customer's WhatsApp number
  const messageText = message.text?.body || '';
  const messageType = message.type;

  if (messageType !== 'text') {
    await sendWhatsAppText(from, "I can only process text messages right now. How can I help you?");
    return;
  }

  // Get or create conversation context
  const context = await getConversationContext(from);

  // Process with AI
  const aiResponse = await processWithAI(messageText, context, from);

  // Send response
  await sendWhatsAppText(from, aiResponse.message);

  // Save updated context
  await saveConversationContext(from, context, messageText, aiResponse.message);

  // Handle special actions (escalation, order lookup, etc.)
  if (aiResponse.action === 'ESCALATE') {
    await notifyHumanAgent(from, context);
  }
});

async function processWithAI(userMessage, context, customerPhone) {
  // Build system prompt with Shopify store context
  const systemPrompt = `
You are a helpful customer support AI for ${process.env.STORE_NAME}.

Store Information:
- Return policy: 30 days, free returns
- Shipping: Free on orders over $75, 3-5 business days standard
- Express shipping: Available at checkout, 1-2 business days
- Support hours: Monday-Friday 9am-5pm EST

When a customer asks about their order, ask for their order number and email.
When you have an order number, use the lookup_order function to get real data.

If a customer is very upset or requests a human, respond with ACTION:ESCALATE

Always be helpful, warm, and concise. Respond in the same language the customer uses.
  `;

  // Build conversation history
  const messages = [
    { role: 'system', content: systemPrompt },
    ...context.history.slice(-10), // Last 10 messages for context
    { role: 'user', content: userMessage }
  ];

  // Define functions AI can call
  const functions = [
    {
      name: 'lookup_order',
      description: 'Look up order details by order number and customer email',
      parameters: {
        type: 'object',
        properties: {
          order_number: { type: 'string', description: 'Order number (e.g. #1042)' },
          customer_email: { type: 'string', description: 'Customer email address' }
        },
        required: ['order_number', 'customer_email']
      }
    },
    {
      name: 'search_products',
      description: 'Search store products by keyword or category',
      parameters: {
        type: 'object',
        properties: {
          query: { type: 'string', description: 'Search query' },
          limit: { type: 'number', description: 'Max results (default 3)' }
        },
        required: ['query']
      }
    }
  ];

  let response = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages,
    functions,
    function_call: 'auto',
    temperature: 0.7,
    max_tokens: 500
  });

  let aiMessage = response.choices[0].message;

  // Handle function calls (AI needs to look up data)
  while (aiMessage.function_call) {
    const functionName = aiMessage.function_call.name;
    const functionArgs = JSON.parse(aiMessage.function_call.arguments);

    let functionResult;

    if (functionName === 'lookup_order') {
      functionResult = await lookupShopifyOrder(
        functionArgs.order_number,
        functionArgs.customer_email
      );
    } else if (functionName === 'search_products') {
      functionResult = await searchShopifyProducts(functionArgs.query, functionArgs.limit ?? 3);
    }

    // Send function result back to AI
    messages.push(aiMessage);
    messages.push({
      role: 'function',
      name: functionName,
      content: JSON.stringify(functionResult)
    });

    response = await openai.chat.completions.create({
      model: 'gpt-4o',
      messages,
      functions,
      function_call: 'auto',
      temperature: 0.7,
      max_tokens: 500
    });

    aiMessage = response.choices[0].message;
  }

  const responseText = aiMessage.content || "I'm sorry, I couldn't process that. Please try again.";

  // Check for escalation signal
  const shouldEscalate = responseText.includes('ACTION:ESCALATE');
  const cleanResponse = responseText.replace('ACTION:ESCALATE', '').trim();

  return {
    message: cleanResponse,
    action: shouldEscalate ? 'ESCALATE' : null
  };
}

// Look up Shopify order and return structured data
async function lookupShopifyOrder(orderNumber, email) {
  const cleanNumber = orderNumber.replace('#', '');

  const query = `
    {
      orders(first: 1, query: "name:#${cleanNumber} email:${email}") {
        edges {
          node {
            name
            displayFinancialStatus
            displayFulfillmentStatus
            createdAt
            totalPriceSet {
              shopMoney { amount currencyCode }
            }
            lineItems(first: 5) {
              edges {
                node {
                  title
                  quantity
                }
              }
            }
            fulfillments {
              trackingInfo {
                number
                url
                company
              }
              status
            }
            shippingAddress {
              city
              country
            }
          }
        }
      }
    }
  `;

  try {
    const result = await shopifyGraphQL(query);
    const order = result.data.orders.edges[0]?.node;

    if (!order) {
      return { found: false, message: 'Order not found. Please check the order number and email.' };
    }

    const trackingInfo = order.fulfillments?.[0]?.trackingInfo?.[0];

    return {
      found: true,
      orderNumber: order.name,
      paymentStatus: order.displayFinancialStatus,
      fulfillmentStatus: order.displayFulfillmentStatus,
      total: `${order.totalPriceSet.shopMoney.amount} ${order.totalPriceSet.shopMoney.currencyCode}`,
      items: order.lineItems.edges.map(e => `${e.node.title} x${e.node.quantity}`),
      tracking: trackingInfo ? {
        carrier: trackingInfo.company,
        number: trackingInfo.number,
        url: trackingInfo.url
      } : null,
      shipsTo: `${order.shippingAddress?.city}, ${order.shippingAddress?.country}`
    };
  } catch (error) {
    return { found: false, error: 'Could not retrieve order data.' };
  }
}

// Notify human agent when AI escalates
async function notifyHumanAgent(customerPhone, context) {
  const agentMessage = `
🚨 *Customer Needs Human Support*

Customer WhatsApp: ${customerPhone}
Conversation summary: ${context.history.slice(-4).map(m => `${m.role}: ${m.content}`).join('\n')}

Please follow up within 15 minutes.
  `;

  // Alert staff via WhatsApp
  await Promise.all(
    STAFF_NUMBERS.map(staff => sendWhatsAppText(staff, agentMessage))
  );
}

Q: "What is your return policy?"
A: "We offer free 30-day returns on all items. Start a return at yourstore.com/returns"

Q: "How long does shipping take?"
A: "Standard shipping takes 3-5 business days. Express (1-2 days) is available at checkout."

Q: "Where is my order?"
A: "I'd be happy to check! Please share your order number (e.g. #1042) and the email you ordered with."

{%- comment -%} In theme.liquid — before </body> {%- endcomment -%}
<div id="ai-chat-widget" class="chat-widget chat-widget--closed">
  <button class="chat-widget__toggle" aria-label="Open chat">
    <svg><!-- Chat icon SVG --></svg>
    <span class="chat-widget__badge" id="unread-badge" style="display:none">1</span>
  </button>

  <div class="chat-widget__window" id="chat-window" hidden>
    <div class="chat-widget__header">
      <div class="chat-widget__avatar">
        <img src="{{ 'ai-avatar.png' | asset_url }}" alt="Maya AI">
      </div>
      <div>
        <p class="chat-widget__name">Maya</p>
        <p class="chat-widget__status">AI Assistant · Typically replies instantly</p>
      </div>
      <button class="chat-widget__close" id="close-chat">✕</button>
    </div>

    <div class="chat-widget__messages" id="chat-messages">
      <div class="chat-message chat-message--ai">
        <p>Hi! I'm Maya 👋 I can help with product questions, orders, and more. What can I do for you?</p>
      </div>
    </div>

    <div class="chat-widget__input-area">
      <textarea
        id="chat-input"
        placeholder="Type your message..."
        rows="1"
      ></textarea>
      <button id="send-message">Send</button>
    </div>
  </div>
</div>

<script>
  const chatWidget = {
    sessionId: crypto.randomUUID(),
    customerId: {{ customer.id | json }},
    customerEmail: {{ customer.email | json }},

    async sendMessage(text) {
      this.appendMessage('user', text);
      this.showTypingIndicator();

      const response = await fetch('/apps/your-proxy/chat', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          message: text,
          sessionId: this.sessionId,
          customerId: this.customerId,
          currentPage: window.location.pathname,
          currentProduct: {{ product.title | json }} ?? null
        })
      });

      const data = await response.json();
      this.hideTypingIndicator();
      this.appendMessage('ai', data.response);

      if (data.suggestedProducts) {
        this.appendProductCards(data.suggestedProducts);
      }
    },

    appendMessage(role, text) {
      const messagesEl = document.getElementById('chat-messages');
      const msgEl = document.createElement('div');
      msgEl.className = `chat-message chat-message--${role}`;
      msgEl.innerHTML = `<p>${this.escapeHtml(text)}</p>`;
      messagesEl.appendChild(msgEl);
      messagesEl.scrollTop = messagesEl.scrollHeight;
    },

    escapeHtml(text) {
      return text.replace(/[&<>"']/g, char => ({
        '&': '&amp;', '<': '&lt;', '>': '&gt;',
        '"': '&quot;', "'": '&#39;'
      })[char]);
    }
  };
</script>

const ALERT_TEMPLATES = {
  // High priority — immediate alerts
  HIGH_RISK_ORDER: {
    template: 'high_risk_order_alert',
    recipients: ['fraud_manager', 'store_owner'],
    emoji: '🚨'
  },
  HIGH_VALUE_ORDER: {
    template: 'priority_order_alert',
    recipients: ['sales_manager', 'fulfillment_lead'],
    emoji: '💎',
    threshold: 500 // USD
  },

  // Operations alerts
  NEW_ORDER: {
    template: 'standard_order_alert',
    recipients: ['fulfillment_team'],
    emoji: '🛒'
  },
  ORDER_CANCELLED: {
    template: 'cancellation_alert',
    recipients: ['fulfillment_lead'],
    emoji: '❌'
  },
  REFUND_CREATED: {
    template: 'refund_alert',
    recipients: ['finance_team'],
    emoji: '💸'
  },
  ORDER_FULFILLED: {
    template: 'fulfillment_confirmation',
    recipients: ['customer_service'],
    emoji: '📦'
  },

  // Inventory alerts
  LOW_STOCK: {
    template: 'low_stock_alert',
    recipients: ['inventory_manager'],
    emoji: '⚠️',
    threshold: 5 // units remaining
  },
  OUT_OF_STOCK: {
    template: 'out_of_stock_alert',
    recipients: ['inventory_manager', 'store_owner'],
    emoji: '🔴'
  },

  // Customer service escalation
  CHATBOT_ESCALATION: {
    template: 'human_agent_needed',
    recipients: ['customer_service_team'],
    emoji: '👤'
  }
};

// Auto-delete conversation history after retention period
async function cleanupOldConversations() {
  const retentionDays = 90;
  const cutoffDate = new Date();
  cutoffDate.setDate(cutoffDate.getDate() - retentionDays);

  await db.conversations.deleteWhere({
    updatedAt: { $lt: cutoffDate }
  });
}