ETIP — Meta Cloud API Setup & Add-on Guide

Before you start — prerequisites

• A Google account with edit access to the spreadsheet you will use.
• An approved WhatsApp Business account (Meta) with access token, Phone Number ID and WABA ID.
• Basic familiarity with Google Apps Script (we provide scripts you can copy & deploy).
• ETIP Add-on installed in your Google Sheets (Extensions → ETIP WhatsApp Management).

1. Install & Open the Add-on

1. Open the Google Sheet you want to use for messaging.
2. Install the ETIP Add-on (from your Add-on package or Workspace Marketplace).
3. Open it via Extensions → ETIP WhatsApp → Setup.

2. Save Meta Credentials in Setup

In the Setup panel paste your Meta details:

• Phone Number ID — your Meta phone id (e.g. 752371524624857)
• WABA ID — WhatsApp Business Account ID
• Permanent Access Token — long lived token from Meta Business
• API Version — default v21.0 (or as provided by Meta)
• Default Country Code — e.g. +91
• Optional: Sheet ID — leave blank to use current spreadsheet

Click Save Settings. You should see a success toast.

3. Deploy the User WebApp (Webhook)

The webhook receives incoming messages from Meta and writes them to your Messages sheet. Follow these steps:

1. Open Extensions → Apps Script in your spreadsheet (or create a new Apps Script project).
2. Create a new file (e.g., webhook.gs) and paste this minimal webhook code:

/* Minimal WebApp for Meta → writes incoming events to 'Messages' sheet */
function doGet(e){
  // Used for verification (verify token)
  const verifyToken = PropertiesService.getUserProperties().getProperty('verifyToken') || 'etip_verify_token';
  if (e.parameter && e.parameter['hub.mode']) {
    if (e.parameter['hub.verify_token'] === verifyToken) {
      return ContentService.createTextOutput(e.parameter['hub.challenge']);
    }
    return ContentService.createTextOutput('Invalid verify token');
  }
  return ContentService.createTextOutput('ETIP Webhook');
}

function doPost(e){
  try{
    const ssId = PropertiesService.getUserProperties().getProperty('sheetId'); // set in Setup
    const ss = SpreadsheetApp.openById(ssId);
    const sh = ss.getSheetByName('Messages') || ss.insertSheet('Messages');
    // Ensure headers exist (first row)
    const headers = ['Timestamp','From','FromCountry','To','TemplateName','Type','Body','Text','MediaURL','MediaMime','MessageID','Status','Direction','ThreadID','MetaEventJSON'];
    if (sh.getLastRow() === 0) sh.appendRow(headers);

    const raw = e.postData && e.postData.contents ? e.postData.contents : '{}';
    const ev = JSON.parse(raw);

    // Parse minimal fields (adjust as needed)
    const contact = ev?.contacts?.[0]?.wa_id || '';
    const phone_to = ev?.metadata?.display_phone_number || '';
    const msg = ev?.messages?.[0] || {};
    const text = msg?.text?.body || '';
    const messageId = msg?.id || Utilities.getUuid();
    const now = new Date();

    const row = [
      now,
      contact,
      '',
      phone_to,
      '',
      msg.type || 'text',
      JSON.stringify(msg),
      text,
      '',
      '',
      messageId,
      'RECEIVED',
      'IN',
      contact,
      JSON.stringify(ev)
    ];
    sh.appendRow(row);
    return ContentService.createTextOutput('ok');
  }catch(err){
    return ContentService.createTextOutput('error:'+err.message);
  }
}
      

3. Deploy → New deployment → choose Web app.
4. Set Execute as = Me and Who has access = Anyone (or Anyone with link), then click Deploy.
5. Copy the Web App URL and paste it into the Add-on Setup → Webhook URL field → Save.

Tip:

Before deploying, run a small Apps Script function to save your verify token:

function setVerifyToken(){
  PropertiesService.getUserProperties().setProperty('verifyToken','etip_verify_token');
}
      

Run it once from the Apps Script editor to set the verify token used during Meta webhook verification.

4. Subscribe Webhook in Meta (Developer Portal)

1. Open Meta for Developers → App Dashboard → Add Product → Webhooks.
2. Subscribe to your WhatsApp Business Account and add the WebApp URL. Use the verify token etip_verify_token (or your custom token).
3. Select fields to subscribe (messages).

Once subscribed, incoming messages will be forwarded to your WebApp and recorded in the Messages sheet.

5. Configure Messages Sheet & Test

1. Open the spreadsheet you saved in Setup (or set Sheet ID in Setup to use this file).
2. Ensure a sheet named Messages exists with headers (the webhook script will create them if missing).
3. Send a test message to your WhatsApp Business number. The webhook should append a row in Messages.
4. Open Add-on → Messages tab to view and reply (Pro users).

6. Common Troubleshooting

• No messages in sheet? Confirm your WebApp URL is the same one subscribed in Meta and that the WebApp deployment is the newest version.
• Webhook verification failed? Make sure the verify token you set via setVerifyToken() matches the token you used in Meta.
• Messages appear in a different spreadsheet? Check the sheetId saved in PropertiesService (Setup). The webhook writes to the sheetId set there.
• 403 / Unauthorized while sending? Verify your Meta token and phone ID in Setup are correct and active.

7. Quick Tests

1. Run the Apps Script function below to simulate a webhook POST (for debugging):

function testSimulateMetaWebhook(){
  const url = ScriptApp.getService().getUrl(); // or your deployed webapp URL
  const payload = {
    "object":"whatsapp_business_account",
    "entry":[
      {"id":"1","changes":[{"value":{"metadata":{"display_phone_number":"919286412427","phone_number_id":"752371524624857"},"contacts":[{"profile":{"name":"Tester"},"wa_id":"918218901242"}],"messages":[{"from":"918218901242","id":"wamid.TEST","timestamp":"1234567890","text":{"body":"Hello test"},"type":"text"}]}}]}
    ]
  };
  const opts = {method:'post',contentType:'application/json',payload:JSON.stringify(payload),muteHttpExceptions:true};
  const res = UrlFetchApp.fetch(url,opts);
  Logger.log('Simulated response: ' + res.getContentText());
}
      

Open Apps Script → Run → check Logs (View → Logs) to confirm the deployment writes to your Messages sheet.

8. Next steps in the Add-on

• Open Send Template to fetch your Meta-approved templates and map placeholders.
• Use the Messages panel to read and reply (Pro users).
• For automation & bot features — consider the SaaS upgrade (future roadmap).