# Splashify Pro — Complete User Documentation

> This is the full-text version of the Splashify Pro user documentation.
> Generated for AI consumption. Source: https://docs.splashifypro.com
> Generated at: 2026-05-11T17:06:18.438Z

> Total pages: 156

---

========================================================================
## Splashify Pro Documentation
URL: https://docs.splashifypro.com/
========================================================================

# Splashify Pro Documentation

Welcome to the official documentation for **Splashify Pro** — your all-in-one WhatsApp Business messaging platform. Send broadcasts, automate conversations with AI chatbots, manage contacts, run calling campaigns, and track everything from a single dashboard.

## Platform Overview

| Feature | Description |
|---------|-------------|
| **Messaging** | Real-time WhatsApp conversations with your customers |
| **Broadcasts** | Send bulk WhatsApp & RCS campaigns to targeted segments |
| **AI Agents** | Automate replies with GPT-powered Chat AI Agents |
| **Chatbot Flows** | Build no-code workflow bots with a visual flow builder |
| **Calling** | WhatsApp Business voice calls with recordings |
| **Contacts** | Full CRM with segments, tags, and custom attributes |
| **Templates** | Manage Meta-approved message templates |
| **Analytics** | Track message volume, costs, and campaign performance |

## Quick Links

- [**Get Started →**](/getting-started) — Create your account and connect WhatsApp
- [**WhatsApp Setup →**](/whatsapp-setup) — Connect your WABA and verify your business
- [**Send a Broadcast →**](/broadcasts) — Reach thousands of contacts in one click
- [**Build a Chatbot →**](/ai-agents) — Automate your customer conversations
- [**API & Developer →**](/settings/developer) — Integrate Splashify Pro into your own apps

## App URL

Access your dashboard at:

```
https://app.splashifypro.com
```

## Support

- **Email:** support@splashifypro.in
- **WhatsApp:** Message us directly from the [Support](/support) section in your dashboard


========================================================================
## Getting Started
URL: https://docs.splashifypro.com/getting-started
========================================================================

# Getting Started

Get your Splashify Pro account up and running in minutes. This section covers account creation, login, and an orientation to the dashboard.

## What You'll Need

- A valid business email address
- A WhatsApp Business phone number (for connecting WhatsApp)
- A Meta Business account (required to connect WABA)

## Steps at a Glance

1. **[Sign Up](/getting-started/signup)** — Create your account with email and OTP verification
2. **[Log In](/getting-started/login)** — Secure login with optional 2FA
3. **[Dashboard](/getting-started/dashboard)** — Understand the dashboard layout and setup checklist
4. **[Connect WhatsApp](/whatsapp-setup)** — Link your WhatsApp Business Account

## Platform URLs

| Portal | URL |
|--------|-----|
| App Dashboard | `https://app.splashifypro.com` |
| API Base URL | `https://apis.splashifypro.com/api/v1/` |

> **Tip:** Splashify Pro works best on desktop Chrome or Edge. Mobile support is available but some features (like the flow builder) are optimized for desktop.


========================================================================
## Dashboard
URL: https://docs.splashifypro.com/getting-started/dashboard
========================================================================

# Dashboard

Your dashboard is the central hub for your Splashify Pro account. It shows your setup status, key metrics, and quick-access actions.

## Dashboard Sections

### Setup Checklist

When you first sign up, the dashboard shows a **Setup Checklist** with the steps needed to get fully operational:

| Step | Description |
|------|-------------|
| **Connect WhatsApp** | Link your WhatsApp Business Account (WABA) |
| **Add Wallet Balance** | Recharge your wallet to send messages |
| **Complete KYC** | Verify your business identity |
| **Apply for OBA** | Apply for Official Business Account (green tick) |
| **Set Up Billing** | Add your GSTIN for invoice generation |

Each step shows as ✅ complete or ⏳ pending. Click any step to navigate to the relevant settings page.

### Wallet Balance

The top bar shows your current **wallet balance**. Click it to:
- View transaction history
- Recharge your wallet via Zoho Payments

> Wallet balance is deducted per message sent based on your plan's pricing.

### Announcement Banner

If there are any active system announcements (maintenance, new features, incidents), they appear as a cycling banner at the top of the dashboard.

## Sidebar Navigation

| Section | What it Does |
|---------|-------------|
| **Dashboard** | Setup status and overview |
| **Messages** | Real-time conversation inbox |
| **Contacts** | CRM — manage contacts, segments, tags |
| **Broadcasts** | Create and manage bulk campaigns |
| **AI Agents** | Chat AI Agents and Workflow Bots |
| **Templates** | WhatsApp & RCS message templates |
| **Flows** | WhatsApp Flows management |
| **Calling** | WhatsApp Business Calling |
| **Analytics** | Message stats and expense tracking |
| **Track Expenses** | Billing log and cost breakdown |
| **Wallet** | Balance and transactions |
| **Support** | Create and track support tickets |
| **Settings** | All account, team, and integration settings |

## Notifications

The bell icon in the top bar shows unread activity notifications. Click to view recent events such as:
- New incoming messages
- Broadcast completion
- Low wallet balance alert
- KYC status updates

## Low Balance Alert

When your wallet balance falls below a threshold, a **Low Balance Dialog** pops up prompting you to recharge before messages are blocked.


========================================================================
## Login & 2FA
URL: https://docs.splashifypro.com/getting-started/login
========================================================================

# Login & 2FA

## Standard Login

1. Go to [https://app.splashifypro.com/auth/login](https://app.splashifypro.com/auth/login)
2. Enter your **email address** and **password**
3. Click **Sign In**

If you have **Two-Factor Authentication (2FA)** enabled, you'll be prompted for a verification code before accessing the dashboard.

## Two-Factor Authentication (2FA)

2FA adds an extra layer of security. When enabled, every login requires a one-time code sent to your registered email or WhatsApp.

### 2FA Verification Steps

1. After entering your password, the 2FA screen appears
2. Check your **email** or **WhatsApp** for the 6-digit code
3. Enter the code and click **Verify**

> **2FA codes expire after 10 minutes.** Request a new code if needed.

## Team Member Login

Team members added by the account owner log in with a **password set via invitation email**.

1. Click the link in your invitation email
2. Set your password on the `/auth/set-team-password` page
3. Log in at the standard login page with your email and new password

## Forgot Password

1. Click **Forgot Password** on the login page
2. Enter your registered email address
3. Check your inbox for a password reset link
4. Click the link and set a new password

The reset link is valid for **30 minutes**.

## Session Management

- Sessions last **3 months** — you stay logged in unless you explicitly sign out
- A maximum of **5 concurrent devices** can be active at once
- If you log in on a 6th device, you'll be shown a list of active sessions to revoke one

### View Active Devices

Go to **Settings → Devices** to:
- See all active sessions (device, IP address, last seen)
- Identify which session is the current device
- Remotely log out any device

> Logging out a device takes effect immediately — that session is instantly invalidated.

## Troubleshooting

| Issue | Fix |
|-------|-----|
| Wrong password | Use **Forgot Password** to reset |
| 2FA code not received | Check spam/junk; request a new code |
| Account locked | Contact support@splashifypro.in |
| Device limit reached | Revoke an old session from the device list shown at login |


========================================================================
## Sign Up
URL: https://docs.splashifypro.com/getting-started/signup
========================================================================

# Sign Up

Create your Splashify Pro account in under 2 minutes.

## Step 1: Go to the Sign Up Page

Navigate to [https://app.splashifypro.com/auth/signup](https://app.splashifypro.com/auth/signup)

## Step 2: Enter Your Details

Fill in the registration form:

| Field | Description |
|-------|-------------|
| **Full Name** | Your name or business contact name |
| **Email Address** | Your business email — used for login and notifications |
| **Phone Number** | Mobile number with country code (e.g. `+91 9876543210`) |
| **Password** | Minimum 8 characters |
| **Organization Name** | Your company or brand name |
| **Country** | Select your country from the dropdown |

## Step 3: Verify Your Email (OTP)

After submitting the form, you'll be redirected to the **OTP Verification** screen.

1. Check your inbox for an email from `noreply@splashifypro.com`
2. Enter the **6-digit OTP** in the verification field
3. Click **Verify**

> **OTP expires in 10 minutes.** Click **Resend OTP** if you don't receive it within 60 seconds.

## Step 4: You're In!

After successful verification, you'll land on your **Dashboard** with a setup checklist.

The first thing you'll want to do is [connect your WhatsApp Business Account](/whatsapp-setup/connect-waba).

## Already Have an Account?

[Log in here →](/getting-started/login)

## Troubleshooting

| Issue | Fix |
|-------|-----|
| OTP not received | Check spam/junk folder; click Resend OTP |
| Email already registered | Use the [Login](/getting-started/login) page or reset your password |
| OTP invalid | OTPs expire after 10 minutes — request a new one |


========================================================================
## WhatsApp Setup
URL: https://docs.splashifypro.com/whatsapp-setup
========================================================================

# WhatsApp Setup

To send and receive WhatsApp messages through Splashify Pro, you need to connect a **WhatsApp Business Account (WABA)** and register a phone number.

## Setup Flow

```
Meta Business Account
        ↓
  Connect WABA (Embedded Signup)
        ↓
  Register Phone Number
        ↓
  Complete KYC (Business Verification)
        ↓
  Start Messaging ✓
```

## Prerequisites

Before you start, make sure you have:

- A **Meta Business Account** — [create one at business.facebook.com](https://business.facebook.com)
- A **phone number** that is NOT already registered on WhatsApp personal or WhatsApp Business App
- A valid **business website** or Facebook Page
- Business address and category details

> **Important:** You cannot use a phone number that is currently active on the WhatsApp mobile app. You must first delete or deregister that number from the app.

## Quick Setup Checklist

| Step | Action | Status |
|------|--------|--------|
| 1 | Connect WABA via Meta Embedded Signup | Required |
| 2 | Register your phone number | Required |
| 3 | Submit KYC documents | Required |
| 4 | Apply for Official Business Account (OBA) | Optional |


========================================================================
## Connect WhatsApp (WABA)
URL: https://docs.splashifypro.com/whatsapp-setup/connect-waba
========================================================================

# Connect WhatsApp (WABA)

Splashify Pro uses **Meta Embedded Signup** to connect your WhatsApp Business Account (WABA) securely without sharing your Meta credentials.

## Step 1: Open the Setup Wizard

1. Go to your **Dashboard**
2. Click **Connect WhatsApp** in the setup checklist, or navigate to **Settings → Channels**
3. Click **Connect WhatsApp Business Account**

## Step 2: Start Meta Embedded Signup

A **Meta popup window** will open. Follow the steps inside it:

1. **Log in with Facebook** — Use the Facebook account connected to your Meta Business Manager
2. **Select or Create a Business Portfolio** — Choose your existing Meta Business Account or create a new one
3. **Create or Select a WABA** — Either pick an existing WhatsApp Business Account or create a new one
4. **Select or Create a Phone Number** — Choose a phone number to register
5. **Verify the Phone Number** — Enter the OTP sent via SMS or voice call to that number
6. **Complete Signup** — Click Finish to return to Splashify Pro

## Step 3: Wait for Connection

After the popup closes, Splashify Pro automatically:
- Receives your WABA ID and Phone Number ID from Meta
- Creates your WhatsApp channel in the system
- Registers the webhook for receiving messages

This usually takes **10–30 seconds**. Your dashboard will refresh and show your WABA as **Connected**.

## WABA Status Indicators

| Status | Meaning |
|--------|---------|
| 🟢 **Connected** | WABA is active, messages can be sent/received |
| 🟡 **Pending** | Waiting for Meta approval |
| 🔴 **Restricted** | Account has messaging restrictions from Meta |
| ⚪ **Not Connected** | No WABA linked yet |

## Troubleshooting

| Issue | Fix |
|-------|-----|
| Popup blocked | Allow popups from `app.splashifypro.com` in browser settings |
| Phone number already used | Deregister the number from WhatsApp app first |
| Business not verified | Complete Meta Business Verification at business.facebook.com |
| Signup failed | Ensure you have admin access to the Meta Business Account |

## Next Step

After connecting your WABA, [register your phone number →](/whatsapp-setup/phone-registration)


========================================================================
## Business Verification (KYC)
URL: https://docs.splashifypro.com/whatsapp-setup/kyc
========================================================================

# Business Verification (KYC)

KYC (Know Your Customer) verification unlocks higher messaging tiers and is required for sending broadcasts to large audiences.

## Why KYC is Required

| Without KYC | With KYC |
|-------------|----------|
| Limited to 250 conversations/day | Starts at 1,000 conversations/day |
| Can only message users who messaged first | Can send outbound template messages |
| No broadcast campaigns | Full broadcast access |

## Step 1: Navigate to KYC

1. Go to **Dashboard**
2. Click **Complete KYC** in the setup checklist
3. Or navigate to **Settings → Account Details → KYC**

## Step 2: Submit Business Documents

Fill out the KYC form with the following information:

### Business Details

| Field | Description |
|-------|-------------|
| **Legal Business Name** | Exact name as registered (must match government records) |
| **Business Type** | Sole Proprietor, Private Limited, LLP, etc. |
| **GSTIN** | Your GST Identification Number (for Indian businesses) |
| **Business Address** | Registered office address with PIN code |
| **Business Category** | Industry category (e.g. E-Commerce, Healthcare, Education) |
| **Website URL** | Your business website |

### Required Documents

| Document | Accepted Formats |
|----------|-----------------|
| **Business Registration Certificate** | PDF, JPG, PNG (max 5MB) |
| **GST Certificate** | PDF, JPG, PNG (max 5MB) |
| **Proof of Address** | Utility bill or bank statement |
| **Authorized Signatory ID** | Aadhaar, PAN, Passport |

## Step 3: Submit for Review

Click **Submit KYC**. Our team reviews submissions within **1–3 business days**.

## KYC Status

| Status | Meaning |
|--------|---------|
| **Not Submitted** | KYC form not yet filled |
| **Pending** | Under review by Splashify Pro team |
| **Approved** ✅ | Verified — higher limits unlocked |
| **Rejected** ❌ | Resubmission required (reason provided) |

> You'll receive an email notification when your KYC status changes.

## After KYC Approval

Once approved:
- Messaging limits increase automatically
- You become eligible to [apply for Official Business Account](/whatsapp-setup/oba)
- Broadcast campaigns to large segments are unlocked


========================================================================
## Official Business Account (OBA)
URL: https://docs.splashifypro.com/whatsapp-setup/oba
========================================================================

# Official Business Account (OBA)

An **Official Business Account** (OBA) gives your business the green tick ✅ badge on WhatsApp, increasing trust and improving message open rates.

## What is OBA?

The OBA badge appears next to your business name in customer chats. It signals that Meta has verified your business as legitimate and notable.

**Benefits:**
- Green checkmark next to your display name
- Higher customer trust and engagement
- Eligibility for higher message tier limits
- Better deliverability on broadcast campaigns

## Requirements

Before applying, ensure:

1. ✅ WABA is connected and phone number registered
2. ✅ KYC is approved
3. ✅ Business has an active online presence (website, social media)
4. ✅ Business meets Meta's notability criteria

> **Note:** OBA is granted by Meta, not Splashify Pro. Approval is at Meta's discretion and typically takes **5–15 business days**.

## How to Apply

1. Go to **Dashboard**
2. Click **Apply for OBA** in the setup checklist
3. Complete the OBA application form:
   - Confirm your business name and category
   - Provide business website URL
   - Optionally link your Facebook Page
4. Click **Submit Application**

Splashify Pro submits the application to Meta on your behalf.

## Application Status

| Status | Meaning |
|--------|---------|
| **Not Applied** | Application not submitted |
| **Submitted** | Application sent to Meta, awaiting review |
| **Approved** 🟢 | Green tick active on your WABA |
| **Rejected** | Application denied — review Meta's feedback and reapply after 30 days |

## Tips for Approval

- Ensure your business name on WABA matches your official business name
- Have an active, professional website (no landing page builders)
- Active presence on social media and Google My Business helps
- Avoid generic or ambiguous business names


========================================================================
## Register Phone Number
URL: https://docs.splashifypro.com/whatsapp-setup/phone-registration
========================================================================

# Register Phone Number

After connecting your WABA, you need to formally register your phone number with the WhatsApp Business Platform to enable two-way messaging.

## Step 1: Go to Phone Registration

1. Navigate to **Dashboard** or **Settings → Channels**
2. Click **Register Phone Number** next to your connected WABA

## Step 2: Choose Verification Method

Select how you want to receive the verification PIN:

- **SMS** — A 6-digit PIN sent via text message
- **Voice Call** — A voice call reads out the PIN

> **Note:** If your number is a VoIP or landline, choose **Voice Call**.

## Step 3: Enter the PIN

Enter the 6-digit PIN you receive and click **Verify & Register**.

## Step 4: Confirm Registration

Once verified, your phone number status changes to **Registered**. You can now:
- Send and receive WhatsApp messages
- Use approved message templates
- Create broadcast campaigns

## Phone Number Requirements

| Requirement | Details |
|-------------|---------|
| Not on WhatsApp App | Number must be deregistered from the consumer WhatsApp app |
| Can receive SMS/calls | The number must be able to receive SMS or voice calls |
| Country code | Must include full international country code |

## Display Name

When registering, your WABA's **display name** is shown to customers. This name:
- Is set during the Meta Embedded Signup
- Must match your business name
- Can be changed later in Meta Business Settings (subject to approval)

## Troubleshooting

| Issue | Fix |
|-------|-----|
| PIN not received | Check if the number can receive SMS; try voice call |
| Registration failed | Ensure the number is not active on WhatsApp app |
| Number already registered | Contact support to transfer the number |

## Next Step

[Complete KYC (Business Verification) →](/whatsapp-setup/kyc)


========================================================================
## Messaging
URL: https://docs.splashifypro.com/messaging
========================================================================

# Messaging

The **Messages** page is your real-time inbox for all WhatsApp conversations. View, reply, assign, and resolve conversations from one unified interface.

## Navigate to Messages

Click **Messages** in the left sidebar, or go to:

```
https://app.splashifypro.com/messages
```

## Inbox Layout

The Messages page has three panels:

| Panel | Description |
|-------|-------------|
| **Conversation List** (left) | All conversations, filterable by status and assignee |
| **Message Thread** (center) | The active conversation with full chat history |
| **Contact Details** (right) | Contact info, tags, notes, and activity log |

## Conversation Statuses

| Status | Meaning |
|--------|---------|
| **Open** | Active conversation, needs attention |
| **Resolved** | Conversation marked as done |
| **All** | Shows all conversations |

## Real-Time Updates

Conversations update in real-time via WebSocket. New incoming messages appear instantly without needing to refresh the page. A notification badge shows unread message counts.

## Key Features

- **Infinite scroll** — Load older messages as you scroll up
- **Media support** — View images, videos, documents, and audio directly in the thread
- **Voice messages** — Play audio directly in the browser
- **Template messages** — Send approved WhatsApp templates from the message input
- **Interactive messages** — View button replies and list selections
- **Optimistic UI** — Messages appear immediately after sending, even before server confirmation


========================================================================
## Assign & Resolve
URL: https://docs.splashifypro.com/messaging/assign-resolve
========================================================================

# Assign & Resolve

## Assigning a Conversation

Assign conversations to specific team members to route customer queries to the right person.

1. Open a conversation
2. Click the **Assign** button in the conversation header (top right)
3. Select a team member from the dropdown
4. The conversation is now assigned and the agent is notified

> When a conversation is assigned to a human agent, the AI chatbot automatically **pauses** and does not send automated replies — the human takes over.

### Unassigning

To unassign, click the assignee's name and select **Unassign**. This hands the conversation back to automated handling.

## Resolving a Conversation

Mark a conversation as resolved when the customer query is complete.

1. Click **Resolve** (✓) in the conversation header
2. The conversation moves to the **Resolved** tab
3. If the customer replies again, the conversation automatically **reopens** as Open

## Auto-Resolve

Configure conversations to auto-resolve after inactivity:

1. Go to **Settings → Live Chat**
2. Enable **Auto-Resolve**
3. Set the inactivity period (e.g. 24 hours, 48 hours)

Conversations that have no new messages for the configured period will automatically be resolved.

## Off-Hours Handling

You can configure what happens when customers message outside your working hours:

1. Go to **Settings → Live Chat**
2. Set **Working Hours** (Mon–Sat, 9AM–6PM, etc.)
3. Set an **Off-Hours Message** (e.g. "We're closed right now. We'll reply tomorrow morning.")
4. Toggle **Auto-Resolve outside working hours** if needed

## Welcome Message

Send a welcome message automatically when a new conversation starts:

1. Go to **Settings → Live Chat**
2. Enable **Welcome Message**
3. Write your welcome text
4. Save

The welcome message is sent once per new contact when they first message you.


========================================================================
## Conversations
URL: https://docs.splashifypro.com/messaging/conversations
========================================================================

# Conversations

## Conversation List

The left panel shows all your WhatsApp conversations. Each conversation card shows:

- **Contact name** (or phone number if unnamed)
- **Last message preview**
- **Time** of last message
- **Assignee** (team member or unassigned)
- **Unread badge** for unread messages

## Filtering Conversations

Use the filter bar above the conversation list to narrow down results:

| Filter | Description |
|--------|-------------|
| **Status** | Open, Resolved, or All |
| **Assigned to Me** | Only show conversations assigned to you |
| **Unassigned** | Conversations not assigned to any team member |
| **Search** | Search by contact name or phone number |

## Opening a Conversation

Click any conversation card to open it in the center panel. The message thread loads the last 50 messages and supports scrolling back to older messages.

## Message Thread

Inside a conversation, messages are displayed chronologically:

- **Inbound messages** (from customers) appear on the **left**
- **Outbound messages** (from your team) appear on the **right**
- Message **delivery status** icons: Sent ✓, Delivered ✓✓, Read 🔵✓✓
- **Timestamp** shown on each message

### Message Types Supported

| Type | Description |
|------|-------------|
| Text | Plain text messages |
| Image | JPEG, PNG images with caption |
| Video | MP4 videos with caption |
| Document | PDF, DOCX, and other files |
| Audio | Voice messages with inline player |
| Location | GPS coordinates shown on map link |
| Contacts | vCard contacts |
| Interactive (Buttons) | Quick reply and CTA buttons |
| Interactive (List) | List picker messages |
| Template | Approved WhatsApp template messages |

## Contact Details Panel

The right panel shows details about the selected conversation's contact:

- **Name, phone, email**
- **Tags** — add/remove tags to segment contacts
- **Custom attributes** — any custom contact fields you've defined
- **Assigned agent** — who is handling this conversation
- **Activity log** — history of actions taken on this contact
- **Call button** — initiate a WhatsApp call directly


========================================================================
## Live Chat Settings
URL: https://docs.splashifypro.com/messaging/live-chat
========================================================================

# Live Chat Settings

Configure how Splashify Pro handles conversations automatically.

Navigate to **Settings → Live Chat**.

## Welcome Message

An automatic message sent when a customer starts a new conversation.

| Setting | Description |
|---------|-------------|
| **Enable** | Toggle welcome message on/off |
| **Message Text** | The text sent to new customers |

## Off-Hours Message

Sent automatically when a customer messages outside your working hours.

| Setting | Description |
|---------|-------------|
| **Enable** | Toggle off-hours reply on/off |
| **Message Text** | E.g. "Thanks for reaching out! Our team is available Mon–Sat 9AM–6PM IST." |

## Working Hours

Define when your team is available:

1. Select each day of the week
2. Set **From** and **To** time for each active day
3. Choose your **timezone**
4. Save

Outside these hours, the off-hours message is triggered automatically.

## Auto-Resolve

Automatically resolve conversations after a period of inactivity.

| Setting | Description |
|---------|-------------|
| **Enable** | Toggle auto-resolve on/off |
| **Inactivity Period** | Time without reply before auto-resolving (e.g. 24h, 48h, 7 days) |

> **Tip:** Use auto-resolve with welcome messages so resolved conversations restart cleanly when customers message again.


========================================================================
## Sending Messages
URL: https://docs.splashifypro.com/messaging/send-messages
========================================================================

# Sending Messages

## Message Input Bar

The message input bar is at the bottom of the conversation thread.

### Send a Text Message

1. Click in the message input field
2. Type your message
3. Press **Enter** or click the **Send** button

### Send Media

Click the **attachment icon (📎)** to attach:

| Type | Max Size | Formats |
|------|----------|---------|
| Image | 5 MB | JPEG, PNG, WebP |
| Video | 16 MB | MP4, 3GP |
| Document | 100 MB | PDF, DOCX, XLSX, etc. |
| Audio | 16 MB | MP3, OGG, AMR |

Add an optional caption for images and videos.

### Send a Template Message

Templates are pre-approved messages you can send outside the **24-hour customer service window**.

1. Click the **template icon (📄)** in the message bar
2. Search or browse approved templates
3. Fill in any variable placeholders (e.g. `{{customer_name}}`, `{{order_id}}`)
4. Click **Send**

> **When to use templates:** WhatsApp only allows free-form messages within 24 hours of the customer's last message. After 24 hours, you must use an approved template.

### Send a Canned Message

Canned messages are pre-saved reply shortcuts.

1. Type `/` in the message input to open the canned message picker
2. Search by keyword
3. Select a canned message to insert it instantly

Manage your canned messages at **Settings → Canned Messages**.

## Message Status

| Icon | Status |
|------|--------|
| ⏳ | Sending |
| ✓ | Sent (reached WhatsApp servers) |
| ✓✓ | Delivered (reached the recipient's device) |
| 🔵 ✓✓ | Read (recipient opened the message) |
| ❌ | Failed — check error details |

## 24-Hour Messaging Window

WhatsApp's policy:

- **Within 24 hours** of the customer's last message: send any message type freely
- **After 24 hours**: only approved **template messages** can be sent

The conversation thread shows a banner when the 24-hour window has passed.


========================================================================
## Contacts
URL: https://docs.splashifypro.com/contacts
========================================================================

# Contacts

The **Contacts** section is your customer CRM. Store, organize, and segment your contacts to power targeted broadcasts and personalized conversations.

## Navigate to Contacts

Click **Contacts** in the left sidebar, or go to:

```
https://app.splashifypro.com/contacts
```

## What You Can Do

| Feature | Description |
|---------|-------------|
| **Add contacts** | Manually create contacts one by one |
| **Import contacts** | Bulk upload from CSV |
| **Edit & delete** | Update or remove contact records |
| **Tag contacts** | Apply labels for categorization |
| **Create segments** | Build filtered lists for targeted broadcasts |
| **Custom attributes** | Add extra fields (e.g. "Order ID", "City") |
| **Block/Unblock** | Prevent or restore messaging for a contact |

## Contact Fields

Each contact record contains:

| Field | Description |
|-------|-------------|
| **Name** | Full name |
| **Phone** | WhatsApp number with country code |
| **Email** | Optional email address |
| **Tags** | Labels applied to this contact |
| **Custom Columns** | Any custom attributes you've created |
| **Created At** | When the contact was added |
| **Last Activity** | Timestamp of last interaction |


========================================================================
## Custom Attributes
URL: https://docs.splashifypro.com/contacts/attributes
========================================================================

# Custom Attributes

**Custom Attributes** (also called contact columns) let you store extra data fields on contacts beyond the defaults — for example, "Order ID", "City", "Plan Type", "Subscription Date".

## Manage Custom Attributes

1. Go to **Settings → Attributes**
2. View existing custom attributes
3. Click **+ Add Attribute** to create a new field

### Attribute Settings

| Field | Options |
|-------|---------|
| **Name** | Display name (e.g. "City") |
| **Key** | API key (auto-generated from name, e.g. `city`) |
| **Type** | Text, Number, Date, Boolean |

## Supported Attribute Types

| Type | Example Values |
|------|---------------|
| **Text** | "Mumbai", "Premium", "Order #123" |
| **Number** | `1500`, `99.99` |
| **Date** | `2024-01-15` |
| **Boolean** | `true` / `false` |

## Set Attribute Values

### On a Contact

1. Open a contact
2. Scroll to the **Custom Attributes** section
3. Click the field and enter the value
4. It saves automatically

### Via CSV Import

Include columns matching your attribute keys:

```csv
name,phone,city,plan_type
John Doe,+919876543210,Mumbai,Pro
```

### Via Chatbot Flow

The **Update Column** node in the flow builder can set attribute values based on user input during a chatbot conversation.

## Using Attributes in Segments

Filter contacts by custom attributes when creating segments:

- **Condition:** `city → equals → Mumbai`
- **Condition:** `plan_type → equals → Pro`

## Using Attributes in Templates

Reference attributes in message templates with `{{variable_name}}` syntax. During broadcast creation, map each variable to a contact attribute.


========================================================================
## Import Contacts
URL: https://docs.splashifypro.com/contacts/import
========================================================================

# Import Contacts

Import thousands of contacts at once using a CSV file.

## Step 1: Prepare Your CSV

Your CSV must have at minimum a **phone** column. Recommended columns:

```csv
name,phone,email,city,tag
John Doe,+919876543210,john@example.com,Mumbai,vip
Jane Smith,+918765432109,jane@example.com,Delhi,
```

### Column Rules

| Column | Required | Notes |
|--------|----------|-------|
| `phone` | ✅ Yes | Include country code (e.g. `+91`) |
| `name` | Optional | Falls back to phone if blank |
| `email` | Optional | Must be valid email format |
| Any other column | Optional | Treated as custom attribute |

> **Phone format:** Include the `+` and country code. Numbers without country code may fail to match existing contacts.

## Step 2: Open Import Dialog

1. Go to **Contacts**
2. Click **Import Contacts**
3. Click **Choose File** and select your CSV

## Step 3: Review and Import

The import is automatic:
- **New contacts** are created
- **Existing contacts** (matched by phone) are updated
- **Invalid rows** (bad phone format, missing required field) are skipped
- **Previously deleted contacts** are restored if they match by phone

## Step 4: View Results

After the import completes, a summary appears:

| Metric | Description |
|--------|-------------|
| **Created** | New contacts added |
| **Updated** | Existing contacts updated |
| **Skipped** | Invalid or duplicate entries |
| **Failed** | Rows that couldn't be processed |

## Tips

- Always include country codes in phone numbers
- Use UTF-8 encoding for your CSV (especially for non-English names)
- Maximum recommended import size: **50,000 rows** per file
- Headers are case-insensitive (`Phone`, `phone`, `PHONE` all work)


========================================================================
## Manage Contacts
URL: https://docs.splashifypro.com/contacts/manage-contacts
========================================================================

# Manage Contacts

## Add a Contact Manually

1. Go to **Contacts**
2. Click **+ Add Contact**
3. Fill in the form:
   - **Name** (required)
   - **Phone Number** (required — include country code, e.g. `+919876543210`)
   - **Email** (optional)
   - Any **custom attributes** you've configured
4. Click **Save**

## Edit a Contact

1. Click on any contact row to open the contact detail
2. Click **Edit**
3. Update the fields
4. Click **Save**

## Delete a Contact

1. Click on a contact row
2. Click the **Delete** button (trash icon)
3. Confirm deletion

> Deleting a contact removes them from all segments but does **not** delete their message history.

## Search & Filter

Use the search bar at the top of the Contacts page to find contacts by:
- Name
- Phone number
- Email

## Block / Unblock

Blocking prevents any outbound messages (including broadcasts) from reaching a contact.

1. Open a contact
2. Click **Block Contact**
3. Confirm

To unblock, open the same contact and click **Unblock**.

## Opt-Out Management

If a contact replies with opt-out keywords (e.g. "STOP", "Unsubscribe"), they are automatically flagged.

Manage opt-outs at **Settings → Opt Management**.


========================================================================
## Segments
URL: https://docs.splashifypro.com/contacts/segments
========================================================================

# Segments

**Segments** are dynamic filtered lists of contacts based on conditions. Use segments as broadcast audiences to target the right customers.

## Navigate to Segments

Go to **Settings → Segments**, or access segments during broadcast creation.

## Create a Segment

1. Go to **Settings → Segments**
2. Click **+ Create Segment**
3. Enter a **segment name** (e.g. "Mumbai VIP Customers")
4. Add **filter conditions** using the condition builder:

### Filter Conditions

| Field Type | Available Operators |
|------------|-------------------|
| Contact name | contains, equals, starts with |
| Phone number | contains, equals |
| Tag | has tag, does not have tag |
| Custom attribute | equals, contains, greater than, less than |
| Created date | before, after, between |

### Combining Conditions

- **AND** — Contact must match all conditions
- **OR** — Contact must match at least one condition

**Example:** `Tag = "premium"` AND `City = "Mumbai"` → Only premium contacts from Mumbai

## View Segment Contacts

1. Open a segment
2. Click **Preview Contacts** to see the matching contacts
3. The **contact count** updates automatically as contacts are added/removed

## Edit a Segment

1. Open the segment
2. Click **Edit**
3. Modify the conditions
4. Save — the segment updates immediately

## Delete a Segment

1. Open the segment
2. Click **Delete Segment**
3. Confirm

> Deleting a segment does not delete the contacts in it.

## Using Segments in Broadcasts

When creating a broadcast:
1. Go to the **Audience** step
2. Select **Segment** as the source
3. Choose your segment
4. The recipient count is estimated based on current segment members

Segments are evaluated at **broadcast send time**, so contacts added after scheduling will be included.


========================================================================
## Tags
URL: https://docs.splashifypro.com/contacts/tags
========================================================================

# Tags

Tags are simple labels you can apply to contacts to categorize them (e.g. "VIP", "Lead", "Churned", "New Customer").

## Manage Tags

1. Go to **Settings → Tags**
2. View all existing tags
3. Click **+ Add Tag** to create a new tag
4. Click the edit icon to rename a tag
5. Click the delete icon to remove a tag

> Deleting a tag removes it from all contacts that have it.

## Apply Tags to Contacts

### From the Conversation View

1. Open a conversation
2. In the **Contact Details** panel on the right
3. Find the **Tags** section
4. Click **+ Add Tag** and select or type a tag name

### From the Contact List

1. Go to **Contacts**
2. Click on a contact
3. Open the **Tags** section
4. Add or remove tags

### Via CSV Import

Include a `tag` column in your CSV. Multiple tags can be separated by a pipe `|`:

```csv
name,phone,tag
John Doe,+919876543210,vip|premium
```

## Using Tags in Segments

Create segments filtered by tags:

1. **Condition:** `Tag → has tag → "VIP"`
2. Result: All contacts tagged as VIP

## Common Tag Examples

| Tag | Use Case |
|-----|----------|
| `lead` | New potential customer |
| `customer` | Existing paying customer |
| `vip` | High-value customer |
| `churned` | Customer who stopped buying |
| `support` | Has open support request |
| `do-not-disturb` | Do not send broadcasts |


========================================================================
## Broadcasts
URL: https://docs.splashifypro.com/broadcasts
========================================================================

# Broadcasts

**Broadcasts** let you send a single message to thousands of contacts at once — using WhatsApp templates or RCS messages.

## Navigate to Broadcasts

Click **Broadcasts** in the left sidebar, or go to:

```
https://app.splashifypro.com/broadcasts
```

## Broadcast Types

| Type | Channel | Best For |
|------|---------|---------|
| **WhatsApp Broadcast** | WhatsApp Business API | Transactional alerts, promotions, updates |
| **RCS Broadcast** | RCS (Rich Communication Services) | Rich media campaigns with buttons |

## Broadcast Statuses

| Status | Meaning |
|--------|---------|
| **Draft** | Created but not yet sent |
| **Scheduled** | Set to send at a future time |
| **Processing** | Currently being sent |
| **Completed** | All messages dispatched |
| **Failed** | Sending encountered errors |
| **Cancelled** | Manually stopped before completion |

## Broadcasts List

The Broadcasts page shows all your campaigns with:
- Campaign name and channel
- Status badge
- Recipient count
- Sent / Failed / Pending counts
- Created date
- Actions: View Report, Cancel (if in progress)

## Before You Broadcast

Make sure you have:
1. ✅ An approved **message template** (for WhatsApp)
2. ✅ Sufficient **wallet balance**
3. ✅ A **segment** or contact list to target


========================================================================
## Broadcast Reports
URL: https://docs.splashifypro.com/broadcasts/broadcast-reports
========================================================================

# Broadcast Reports

After a broadcast is sent, view detailed delivery analytics in the **Broadcast Report**.

## Access a Report

1. Go to **Broadcasts**
2. Find your completed broadcast
3. Click **View Report** or click the broadcast name

## Report Overview

The top of the report shows summary cards:

| Metric | Description |
|--------|-------------|
| **Total Recipients** | Number of contacts targeted |
| **Sent** | Messages dispatched from your WABA |
| **Delivered** | Messages confirmed delivered to device |
| **Read** | Messages opened by recipients |
| **Failed** | Messages that could not be delivered |
| **Pending** | Messages still in queue |

## Delivery Rate Calculation

```
Delivery Rate = (Delivered / Sent) × 100
Read Rate = (Read / Delivered) × 100
```

## Per-Contact Delivery Table

Scroll down to see each recipient's delivery status:

| Column | Description |
|--------|-------------|
| Contact Name | Recipient name |
| Phone | Phone number |
| Status | Sent / Delivered / Read / Failed |
| Timestamp | When the status was last updated |
| Error | Failure reason (if failed) |

## Common Failure Reasons

| Error | Cause |
|-------|-------|
| `User not on WhatsApp` | Number not registered on WhatsApp |
| `Number opted out` | Contact previously opted out |
| `Messaging limit reached` | WABA daily tier exceeded |
| `Template rejected` | Template was rejected by Meta after approval |
| `Invalid phone number` | Phone number format is incorrect |

## Failed Message Refunds

Failed messages are automatically refunded to your wallet. Refunds typically process within **24 hours**.

## Broadcast Creator

The report shows which team member created and sent the broadcast, so you can track campaign ownership.

## Export

Use the browser's print/save function to export the report. Native CSV export is coming soon.


========================================================================
## Create a Broadcast
URL: https://docs.splashifypro.com/broadcasts/create-broadcast
========================================================================

# Create a Broadcast

## Step 1: Start a New Broadcast

1. Go to **Broadcasts**
2. Click **+ New Broadcast**
3. Choose the channel: **WhatsApp** or **RCS**

---

## WhatsApp Broadcast

### Step 2: Select a Template

Browse your approved WhatsApp templates and select one.

- Filter by template category: **Marketing**, **Utility**, **Authentication**
- Preview the template on the right before selecting
- Only **approved** templates can be used for broadcasts

### Step 3: Choose Your Audience

Select who will receive this broadcast:

| Option | Description |
|--------|-------------|
| **Segment** | Target a saved segment (recommended) |
| **All Contacts** | Send to your entire contact list |
| **Upload CSV** | Import a one-time contact list just for this broadcast |

The recipient count is shown after selecting the audience.

### Step 4: Map Template Variables

If your template has variables (e.g. `{{1}}`, `{{customer_name}}`), map each one to a contact field:

| Variable | Map to |
|----------|--------|
| `{{1}}` | Contact Name |
| `{{2}}` | Custom Attribute: "Order ID" |
| `{{3}}` | Static value: "Mumbai" |

### Step 5: Schedule or Send Now

| Option | Description |
|--------|-------------|
| **Send Now** | Broadcast starts immediately after creation |
| **Schedule** | Pick a future date and time (your account timezone) |

### Step 6: Confirm and Launch

Review the summary:
- Template name
- Audience count
- Estimated cost (deducted from wallet)
- Send time

Click **Launch Broadcast** to confirm.

---

## Billing

Broadcast costs are deducted from your wallet per message:

- **Marketing template:** Higher per-message rate
- **Utility template:** Lower per-message rate
- Failed messages are automatically refunded

Check your balance before sending at **Wallet** in the sidebar.

---

## Cancel a Broadcast

To stop an in-progress broadcast:

1. Go to **Broadcasts**
2. Find the broadcast with status **Processing**
3. Click **Cancel**
4. Confirm

Messages already sent cannot be recalled. Only unsent messages are stopped.


========================================================================
## RCS Broadcasts
URL: https://docs.splashifypro.com/broadcasts/rcs-broadcast
========================================================================

# RCS Broadcasts

**RCS (Rich Communication Services)** is the next-generation SMS. RCS Broadcasts allow you to send rich, interactive messages — with images, carousels, and buttons — to contacts' native SMS apps on supported Android devices.

## RCS vs WhatsApp

| Feature | RCS | WhatsApp |
|---------|-----|---------|
| No app install needed | ✅ | ❌ |
| Delivered to SMS inbox | ✅ | ❌ |
| Supports Android only | ✅ | Both iOS & Android |
| Rich media (images, buttons) | ✅ | ✅ |
| Template approval required | ✅ | ✅ |

## Creating an RCS Broadcast

1. Go to **Broadcasts**
2. Click **+ New Broadcast**
3. Select **RCS** as the channel

### RCS Campaign Steps

**Step 1: Campaign Name**
Give your campaign a descriptive name for internal tracking.

**Step 2: Select RCS Template**
Choose from your approved RCS templates. Templates must be submitted and approved before use.

**Step 3: Choose Audience**
Same as WhatsApp — select a segment, all contacts, or upload a CSV.

**Step 4: Map Variables**
If your RCS template has variables, map them to contact fields.

**Step 5: Schedule or Send**
Choose to send immediately or schedule for a later time.

## RCS Templates

Create RCS templates at **Templates → RCS Templates**.

RCS templates support:
- Plain text messages
- Image messages
- Card messages (image + title + description + buttons)
- Carousel messages (multiple cards)

See [Templates](/templates) for how to create and submit RCS templates.

## Billing

RCS messages are charged per message sent based on your RCS plan. Rates are separate from WhatsApp pricing. Check your current RCS balance in **Wallet**.

## Delivery

- RCS delivers only to Android devices with RCS support enabled
- If RCS is not supported, the message may fallback to SMS (depending on carrier and your plan)
- Delivery reports are available in the broadcast report

## View RCS Broadcast Report

After the broadcast, click **View Report** on the broadcast row to see:
- Total sent
- Delivered count
- Failed count
- Per-contact delivery status


========================================================================
## WhatsApp Broadcasts
URL: https://docs.splashifypro.com/broadcasts/whatsapp-broadcast
========================================================================

# WhatsApp Broadcasts

WhatsApp Broadcasts use **Meta-approved message templates** to send messages to large audiences outside the 24-hour customer service window.

## How WhatsApp Broadcasts Work

1. You select an approved template
2. Splashify Pro sends each message individually from your WABA
3. Recipients receive messages in their WhatsApp as if sent from your number
4. Replies open a regular conversation in your inbox

> WhatsApp limits the number of messages you can send per day based on your messaging tier. Higher tiers are unlocked by completing KYC and maintaining good message quality.

## Messaging Tiers

| Tier | Conversations/Day |
|------|------------------|
| **Tier 1** | 1,000 |
| **Tier 2** | 10,000 |
| **Tier 3** | 100,000 |
| **Tier 4** | Unlimited |

Tier upgrades happen automatically when Meta's quality rating criteria are met.

## Template Categories

| Category | Use Case | Approval Time |
|----------|----------|--------------|
| **Marketing** | Promotions, offers, announcements | 24–48 hours |
| **Utility** | Order updates, OTP, transactional | Usually faster |
| **Authentication** | OTP for login/verification | Fastest |

## Message Quality Rating

Meta monitors message quality based on:
- **Read rate** — How many recipients open your messages
- **Block rate** — How many recipients block you after receiving messages
- **Opt-out rate** — How many recipients report or opt out

Poor quality can lower your tier or restrict your account. Always send relevant, expected messages.

## Rate Limits

Splashify Pro handles WABA rate limiting automatically:
- Messages are queued and sent at the optimal rate
- Large broadcasts are processed in batches
- No manual rate limiting required

## Template Variable Tips

| Tip | Details |
|-----|---------|
| Personalize with `{{name}}` | Higher open rates |
| Keep CTAs clear | One call-to-action works better than multiple |
| Test before sending | Use the preview feature on the template page |


========================================================================
## AI Agents & Chatbots
URL: https://docs.splashifypro.com/ai-agents
========================================================================

# AI Agents & Chatbots

Splashify Pro offers two types of automation agents:

## Agent Types

| Type | Description | Best For |
|------|-------------|---------|
| **Chat AI Agent** | GPT-powered agent that reads your instructions and responds intelligently | FAQ bots, support automation, lead qualification |
| **Workflow Bot** | Visual no-code flow builder with trigger-based conversation paths | Structured conversations, data collection, onboarding |

## Navigate to AI Agents

Click **AI Agents** in the left sidebar, or go to:

```
https://app.splashifypro.com/ai-agents
```

## How Automation Works

When a customer sends a message:

```
Incoming WhatsApp message
        ↓
  Is a human agent assigned?
        ↓ No
  Is there a default Workflow Bot?
        ↓ Yes → Run the bot flow
        ↓ No
  Is there a Chat AI Agent?
        ↓ Yes → AI generates reply
        ↓ No
  Message sits unhandled in inbox
```

When a **human agent** is assigned to a conversation, all automated replies pause — the human takes control.

## Setting a Default Agent

1. Go to **AI Agents**
2. Find your Workflow Bot
3. Click the **star icon ⭐** (Set as Default)

Only Workflow Bots can be set as default (Chat AI Agents handle specific conversations, not all inbound messages by default).

## AI Credits

AI Agent responses consume **AI credits**. Each reply uses a certain number of credits based on the length of the conversation.

- View your AI credit balance at **AI Credits** in the sidebar
- Recharge AI credits at **Settings → AI Credits**
- When credits run out, the AI agent stops responding and the conversation becomes available for human handling


========================================================================
## Chat AI Agent
URL: https://docs.splashifypro.com/ai-agents/chat-ai-agent
========================================================================

# Chat AI Agent

A **Chat AI Agent** uses GPT (large language model) to read your instructions and automatically respond to customer messages in a natural, human-like way.

## Create a Chat AI Agent

1. Go to **AI Agents**
2. Click **+ New Agent**
3. Select **Chat AI Agent**
4. Fill in the agent details:

### Agent Configuration

| Field | Description |
|-------|-------------|
| **Name** | Internal name (e.g. "Customer Support Bot") |
| **Instructions** | The system prompt — tell the AI who it is and how to behave |
| **Knowledge Base** | Add documents or text the AI should know about |
| **Tone** | Professional, Friendly, Formal |
| **Language** | Default language for responses |

### Writing Good Instructions

Your instructions define how the AI behaves. Example:

```
You are a customer support agent for Acme Store.
You help customers with:
- Order status inquiries
- Return and refund policies
- Product recommendations

Always be polite and professional. If you cannot answer
a question, say "Let me connect you with our team."
Do NOT make up information not in the knowledge base.
```

## Knowledge Base

Add documents for the AI to reference:

1. Open your Chat AI Agent
2. Click **Knowledge Base**
3. Add content via:
   - **Plain text** — Paste FAQs, policies, product descriptions
   - **URL** — The AI fetches and indexes the page
   - **File upload** — PDF, DOCX support

The AI uses the knowledge base to answer questions accurately without hallucinating.

## Testing Your Agent

1. Open the agent
2. Use the **Test Chat** panel to simulate a conversation
3. Review the AI's responses
4. Adjust instructions if needed

## Assigning to a Conversation

You can manually assign a Chat AI Agent to a specific conversation:

1. Open the conversation in **Messages**
2. Click **Assign AI Agent** in the conversation header
3. Select your agent

## Deactivating / Archiving

1. Open the agent
2. Toggle **Status** to **Inactive**

Inactive agents do not process messages but their configuration is preserved.

## AI Credits Usage

Each AI-generated response consumes credits based on:
- Input tokens (conversation history + instructions)
- Output tokens (the response generated)

Monitor usage at **Settings → AI Credits**.


========================================================================
## Flow Builder
URL: https://docs.splashifypro.com/ai-agents/flow-builder
========================================================================

# Flow Builder

The **Flow Builder** is a visual drag-and-drop canvas where you connect nodes to build your chatbot conversation flow.

## Open the Flow Builder

1. Go to **AI Agents**
2. Click on a **Workflow Bot**
3. The flow builder opens automatically

## Canvas Controls

| Action | How |
|--------|-----|
| **Pan** | Click and drag on empty canvas |
| **Zoom** | Scroll wheel, or use +/− buttons |
| **Select node** | Click on a node |
| **Move node** | Click and drag a node |
| **Connect nodes** | Drag from an output handle to an input handle |
| **Delete connection** | Click the edge and press Delete |
| **Delete node** | Select node → press Delete or use the node menu |

## Node Palette

The left sidebar shows available node types. Click a node type to add it to the canvas.

### Node Categories

**Send Messages**
- Send Text
- Send Image
- Send Video
- Send Document
- Send Audio
- Send Button Message (interactive)
- Send List Message (interactive)
- Send Template Message

**Ask / Collect Input**
- Ask Question (text)
- Ask Number
- Ask Phone
- Ask Email
- Ask Date
- Ask URL
- Ask Media / File
- Ask Location
- Ask Choice (multiple choice buttons)

**Logic & Flow Control**
- Condition (if/else branching)
- Delay (wait before next step)
- AI Agent (hand off to another bot)

**Actions**
- HTTP Request (call an external API)
- Update Contact Column (set a custom attribute)
- Update Contact Tag (add/remove tag)
- AI Generate (generate dynamic text using AI)
- Assign Agent (assign conversation to team member)
- Resolve Conversation

## Building a Flow

### Step 1: Start with a Trigger

Every flow must start with an **On Message** trigger node. It's added automatically when you create a new bot.

### Step 2: Add Nodes

1. Click a node in the **Node Palette** (left sidebar)
2. It appears on the canvas
3. Drag it to position it

### Step 3: Connect Nodes

- Drag from the **output handle** (circle on the right/bottom of a node) to the **input handle** of the next node
- Conditional nodes have two outputs: **True** (yes path) and **False** (no path)

### Step 4: Configure Each Node

Click on a node to open its configuration panel on the right:
- Set the message text, media, or logic
- Map variable placeholders to contact attributes
- Configure conditions and operators

### Step 5: Test the Flow

Use the **Test** button to simulate the flow in a preview mode.

### Step 6: Save and Publish

- Click **Save** to save your progress as a draft
- Click **Publish** to make the bot live

## Variables

Variables let you store and reuse dynamic values throughout a flow.

### Storing User Input

When using Ask nodes, the user's answer is saved to a **variable**:

```
Ask Question: "What is your name?"
Save to variable: "customer_name"
```

Later nodes can reference `{{customer_name}}` in message text.

### Mapping to Contact Attributes

Use the **Update Contact Column** node to persist variables to the contact's profile in the database.

## Maya AI Flow Generator

Instead of building a flow from scratch, describe what you want in plain language and let **Maya AI** generate a complete, ready-to-run flow automatically.

### How it works

1. Open a Workflow Bot in the Flow Builder
2. Click the **Maya** button (top-right of the canvas toolbar)
3. Type a description of the flow you want — e.g. *"Ask for name, email, and service interest, then send a confirmation message"*
4. Select the **Mode**:
   - **Replace** — clears the current canvas and builds the new flow from scratch
   - **Append** — adds the generated nodes to the existing canvas
5. Click **Generate** — Maya will build the flow in seconds
6. Review the generated nodes; use the **Refine** input if you want to adjust specific parts
7. Click **Apply to Canvas** to insert the flow

### Cost

Each generation deducts **₹5** from your **Wallet**. The deduction happens only after the AI returns a valid flow — a failed call costs nothing.

### Supported node types (23)

Maya can generate flows using any of these node types:

| Category | Nodes |
|----------|-------|
| **Trigger** | On Message |
| **Send** | Send Text, Send Button, Send List, Send Media, Send Template |
| **Ask** | Ask Text, Ask Number, Ask Email, Ask Phone, Ask Choice |
| **Logic** | Condition, Delay, Jump to Flow |
| **AI** | AI Generate |
| **Actions** | HTTP Request, Set Variable, Update Tag, Update Column, Assign Conversation, Unassign Conversation, Resolve Conversation, Stop Chatbot |

### Tips for better results

- Be specific: *"Ask for the customer's name, then ask for their city, then send a text saying 'Thanks \{\{name\}\}, we'll contact you in \{\{city\}\} shortly'"*
- Mention branching: *"If the customer selects Premium, send the premium offer; otherwise send the standard offer"*
- Describe the goal: *"Lead capture flow for a real-estate business — collect name, budget, and preferred location"*
- Use **Refine** to tweak individual parts without regenerating the whole flow

## CTWA Ads Integration

When triggered from a Click-to-WhatsApp (CTWA) ad, the flow receives the ad's **Source ID**. Use the **On Message** trigger with "For Specific Ads" to build dedicated landing-style flows per ad campaign.


========================================================================
## Flow Node Reference
URL: https://docs.splashifypro.com/ai-agents/flow-nodes
========================================================================

# Flow Node Reference

## Trigger Nodes

### On Message Node

The entry point of every flow. Defines what messages activate the bot.

| Setting | Options |
|---------|---------|
| **Trigger Type** | Any Message / Specific Keywords / Any CTWA Ad / Specific CTWA Ads |
| **Keywords** | Comma-separated keywords (case-insensitive match) |
| **Source IDs** | CTWA ad source IDs for ad-specific triggers |
| **Behavior** | Normal / Only once per new contact / Only if resolved |

---

## Send Message Nodes

### Send Text

Sends a plain text WhatsApp message.

- Supports `{{variable_name}}` placeholders
- Supports emoji

### Send Image / Video / Document / Audio

Sends a media file.

- **URL:** Direct link to the media file
- **Caption:** Optional text below the media

### Send Button Message

Sends an interactive message with up to **3 quick reply buttons**.

| Field | Description |
|-------|-------------|
| Body text | The main message |
| Footer | Optional sub-text below body |
| Buttons | Up to 3 button labels |

Each button connects to a separate output handle for branching.

### Send List Message

Sends an interactive list picker with sections and rows.

| Field | Description |
|-------|-------------|
| Header | Optional header text |
| Body | Main message |
| Button Label | Text of the "View Options" button |
| Sections | Up to 10 sections, each with up to 10 rows |

### Send Template Message

Sends an approved WhatsApp message template.

| Field | Description |
|-------|-------------|
| Template | Select from approved templates |
| Variables | Map template variables to contact attributes |

---

## Ask / Input Nodes

All Ask nodes send a question and **wait for the user's reply** before proceeding.

| Node | Validates |
|------|-----------|
| **Ask Question** | Any text |
| **Ask Number** | Numeric input |
| **Ask Phone** | Valid phone format |
| **Ask Email** | Valid email format |
| **Ask Date** | Date format |
| **Ask URL** | Valid URL |
| **Ask Media** | Image / Video |
| **Ask File** | Document / File |
| **Ask Location** | GPS location share |
| **Ask Choice** | Buttons (up to 3 choices) |

### Ask Node Settings

| Setting | Description |
|---------|-------------|
| **Question text** | The message sent to the user |
| **Save to variable** | Variable name to store the answer |
| **Invalid response message** | Sent if the user's input fails validation |

---

## Logic Nodes

### Condition Node

Branches the flow based on a condition.

| Field | Description |
|-------|-------------|
| **Variable** | The variable or contact attribute to check |
| **Operator** | equals / not_equals / contains / starts_with / ends_with |
| **Value** | The value to compare against |

**Outputs:**
- **True** handle → path taken when condition is met
- **False** handle → path taken when condition is not met

### Delay Node

Pauses the flow for a specified duration before executing the next node.

| Field | Options |
|-------|---------|
| **Duration** | Any number |
| **Unit** | Seconds / Minutes / Hours |

---

## Action Nodes

### HTTP Request Node

Calls an external API and optionally stores the response in a variable.

| Field | Description |
|-------|-------------|
| **Method** | GET / POST / PUT / DELETE |
| **URL** | The API endpoint |
| **Headers** | Key-value pairs |
| **Body** | JSON body (for POST/PUT) |
| **Save response to** | Variable name |

### Update Contact Column

Sets a custom attribute on the contact.

| Field | Description |
|-------|-------------|
| **Column** | The custom attribute to update |
| **Value** | Static value or `{{variable}}` |

### Update Contact Tag

Adds or removes a tag from the contact.

| Field | Options |
|-------|---------|
| **Action** | Add tag / Remove tag |
| **Tag** | Select from existing tags |

### AI Agent Node

Hands off the flow to another **Workflow Bot** (sub-flow).

| Field | Description |
|-------|-------------|
| **Select Bot** | Choose a published Workflow Bot |

### AI Generate Node

Generates dynamic text using AI based on a prompt.

| Field | Description |
|-------|-------------|
| **Prompt** | Instruction for the AI (can include `{{variables}}`) |
| **Save to variable** | Where to store the generated text |

### Assign Agent Node

Assigns the conversation to a specific team member.

| Field | Description |
|-------|-------------|
| **Agent** | Select a team member |

### Resolve Conversation Node

Marks the conversation as resolved. Useful at the end of a flow.


========================================================================
## Untitled
URL: https://docs.splashifypro.com/ai-agents/instagram-bots
========================================================================

# Instagram Chatbots

Workflow Bots can run on Instagram in addition to WhatsApp. Pick the channel when you create the bot — channel is permanent post-create. The same flow editor, the same node palette (minus a few WA-only nodes), and the marquee feature: a **Send WhatsApp Template** node that hands a qualified lead from Instagram to WhatsApp for richer engagement.

> **Plan + connection requirements:** Instagram bots need a plan with **Instagram Automation** enabled, AND a connected Instagram Business account at [/instagram-automation](/instagram-automation). Trial users get full access.

## Channel scoping

Each bot is either **WhatsApp** or **Instagram**, picked at create-time and immutable. The flow editor renders the matching node palette per channel — IG bots don't see WA-only nodes (and vice versa).

| Concern | WhatsApp | Instagram |
|---|---|---|
| Trigger types | Keyword, any-message, CTWA Ads | DM keyword, DM any, story reply, comment-on-post |
| Send-type nodes | Text, media, button, list, CTA, template, carousel | Text, media, button (quick-replies), **Send WhatsApp Template** (handoff) |
| Ask-type nodes | Text, number, email, phone, date, URL, media, file, location | Text, number, email, phone, date, URL, media (no file, no location) |
| 24h/7d window | Not enforced | Auto-attaches `HUMAN_AGENT` tag 24h–7d, refuses send beyond 7d |
| Default-bot star | Independent — one default per channel | Independent — one default per channel |

## IG trigger types

Pick one per bot in the **On Message** node:

- **Any DM** — fires on any plain inbound DM. Story replies and comment-triggered DMs are excluded so they can be handled by their dedicated triggers.
- **DM Keyword** — case-insensitive substring match against keywords you list. Optional fuzzy / case-match toggles match the WA keyword UI.
- **Story Reply** — fires when a customer replies to one of your stories. Optional story-id filter restricts to specific stories; empty = any story.
- **Comment on Post** — fires when a customer comments on a post you pick from the IG media grid. Optional keyword filter restricts to comments containing certain words.

All four support the standard behavior gates (every message / only-once-per-contact / only-if-resolved).

### Constraint on comment triggers

When the trigger is **Comment on Post**, the first node connected after the trigger MUST be a Send-type (Send Text / Send Media / Send Button). The bot replies via Meta's comment-scoped private-reply API which only accepts the immediate content of the reply — there's no way to "run the bot to completion before sending." If the first node is a Condition or Delay, the customer never receives a DM and the session never starts. Save fails with a clear error if you try.

### Comment trigger overlap with comment-to-DM rules

If a [comment-to-DM rule](/instagram/automation-rules) on the same post + keyword matches first, the rule fires and the bot is skipped. So:

- For one-shot DM replies → use a comment-to-DM rule
- For multi-step qualification flows → use a bot with a comment trigger
- Don't put both on the same post + keyword — only the rule will run

## Send WhatsApp Template (cross-channel handoff)

The marquee feature. Drop this node anywhere in your IG flow to hand off to WhatsApp:

1. **Phone source variable** — pick the variable that holds the captured phone (typically the saveAs of an Ask Phone node earlier in the flow).
2. **WhatsApp template** — pick an APPROVED template from your WA template library.
3. **Variable mapping** — map body / header / button params, same UI as the WA Send Template node.
4. **After handoff** — choose what happens next:
   - **End IG flow** (default): one-shot template send, IG flow stops.
   - **Continue on WhatsApp via bot…**: chained WA bot resumes when the customer replies on WA. IG-captured variables transfer verbatim into the WA session.
5. **Compliance acknowledgement** — required to save. Confirms the recipient has opted into WhatsApp messages. Marketing templates without explicit opt-in violate Meta policy.

When the node fires, we:

- Find or create a WA contact tagged `instagram-handoff` with `metadata.source_ig_conversation_id` cross-linking back to the originating IG conversation.
- Find or create the WA conversation row (channel='whatsapp').
- Send the template via your standard WA messaging path. Wallet deduction + reseller markup apply normally.
- (If continue-on-WA) insert a paused chatbot session keyed on the WA conversation + chosen bot. The customer's first WA reply resumes the bot.
- Record a `cross_channel_handoff` row in the activity log with both conversation ids.

If the phone variable is empty / invalid, or the user has no WABA connected, the node logs an audit row and advances the flow without sending — surrounding nodes (CRM tag updates, audit webhooks, etc.) still run.

## 24h / 7d messaging window

Meta restricts who you can DM and when:

- **0–24h** since the customer's last inbound: send freely.
- **24h–7d**: the IG send layer auto-attaches the `HUMAN_AGENT` message tag. The bot still works but Meta's policy requires this for non-promotional follow-ups.
- **Beyond 7d**: Meta refuses the send. The flow logs the skip and advances to the next node — Condition / HTTP / UpdateColumn / UpdateTag / SendWhatsAppTemplate still run for an expired-window contact.

The Send WhatsApp Template handoff is the one path that bypasses the window, since WA templates have their own opt-in policy.

## Setting a default IG bot

Independent from the default WA bot. Star button on each bot row in [/ai-agents](/ai-agents) — IG bots get a pink star, WA bots emerald. Stars per channel are independent: starring an IG bot doesn't unstar your WA default.

Inbound IG DMs that don't match a more specific bot (keyword / story / comment) fall through to the default IG bot if one is set, OR to the welcome / off-hours auto-reply if those are configured under [Settings → Live Chat](/settings/live-chat).

## What lives where

- **Bot creation + channel pick** — [/ai-agents](/ai-agents) → Create Agent → Workflow Bot → pick WhatsApp or Instagram.
- **Flow builder** — [/chatbot/[id]](/chatbot) — same canvas as WA bots, IG-pink accent + filtered palette.
- **Comment-to-DM rules (one-shot)** — [/instagram-automation](/instagram-automation) — keep for simple "comment X → DM Y" use cases.
- **Default-bot star + channel pill** — agent list at [/ai-agents](/ai-agents).
- **Live testing** — [/messages](/messages) Instagram tab; bots fire on real inbound.


========================================================================
## AI Credits & Pricing
URL: https://docs.splashifypro.com/ai-agents/pricing
========================================================================

# AI Credits & Pricing

Every AI agent reply — text or voice — deducts from your **AI Credits**
wallet (separate from your WhatsApp messaging wallet). Top-up at
**Settings → AI Credits**. All prices below are in **INR**, deducted
in real time after each reply.

## Chat (text in, text out)

Chat AI agents and the **AI Generate Text** node are billed per
token of input + output:

| Direction | Rate per 1M tokens | Rate per token |
| --------- | ------------------ | -------------- |
| Input (your prompt + history + KB context) | **₹15** | ₹0.000015 |
| Output (the agent's reply) | **₹60** | ₹0.000060 |

A typical WhatsApp reply uses around **400 input + 80 output tokens**:

```
input  = 400 × 0.000015 = ₹0.0060
output =  80 × 0.000060 = ₹0.0048
total                   = ₹0.0108  per message
```

That's about **₹1.08 per 100 chat replies** for a typical agent. A
support agent serving 10,000 messages a month costs around
**₹100-150** in chat credits.

### What counts as a token

Tokens are how the model measures text — roughly 4 characters or
¾ of an English word. We count exactly the prompt + completion
tokens reported by the model and deduct that, no rounding up.

The system prompt (your agent's role, goal, instructions, tone +
the entire knowledge base text) is part of the **input** count, so
larger knowledge bases mean slightly higher per-message costs.
Trim KB files to relevant content for the cheapest rate.

## Voice (incoming voice notes & spoken replies)

When a customer sends a **WhatsApp voice note** to a chat AI agent,
two extra services run on top of the chat charge:

1. **Speech-to-Text** — the voice note is transcribed before being
   sent to the model
2. **Text-to-Speech** — the agent's reply is converted back to
   audio and sent as a voice note (only when the inbound was audio)

| Service | Rate |
| ------- | ---- |
| **Speech-to-Text** | **₹0.0104 / second** of audio |
| **Text-to-Speech** | **₹0.00375 / character** of reply |

A typical voice exchange:

```
Customer voice note (10s)     STT  10  × 0.0104     = ₹0.104
Chat reply (400+80 tokens)    chat                  = ₹0.011
Agent voice note (200 chars)  TTS 200  × 0.00375    = ₹0.75
                                                      ──────
Total per voice exchange                            ≈ ₹0.87
```

A chat-only exchange costs **~₹0.01**; a voice exchange costs
**~₹0.87** because the audio pipeline is the dominant cost.

### When voice charges apply

| Inbound | Outbound | Charges |
| ------- | -------- | ------- |
| Text | Text | Chat only |
| **Voice note** | Text | Chat + Speech-to-Text |
| **Voice note** | **Voice note** | Chat + Speech-to-Text + Text-to-Speech |

The agent automatically replies with audio when the inbound was
audio. To force text-only replies, edit the agent's instructions
(e.g. "Always reply with text, never audio").

## Voice AI Agent (real-time phone calls)

Distinct from the chat AI agent — **Voice AI Agents** handle live
WhatsApp Business calls. Pricing is per-second of call time, not
per-token. See [Voice AI Pricing](/voice-ai/pricing) for details.

## Where to see your usage

- **Settings → AI Credits** — current balance + recent deductions
- **Track Expenses → AI Credit Usage** — full history with per-call
  breakdown of token counts, audio seconds, and characters

Each row records the call type (chat, speech-to-text, text-to-speech)
so you can see exactly what your AI agents are doing.

## Insufficient credits

When your balance falls below the cost of the next call, the agent
**stops replying** and the conversation auto-unassigns so a human
team member can take over. Top up at **Settings → AI Credits** —
deductions resume immediately on the next inbound.

The default minimum balance to keep the agent active is **₹0.001**
(covers about 10 short text exchanges). Drop the balance below
that and the conversation gets handed to your unassigned queue
without any failed-message charges.

## Maya AI — Flow Generation

**Maya AI** generates complete chatbot flows from a plain-language prompt.
This is billed from your **Wallet** (not AI Credits), as a flat per-generation fee.

| Action | Cost |
|--------|------|
| Generate a flow | **₹5 per generation** |

The ₹5 is deducted only after the AI returns a valid flow. A failed or timed-out call costs nothing.
If your wallet balance is below ₹5, generation is blocked until you top up.

## Maya AI — Template Generation

**Maya AI** on the template create page generates a full WhatsApp template (header, body, and buttons) in one click.

| Action | Cost |
|--------|------|
| Generate a template | **₹2 per generation** |

Same rules apply: deducted from **Wallet** only on success, free on failure, blocked if balance < ₹2.

## Need higher volume?

For accounts processing 100K+ AI replies per month, custom rates
are available. Email **support@splashifypro.in** with your expected
monthly volume.


========================================================================
## Workflow Bot
URL: https://docs.splashifypro.com/ai-agents/workflow-bot
========================================================================

# Workflow Bot

A **Workflow Bot** uses a visual flow builder to define structured conversation paths. Unlike the Chat AI Agent (which responds freely), a Workflow Bot follows a defined script — collecting data, sending messages, and taking actions at each step.

## Create a Workflow Bot

1. Go to **AI Agents**
2. Click **+ New Agent**
3. Select **Workflow Bot**
4. Enter a name
5. Click **Create** — you'll be taken to the **Flow Builder**

## How Workflow Bots Work

A bot flow is a connected graph of **nodes**. When a trigger fires, the bot executes nodes one by one:

```
Trigger (On Message / On CTWA Ad)
        ↓
  Send a message
        ↓
  Ask a question → Save answer to contact
        ↓
  Condition: Was answer "Yes"?
    ↓ Yes            ↓ No
  Send callback    Send goodbye
  request message  message
```

## Triggers

Every bot flow starts with an **On Message** trigger node that defines when the bot activates:

| Trigger | Description |
|---------|-------------|
| **For Any Message** | Bot activates on every incoming message |
| **For Specific Keywords** | Activates when message matches keywords (e.g. "Hi", "Start", "Menu") |
| **For Any CTWA Ads** | Activates when message comes from any Click-to-WhatsApp ad |
| **For Specific Ads** | Activates only for specific CTWA source IDs |

### Trigger Behavior Options

| Option | Description |
|--------|-------------|
| **Only once per new contact** | Bot runs only the first time a new contact messages |
| **Only if chat is resolved** | Bot only activates for resolved conversations |

## Set as Default Bot

To have the bot handle all inbound messages automatically:

1. On the **AI Agents** list page
2. Click the **⭐ star icon** next to your Workflow Bot
3. It becomes the default — all unassigned conversations are handled by this bot

## Publish the Bot

After building and testing your flow:

1. Click **Publish** in the flow builder
2. Status changes from **Draft** to **Published**
3. The bot is now live and active

> Unpublished (Draft) bots do not process messages even if set as default.

## Session Management

The bot tracks each contact's progress through the flow using **sessions**:

- Sessions are stored per contact per flow
- If a contact stops mid-flow and messages again, the bot **continues from where they left off**
- Sessions expire after **24 hours** of inactivity — the next message restarts the flow

## Nested Bots

You can call one Workflow Bot from another using the **AI Agent Node**. This allows modular, reusable sub-flows.


========================================================================
## Instagram
URL: https://docs.splashifypro.com/instagram
========================================================================

# Instagram

Splashify Pro connects your **Instagram Business account** so you can:

- **Auto-DM** users who comment on your reels with a trigger keyword
- **Reply publicly** to those comments at the same time
- **Chat with DMs** in the same unified inbox you use for WhatsApp + RCS

Everything runs through the official **Instagram Graph API with Instagram Login** — no Instagram password is ever shared with Splashify Pro, and you can revoke access at any time from your Instagram settings.

## Three parts of the feature

| Part | What it does | Where to find it |
|------|--------------|------------------|
| **Connect** | One-time Instagram Login flow that authorises Splashify Pro | [/instagram-automation](https://app.splashifypro.com/instagram-automation) |
| **Automation Rules** | Per-reel keyword triggers → auto-DM + public reply | Same page, Rules tab |
| **Instagram Inbox** | Live DM conversations alongside WhatsApp + RCS | [/messages](https://app.splashifypro.com/messages) — **Instagram** tab |

## Prerequisites

To connect, your Instagram account must be either:

- **Business** account, or
- **Creator** account

Personal accounts are not eligible — Instagram's Graph API blocks them. To convert, open the Instagram mobile app → **Settings → Account → Switch to Professional Account**.

## Plan requirements

Instagram is included on **GROWTH**, **ADVANCED**, and **ENTERPRISE** plans. On a trial account you have full access during the trial period — the feature locks after the trial ends unless your current plan has it enabled.

## How the comment-DM flow works

```
Someone comments on your reel
        ↓
Comment contains one of your trigger keywords?
        ↓ No → nothing happens (comment stays logged under Activity)
        ↓ Yes
Auto-send private DM to that commenter
Optionally post a public reply under their comment
Log everything to the Activity feed
```

Triggers fire in **seconds** — Meta pushes webhook events the moment the comment lands, and Splashify Pro processes them inline.

Continue with [**Connect Instagram**](/instagram/connect) to start setup.


========================================================================
## Automation Rules
URL: https://docs.splashifypro.com/instagram/automation-rules
========================================================================

# Automation Rules

Each rule is scoped to **one reel (or post)** and fires when someone comments on it with a matching keyword. You can have multiple rules on the same reel — e.g. one for `price`, another for `link`.

## Create your first rule

### 1. Open the Rules tab

On [/instagram-automation](https://app.splashifypro.com/instagram-automation), click the **Rules** tab. You'll see all rules with their media thumbnail, keyword, and trigger count.

### 2. Click "New Rule"

A side sheet opens with an empty form.

### 3. Pick a reel or post

You'll see a grid of your recent 25 posts/reels pulled live from Instagram. Click the one you want this rule to apply to. Click **Change** if you need to pick a different one.

### 4. Set the trigger keyword

The keyword is a **case-insensitive substring match** against the comment text.

**Examples:**

| Trigger keyword | Comments that match |
|-----------------|---------------------|
| `price` | "What's the price?", "PRICE??", "priced too high" |
| `link` | "Send link", "Linked in bio?" |
| `how much` | "how much is it", "How Much?", "howmuch" ❌ (no space) |

Pick something short and specific. Common pitfalls:

- **Too generic** — `hi` will fire on nearly every comment
- **Too specific** — `what is the price in dollars` will never match

### 5. Set the DM message

What gets sent as a private reply when the rule fires. Keep it under 1000 characters — Instagram truncates longer messages.

You can include links. Instagram renders clickable link previews in DMs.

### 6. (Optional) Set a public comment reply

The text posted as a **public reply under the comment** at the same time as the DM is sent.

Common pattern: `Check your DMs! 📬` — lets the commenter (and onlookers) know the DM was sent.

Leave blank if you only want a private DM with no public footprint.

### 7. Save

The rule goes live immediately. Comments that arrive from this moment onwards will be checked against it.

## How matching works

When Instagram pushes a comment event to Splashify Pro:

```
Comment text → lowercased → "contains" check against each active rule's keyword
```

- Multiple rules on the same reel are checked **in creation order**
- The **first matching active rule** fires; other rules for the same comment are skipped
- Comments with no match are still logged to the Activity feed (so you can see what's coming in)

## Managing rules

| Action | How |
|--------|-----|
| **Pause / activate** | Click the power icon on the rule row |
| **Edit keyword or messages** | Click the pencil icon |
| **Delete** | Click the trash icon — irreversible |
| **See firing count** | Each rule card shows "Triggered N×" |

## Common patterns

### Lead magnet — "send me the link"

```
Trigger: link
DM:      Here you go 🎁 https://your-site.com/guide

         Reply 'yes' if you want me to follow up with pricing!
Reply:   Check your DMs 📬
```

### Price list on demand

```
Trigger: price
DM:      Our starter pack is ₹2,000/mo, pro is ₹5,000/mo,
         and enterprise is custom. Full breakdown:
         https://your-site.com/pricing
Reply:   DM'd you our pricing — check your inbox 💬
```

### Course waitlist signup

```
Trigger: join
DM:      Welcome! To secure your spot, drop your email here
         and I'll send the enrolment link within 24h.
Reply:   (leave blank — keeps it more personal)
```

## Limits and quirks

- **One DM per matching comment** — we don't fire the same rule multiple times for the same comment ID
- **Deleted comments** — if the commenter deletes their comment after we send the DM, the DM stays; Instagram doesn't retract it
- **Carousel posts** — rules work on the carousel as a whole, not per slide

Continue to [**Instagram Inbox**](/instagram/inbox) to handle the DMs that land after automations fire.


========================================================================
## Connect Instagram
URL: https://docs.splashifypro.com/instagram/connect
========================================================================

# Connect Instagram

The connect flow takes about **30 seconds**. You do it once per Instagram account.

## Before you start

Check your Instagram account type in the mobile app → **Settings → Account**:

- ✅ **Business account** — works
- ✅ **Creator account** — works
- ❌ **Personal account** — Instagram Graph API does not allow apps to manage comments/DMs on personal accounts. Convert to Professional (Business or Creator) first. It's free and reversible.

## Step-by-step

### 1. Open the Instagram page

In the Splashify Pro sidebar, click **Instagram**. You'll land at [app.splashifypro.com/instagram-automation](https://app.splashifypro.com/instagram-automation).

If your plan doesn't include Instagram automation, you'll see an **Upgrade Plan** card here instead. Upgrade first, then return.

### 2. Click "Connect Instagram"

You'll be redirected to `instagram.com/oauth/authorize` — Instagram's own login page.

### 3. Sign in with Instagram

Log in with your Instagram Business/Creator credentials. If you're already logged into Instagram in this browser, it'll skip the password step.

### 4. Review and approve permissions

Instagram will ask you to grant Splashify Pro these permissions:

| Permission | Why Splashify Pro needs it |
|------------|---------------------------|
| `instagram_business_basic` | Read your profile and reels so you can pick which posts get automation rules |
| `instagram_business_manage_comments` | Receive comment events via webhook + post public replies |
| `instagram_business_manage_messages` | Send the private DM when a trigger keyword matches |

Tap **Allow**. Instagram redirects you back to Splashify Pro.

### 5. We finish the setup in the background

Behind the scenes, Splashify Pro:

- Swaps the authorization code for a **long-lived access token** (~60-day validity)
- Reads your profile for the username + profile picture
- **Subscribes our app** to Instagram webhook events for `comments` and `messages`

You'll see your account appear with a **Webhooks active** badge.

## After connecting

You're ready to [**create your first automation rule**](/instagram/automation-rules).

## Disconnecting

Click **Disconnect** on the connected-account card. Splashify Pro:

1. Unsubscribes from your Instagram webhooks (Meta stops sending events to us)
2. Deletes your stored access token
3. Removes every automation rule and activity log for this account

Your Instagram account itself is unaffected — this just severs our access.

## What gets stored

| Stored in Splashify Pro | Not stored |
|------------------------|------------|
| Your Instagram User ID + username + profile picture URL | Your Instagram password |
| Long-lived access token (AES-encrypted at rest) | Your DMs or comments in bulk — we only read the specific events Meta pushes |
| Automation rules you create (keywords, DM text, etc.) | |

## Token expiry

The long-lived token expires 60 days after issue. Splashify Pro will prompt you to reconnect when it's nearing expiry. Refreshing just takes one click.


========================================================================
## Instagram Inbox
URL: https://docs.splashifypro.com/instagram/inbox
========================================================================

# Instagram Inbox

Once you connect Instagram, every **DM** you receive lands in the same `/messages` page as WhatsApp and RCS — no context switching between apps.

## Finding the Instagram inbox

On [/messages](https://app.splashifypro.com/messages), a tab switcher appears at the top of the conversation list:

- **WhatsApp** (green)
- **RCS** (purple) — only when RCS is active
- **Instagram** (pink) — only when Instagram is connected

Click **Instagram** to see only DM conversations.

## What you can do

| Action | How |
|--------|-----|
| **Read incoming DMs** | They appear automatically as Instagram webhooks arrive |
| **Reply** | Type in the composer at the bottom, hit **Send** |
| **See commenter history** | DMs triggered by automation rules show the commenter's Instagram username |
| **Add a contact** | Normal contact panel works — tag, note, etc. |

## Composer states

The composer at the bottom of the chat thread has three states, based on **when the user last messaged you**. These are enforced by Instagram (not Splashify Pro) and govern what you can send.

### 0–24 hours — unrestricted (green banner)

```
✓ Free-reply window open • 23h 45m left
```

You can send **any** text freely. No tags required.

### 24 hours–7 days — Human Agent tag required (amber banner)

```
⚠ 24-hour window has passed. Your message will be sent with
  the Human Agent tag (valid for 6d 5h more).
```

Instagram requires messages sent in this window to carry a `HUMAN_AGENT` tag, which Splashify Pro adds automatically. Your message still gets through. The tag is designed for human customer support — not promotions.

This requires Meta App Review approval for the **Human Agent** feature on your app (already submitted for Splashify Pro).

### More than 7 days — locked (red banner)

```
🔒 This user hasn't messaged you in over 7 days.
   Instagram blocks new outbound DMs until they message you again.
```

The composer is disabled. Instagram doesn't allow **any** outbound DM to a user who hasn't interacted with your account in the last 7 days — not even with the Human Agent tag. You have to wait for them to message you again.

See [**Messaging Windows**](/instagram/messaging-windows) for the full policy reference.

## Comments vs DMs

A **comment** on one of your reels does **not** reset the 7-day messaging window. Only an actual **DM** from the user counts. But — when your automation rule fires and we send the private DM, Instagram treats the DM-from-comment as within the standard 24h window automatically (since it's tied to the comment).

## Attachments

Instagram currently supports `text`, `image`, `video`, `audio`, and `ig_reel` attachments in DMs. Inbound attachments render inline. Outbound attachments from Splashify Pro's composer are limited to text in the current release — we'll expand to media as Meta stabilises the API surface.

## Automation vs inbox

Both features share the same underlying connection:

- **Automation rules** send the *first* DM to a commenter (keyword trigger)
- **Inbox** is where your ongoing conversation with that commenter lives — either continuing the automation-started thread or a cold DM they sent

Replying in the inbox uses the same outbound pipeline, including the window policy.


========================================================================
## Messaging Windows
URL: https://docs.splashifypro.com/instagram/messaging-windows
========================================================================

# Messaging Windows

Instagram enforces strict rules about **when** you can send a DM to a user. These rules are Instagram's, not Splashify Pro's — we simply reflect them in the composer and enforce them server-side.

## The three windows

| Since user's last DM to you | What you can send | Banner colour |
|----------------------------|-------------------|---------------|
| **0–24 hours** | Any text or media, no tag | Green — "Free-reply window open" |
| **24 hours–7 days** | Text only, must carry `HUMAN_AGENT` tag | Amber — "Human Agent tag" |
| **More than 7 days** | Nothing. Wait for them to message again | Red — "Locked" |

## Why Instagram does this

Instagram's goal is to keep DMs a **conversational inbox**, not a marketing channel. Businesses can respond to user-initiated conversations freely for the first 24h, then progressively lock down to prevent cold outreach and spam.

## How Splashify Pro handles each window

### Inside 24h

Your message is sent with no extra metadata. Full creative freedom — attach media, use emoji, link to wherever you want.

### Between 24h and 7d

Splashify Pro automatically stamps the outbound message with:

```
messaging_type: MESSAGE_TAG
tag: HUMAN_AGENT
```

This tells Instagram the message is a legitimate human-agent follow-up (per Meta's [Human Agent policy](https://developers.facebook.com/docs/instagram-platform/humanagent/)). Valid use cases include:

- Following up on a support issue that takes more than 24h to resolve
- Responding after a weekend / holiday closure
- Sending information a customer specifically asked for

Prohibited in this window: promotions, marketing blasts, offer announcements. If you send something that looks promotional, Instagram may flag your account.

Requires the **Human Agent** feature to be approved on the Meta App. Splashify Pro has it submitted.

### After 7 days

Composer is disabled. Splashify Pro's backend also refuses any DM API call to this user — if your code (or another agent in your org) tries, Meta rejects it.

Your only path back: wait for the user to DM you.

## When the clock resets

A **new inbound DM** from the user resets `last_inbound_at` on their conversation. This flips the composer back to the green "Free-reply" state for the next 24h.

Comments on your reels **do not** reset the window — Instagram treats comments and DMs as separate surfaces.

## Automation rule DMs and the window

When your rule fires a DM in response to a comment, Splashify Pro treats that DM as being inside the 24h window automatically — the comment itself is the user's initial engagement signal. This is why comment-triggered auto-DMs always succeed regardless of whether the user has DM'd you before.

## What to show users in your UI

The composer banner above the input reflects the window state in real time. The countdown ticks down once a minute. You don't need to manage this yourself.

## API-level checks

If you're integrating via Splashify Pro's public API, you can query the current window status for a conversation:

```
GET /api/v1/app/instagram/messages/window?conversation_id=...
```

Response:

```json
{
  "success": true,
  "window": {
    "state": "open",
    "can_reply": true,
    "needs_human_agent": false,
    "seconds_remaining": 82500,
    "last_inbound_at": "2026-04-24T03:15:22Z"
  }
}
```

Use `can_reply` to decide whether to enable your send button. Use `needs_human_agent` to tell the user that their reply will carry the support tag.


========================================================================
## Troubleshooting
URL: https://docs.splashifypro.com/instagram/troubleshooting
========================================================================

# Troubleshooting

## "Your current plan doesn't include Instagram automation"

Your plan's Instagram flag is off. Either:

1. **Upgrade to a plan with Instagram** from [/plans/whatsapp](https://app.splashifypro.com/plans/whatsapp), or
2. If you're on a **free trial**, you should have full access — if the trial has expired, upgrading is required
3. If you recently upgraded and still see this message, **hard-refresh** the page (`Ctrl+Shift+R` / `Cmd+Shift+R`) — the app caches the plan state

## "No Instagram Business account found"

Your Instagram account is Personal. Instagram's API does not permit apps to manage comments or DMs on Personal accounts.

**Fix:** in the Instagram mobile app → **Settings → Account → Switch to Professional Account → Business** (or Creator). Takes about 10 seconds, free, reversible.

Then retry the Connect flow.

## Comment events aren't firing my rule

Check in this order:

**1. Is the rule Active?**

On the Rules tab, the rule row shows either an **Active** or **Paused** pill. Click the power icon to toggle.

**2. Does the keyword actually appear in the comment text?**

Matching is case-insensitive substring. `price` matches "Pricing?" and "PRICE" but NOT "priy" or "cost".

**3. Is the comment on the reel this rule is scoped to?**

Rules are **per-reel**. If you set up a rule on Reel A and the comment is on Reel B, it won't fire. Check the thumbnail on the rule row to confirm.

**4. Are webhooks subscribed?**

On the connected-account card, look for the **Webhooks active** badge. If it says **Webhooks pending**, the subscribe call failed during connect. Click **Disconnect**, then **Connect Instagram** again.

**5. Check the Activity tab.**

Every comment on any tracked reel gets logged — even ones that didn't match. If your comment doesn't appear in the Activity feed at all, the webhook isn't reaching us.

## "DM send failed" on a triggered comment

Common causes in order of likelihood:

- **Commenter deleted the comment** — the DM API needs a live comment ID to send a private reply
- **Commenter's account is private and hasn't messaged you** — Instagram may block DMs to strangers in this case
- **You hit Instagram's API rate limit** — ~200 calls/hour per Instagram account. Spacing rules out helps

Check the **Activity** tab — failed DMs show the exact Instagram error in red.

## Public reply not posting

Usually means Instagram flagged the reply as duplicate or too-quick. Instagram throttles "reply spam" aggressively. If multiple people comment the same trigger keyword within seconds, Instagram may reject the second and subsequent public replies. The DM will still succeed.

**Fix:** vary the reply text slightly per rule, or leave it blank for high-volume keywords.

## Connected Instagram account shows wrong username

The profile fetch runs during connect. If your Instagram username changed after connecting, click **Disconnect** and reconnect to refresh.

## Everything was working, then stopped

Check the connection card's **Token expires at** date. Instagram long-lived tokens live ~60 days. After expiry:

- Webhook events stop reaching Splashify Pro
- Sending DMs returns authentication errors
- Activity feed stops populating

**Fix:** click **Disconnect**, then **Connect Instagram** — the whole flow takes 30 seconds.

We'll add an auto-refresh path before you hit this, but manual reconnect always works.

## Still stuck?

Open a support ticket from [/support](https://app.splashifypro.com/support) and include:

- Your Instagram username
- The reel URL where the rule should have fired
- The trigger keyword
- A sample comment text that didn't fire

We can look up the activity log on our side and see exactly where it broke.


========================================================================
## Calling
URL: https://docs.splashifypro.com/calling
========================================================================

# Calling

Splashify Pro supports **WhatsApp Business Calling** — make and receive voice calls directly through the WhatsApp Business Platform, with full recording and billing support.

## Navigate to Calling

Click **Calling** in the left sidebar, or go to:

```
https://app.splashifypro.com/calling
```

## What You Can Do

| Feature | Description |
|---------|-------------|
| **Outbound calls** | Call customers directly from the Messages page |
| **Incoming calls** | Answer inbound WhatsApp calls in the browser |
| **Call recordings** | All calls recorded and stored automatically |
| **Call history** | View all past calls with duration and status |
| **Call permissions** | Request calling permission from contacts |
| **Analytics** | Call volume, duration, and cost analytics |

## How It Works

Splashify Pro uses **Meta's WhatsApp Business Calling API** and **WebRTC** to connect calls:

```
Your browser (WebRTC) ←→ Splashify Pro signaling ←→ Meta API ←→ Customer's WhatsApp
```

No phone hardware or SIM cards required. Calls work entirely through your web browser.

## Prerequisites

- WABA connected and phone number registered
- WhatsApp Calling enabled for your WABA (in Meta Business Settings)
- Call permission obtained from the contact (for the first call)
- Microphone permission granted in your browser

## Call Costs

WhatsApp calls are billed per minute. Costs are deducted from your wallet.

| Call Type | Rate |
|-----------|------|
| Outbound business-initiated | Per your plan rate |

Check your call analytics at **Calling → Analytics** for cost breakdown.


========================================================================
## Making Calls
URL: https://docs.splashifypro.com/calling/outbound-calls
========================================================================

# Making Calls

## Step 1: Open a Conversation

1. Go to **Messages**
2. Open the conversation with the contact you want to call

## Step 2: Initiate a Call

1. In the **Contact Details** panel on the right side
2. Click the **Phone icon (📞)** next to the contact's number
3. A call dialog opens

## Step 3: Confirm and Call

The call dialog shows a confirmation step:
- Displays your **business phone number** (the WABA number you're calling from)
- Shows a note about call permissions

Click **Start Call** to initiate.

## Call States

| State | Description |
|-------|-------------|
| **Connecting** | Establishing connection to Meta API |
| **Ringing** | Customer's phone is ringing |
| **Active** | Call is live — both parties connected |
| **Ended** | Call has concluded |

## During a Call

While a call is active, the call dialog shows:

| Control | Description |
|---------|-------------|
| **Mute** | Mute/unmute your microphone |
| **Speaker** | Toggle speakerphone |
| **End Call** | Hang up the call |
| **Duration timer** | Live call duration counter |

## After a Call

After hanging up, a **call summary** is shown with:
- Call duration
- Start and end time

The call is logged in the **Calling** page and the conversation's activity log.

## Browser Requirements

- Allow **microphone access** when the browser prompts
- Use **Chrome** or **Edge** for best WebRTC compatibility
- A stable internet connection is required (minimum 1 Mbps upload)

## Troubleshooting

| Issue | Fix |
|-------|-----|
| Call fails immediately | Check if calling permission exists for this contact |
| No audio | Check microphone permissions in browser settings |
| Call drops | Check internet connection stability |
| WABA error | Verify calling is enabled for your WABA in Meta |


========================================================================
## Call Permissions
URL: https://docs.splashifypro.com/calling/permissions
========================================================================

# Call Permissions

Before making a **business-initiated** WhatsApp call, the contact must have granted **calling permission**. This is a WhatsApp platform requirement to prevent spam calls.

## How Permissions Work

1. You send a **permission request message** to the contact
2. The contact taps the **"Allow Calls"** button in that message
3. Once granted, you can call them at any time

If you try to call without permission, the call will be rejected by Meta.

## Request Call Permission

### Via Interactive Message

1. Open a conversation in **Messages**
2. Click the **Call Permission** button in the message input area (or use the call dialog if the contact hasn't granted permission yet)
3. Select **Send Permission Request**
4. Choose the **permission request template** (pre-configured)
5. Send the message

The contact receives an interactive WhatsApp message with a button. When they tap it, permission is granted.

### Via Template Message

You can also send a template-based permission request during a broadcast or from the call management page.

## View Permission Status

Go to **Calling** and check the contact's permission status:

| Status | Meaning |
|--------|---------|
| **Granted** | Contact has allowed calls — you can call them |
| **Pending** | Permission request sent, awaiting response |
| **Denied** | Contact declined calling permission |
| **Not Requested** | No permission request sent yet |

## Call Permission Templates

Create and manage templates used for permission requests:

1. Go to **Calling**
2. Click **Call Templates**
3. Click **+ New Template**
4. Set the template type as **Permission Request**
5. Write the message (include a call-to-action button like "Allow Calls")
6. Submit for approval

> Permission request templates require Meta approval like all WhatsApp templates.

## Revoking Permission

Contacts can revoke permission at any time from their WhatsApp. If permission is revoked, subsequent call attempts will fail.

## Callback Requests

Contacts can also request a **callback** from your business:

1. Enable **Callback Permission** in **Settings → Calling**
2. Contacts can tap a button in your template message to request a callback
3. Callback requests appear in your **Calling** page for follow-up


========================================================================
## Call Recordings
URL: https://docs.splashifypro.com/calling/recordings
========================================================================

# Call Recordings

All WhatsApp Business calls through Splashify Pro are **automatically recorded** and stored in the cloud.

## Access Recordings

1. Go to **Calling**
2. Find the call in the call history table
3. Click the **Play** button in the Recording column to listen inline
4. Or click **Download** to download the audio file

## Call Detail Page

Click on any call row to open the full **Call Detail** page:

- Contact name and phone number
- Call direction (Inbound / Outbound)
- Start time, end time, and duration
- Call status (Completed, Missed, Failed)
- **Recording player** — play the audio directly in the browser
- **Upload Recording** — if a recording failed to attach, upload manually

## Call History Table

The calling list shows all calls with:

| Column | Description |
|--------|-------------|
| Contact | Name and phone number |
| Direction | Inbound or Outbound |
| Duration | Call length in minutes:seconds |
| Status | Completed / Missed / Failed |
| Date | When the call occurred |
| Recording | Play or download link |

## Storage

Recordings are stored in cloud object storage (DigitalOcean Spaces). Recordings are:
- Available immediately after the call ends
- Retained for the duration of your subscription

## Compliance Note

> **Important:** Inform your contacts that calls may be recorded for quality purposes. Recording laws vary by country — ensure you comply with local regulations.

## Filtering Calls

Use the filter options in the Calling page to narrow the list by:
- Date range
- Call status
- Contact name or phone


========================================================================
## Calling Settings
URL: https://docs.splashifypro.com/calling/settings
========================================================================

# Calling Settings

Configure calling behavior, operating hours, and templates.

Navigate to **Settings → Calling**.

## General Settings

| Setting | Description |
|---------|-------------|
| **Enable Calling** | Master toggle to enable/disable WhatsApp calling |
| **Show Call Button** | Show/hide the call icon in the Messages UI |
| **Allow Callback Requests** | Let contacts request a callback via button |

## Business Hours for Calls

Define when your team is available to take WhatsApp calls:

1. Toggle each day of the week
2. Set From/To time for each active day
3. Choose timezone

Calls outside business hours can be configured to:
- Play a voice message
- Send an auto-text reply
- Go unanswered

## Holiday Schedule

Add holidays when calling is unavailable:

1. Click **+ Add Holiday**
2. Select the date
3. Optionally add a holiday name
4. Save

## Call Templates

Manage templates used for call permission requests and callback messages:

1. Click **Call Templates** tab
2. Click **+ New Call Template**
3. Choose template type:
   - **Permission Request** — Ask contact for calling permission
   - **Call Button** — Interactive template to initiate a call link

Each template must be approved by Meta before use.

## Default Templates

Set which templates are used by default for:
- **Permission requests** — Sent when permission is needed before a call
- **Callback button** — Shown when contact can request a callback

To set a default:
1. Go to **Call Templates**
2. Click **Set as Default** on the template you want


========================================================================
## Templates
URL: https://docs.splashifypro.com/templates
========================================================================

# Templates

**Message Templates** are pre-approved messages required for initiating WhatsApp conversations outside the 24-hour window. All templates must be approved by Meta before use.

## Navigate to Templates

Click **Templates** in the left sidebar, or go to:

```
https://app.splashifypro.com/templates
```

## Template Types

| Type | Channel | Use |
|------|---------|-----|
| **Marketing** | WhatsApp | Promotions, offers, re-engagement |
| **Utility** | WhatsApp | Order updates, reminders, account alerts |
| **Authentication** | WhatsApp | OTP, verification codes |
| **RCS Templates** | RCS | Rich media campaigns |

## Template Status

| Status | Meaning |
|--------|---------|
| **Approved** ✅ | Ready to use in broadcasts and messages |
| **Pending** ⏳ | Submitted to Meta, awaiting review |
| **Rejected** ❌ | Meta declined — edit and resubmit |
| **Paused** ⚠️ | Temporarily paused by Meta due to quality issues |

## Sync Templates

If you have templates created directly in Meta Business Manager, sync them to Splashify Pro:

1. Go to **Templates**
2. Click **Sync Templates**
3. All your Meta-approved templates are imported

## Delete a Template

1. Find the template in the list
2. Click the **Delete** button
3. Confirm

> Deleting a template in Splashify Pro also deletes it from Meta. This is irreversible.


========================================================================
## Create a Template
URL: https://docs.splashifypro.com/templates/create-template
========================================================================

# Create a WhatsApp Template

## Step 1: Open Template Creator

1. Go to **Templates**
2. Click **+ Create Template**

## Step 2: Template Basics

| Field | Description |
|-------|-------------|
| **Template Name** | Lowercase letters, numbers, underscores only (e.g. `order_update_v1`) |
| **Category** | Marketing / Utility / Authentication |
| **Language** | Select the language(s) for this template |

## Step 3: Header (Optional)

Add a header above the body text:

| Header Type | Description |
|-------------|-------------|
| **Text** | Bold header text |
| **Image** | Image displayed at top |
| **Video** | Short video |
| **Document** | PDF or file attachment |
| **Location** | Static map location |

## Step 4: Body Text

The main message content. Use variables for personalization:

```
Hello {{1}}, your order {{2}} has been shipped and will arrive by {{3}}.
```

Variables are numbered `{{1}}`, `{{2}}`, etc. You'll map these to contact fields when sending.

**Body text limits:**
- Maximum **1024 characters**
- Supports `*bold*`, `_italic_`, `~strikethrough~`, `` `monospace` `` formatting

## Step 5: Footer (Optional)

Optional small grey text below the body. Commonly used for:
- Opt-out instructions
- Legal disclaimers

## Step 6: Buttons (Optional)

Add interactive buttons. Up to **10 buttons** per template.

### Button Types

| Type | Description |
|------|-------------|
| **Quick Reply** | Pre-set reply button — sends a text back |
| **Call to Action: URL** | Opens a website URL |
| **Call to Action: Phone** | Initiates a phone call |
| **Call to Action: Copy Code** | Copies a coupon/promo code |

## Step 7: AI Generation (Optional)

Don't know what to write? Use **Maya AI Generate** to create a complete template in seconds.

### How it works

1. Expand the **Maya AI** panel (Sparkles icon) in the form
2. Type a short description of what the template should do
3. Pick a **Style** — Normal, Poetic, Exciting, or Funny
4. Pick what to **Optimise for** — Click Rate (strong CTAs) or Reply Rate (ends with a question)
5. Click **Generate (₹2 per generation)**
6. Review the generated **Header**, **Body**, and **Buttons**
7. Click **Use This Template** to apply all three fields at once, or **Regenerate (₹2)** to try again

### What gets generated

| Field | What the AI produces |
|-------|----------------------|
| **Header** | Short punchy text (max 60 chars); may include `{{1}}` for a dynamic value |
| **Body** | Full message body starting with `Hi {{1}},`; uses `{{2}}`, `{{3}}` etc. for dynamic values |
| **Buttons** | 1–3 quick-reply button labels matching the call-to-action |

### Cost

Each generation deducts **₹2** from your **Wallet** (same wallet as WhatsApp messaging).
The deduction happens only after the AI successfully returns a result — a failed call costs nothing.

### Previous Prompts

Click **↶ Previous prompts** (next to the prompt input) to open a history of your last 20 AI-generated templates.
Each entry shows:
- The prompt you wrote
- The generated header, body, and buttons
- A **Use this template** button to instantly apply it to the form and set the prompt for further editing

This lets you quickly reuse a previous generation without paying for a new one.

### Variables

If the AI uses variables like `{{1}}` or `{{2}}` in the header or body, you will see them listed
in the **Sample Values** section below the body. Fill these in before submitting so Meta can
review the template with realistic content.

## Step 8: Preview and Submit

- Use the live **Preview** panel on the right to see how the message will look on a phone
- Click **Submit for Approval**

Meta reviews templates within **24–48 hours**. You'll receive an email when the status changes.

## Tips for Approval

| Do | Don't |
|----|-------|
| Use clear, business-relevant content | Include promotional language in Utility templates |
| Match category to content | Use vague placeholders like `{{1}}` without context |
| Keep body concise | Add unsolicited advertising |
| One clear CTA | Add misleading buttons |


========================================================================
## RCS Templates
URL: https://docs.splashifypro.com/templates/rcs-templates
========================================================================

# RCS Templates

**RCS Templates** are structured message formats used for RCS Broadcasts. Unlike WhatsApp, RCS templates support rich visuals — images, carousels, and action buttons.

## Navigate to RCS Templates

1. Go to **Templates**
2. Click **RCS Templates** tab

Or navigate to:
```
https://app.splashifypro.com/templates/rcs
```

## Create an RCS Template

1. Click **+ Create RCS Template**
2. Fill in the template details:

### Template Settings

| Field | Description |
|-------|-------------|
| **Name** | Internal name for the template |
| **Message Type** | Text / Image / Card / Carousel |
| **Content** | Message body (type-dependent) |

### RCS Message Types

**Text**
Simple plain text message.

**Image**
Image with optional caption.

```
- Image URL (direct link)
- Caption text (optional)
```

**Card**
Rich card with image, title, description, and buttons.

```
- Image URL
- Title
- Description
- Buttons (up to 4)
```

**Carousel**
Multiple cards in a horizontally swipeable view.

```
- Up to 10 cards
- Each card: image, title, description, buttons
```

### Button Types (RCS)

| Type | Description |
|------|-------------|
| **Reply** | Quick reply — sends a predefined text |
| **URL** | Opens a web URL |
| **Dial** | Dials a phone number |
| **Location** | Opens maps to a location |

## Template Review

RCS templates go through a review process:

1. **AI Review** — Automatic content check
2. **Admin Review** — Manual approval by Splashify Pro team
3. **Approved** — Ready to use in RCS broadcasts

| Status | Meaning |
|--------|---------|
| **Pending** | Under review |
| **Approved** ✅ | Ready to use |
| **Rejected** ❌ | Needs revision — review feedback |

## Resubmit a Rejected Template

1. Open the rejected template
2. Click **Edit**
3. Make the required changes (review the rejection reason)
4. Click **Resubmit**


========================================================================
## Email Marketing — Overview
URL: https://docs.splashifypro.com/email
========================================================================

# Email Marketing

Send branded email — marketing campaigns, transactional sends, password resets, order confirmations — from your own domain. Recipients see `dkim=pass` against your brand instead of ours.

## What you can do

- **Authenticate your sender domain** — publish 3 DNS records once; we sign every send with your domain
- **Build templates with the visual editor** — drag-in blocks (heading, image, button, footer), live preview, save once and reuse forever
- **Send campaigns** — pick a template, pick an audience (segments + contacts), schedule or send now, watch open + click rates roll in live
- **Transactional API** — `POST /public/email/send` from your backend for one-to-one sends (OTP, receipts, password resets)
- **Built-in compliance** — RFC 8058 one-click unsubscribe header on every send, suppression list enforced at send-time, hard-bounce auto-remove

## Pricing

- **First 100 emails per UTC day are free** — counter shared across marketing + transactional + public API
- Beyond that:
  - **Marketing emails**: ₹0.10 / email + reseller markup (if any)
  - **Transactional emails**: ₹0.05 / email + reseller markup (if any)
- Charges show in [Settings → Track Expenses](https://app.splashifypro.com/settings/track-expenses) as `email_marketing` and `email_transactional` line items, alongside your WhatsApp / RCS deductions

## Plan-gated

Email Marketing requires a plan with the **Email Marketing** feature enabled.

- **Trial users** get full access during the trial window
- **Paid users** need their plan's Email Marketing flag enabled (admin sets this on the plan)

If you see "Email Marketing requires an active plan" when opening `/email`, ask the platform admin to enable the flag on your plan.

## How to start

1. **[Connect your sender domain](./sender-domain.mdx)** — publish 3 DNS records on the domain you want to send from. Takes 5 min to publish, < 15 min to verify.
2. **[Build a template](./templates.mdx)** — open the visual editor, add blocks, save.
3. **[Send a campaign](./campaigns.mdx)** — pick template + audience, click Send.

Or if you want to send transactional email from your backend, jump to the **[Send Email API](https://docs.splashifypro.com/public-api/send-email)** reference.

## Architecture

Every email goes through the same pipeline regardless of source:

```
Your action (campaign / API / template send)
    ↓
We pre-render the template HTML (react-email cross-client output)
    ↓
We sign with your domain's DKIM key
    ↓
We deliver direct to recipient's MX server (STARTTLS, no third-party SMTP relay)
    ↓
Recipient sees: From <you@your-domain.com>, dkim=pass, spf=pass
```

The sender side is fully self-hosted — we don't relay through Resend / SES / Mailgun. Your domain reputation is yours.

## Compliance built in

- **One-click unsubscribe** — every email carries `List-Unsubscribe` + `List-Unsubscribe-Post: One-Click` headers (RFC 8058). Gmail and Outlook show their native Unsubscribe button automatically.
- **Suppression list** checked at send-time — once a recipient unsubscribes, they're suppressed for your account. New campaigns can't re-mail them.
- **Hard bounces auto-suppress** — invalid mailboxes added to your suppression list immediately so you don't keep hitting them and damaging reputation.
- **Footer is required** — every template's Footer block auto-injects company name, mailing address, and unsubscribe link. Required by CAN-SPAM (US) / GDPR (EU) / DPDP (India).

## See also

- [Connect your domain →](./sender-domain.mdx)
- [Build templates →](./templates.mdx)
- [Send campaigns →](./campaigns.mdx)
- [Troubleshooting →](./troubleshooting.mdx)
- [Public API for transactional sends →](https://docs.splashifypro.com/public-api/send-email)


========================================================================
## Send Email Campaigns
URL: https://docs.splashifypro.com/email/campaigns
========================================================================

# Send Email Campaigns

A campaign sends one template to many recipients. This is your bulk marketing path — for one-to-one transactional sends use the [public API](https://docs.splashifypro.com/public-api/send-email).

## Prerequisites

Before you can create a campaign:

1. **[At least one verified sender domain](./sender-domain.mdx)** — the `from_email` you choose has to live on a domain you've authenticated
2. **At least one [template](./templates.mdx)** — you can't send a blank message
3. **Contacts in segments** — campaigns send to segments. If you don't have any yet, build them at [Settings → Segments](https://app.splashifypro.com/settings/segments) first

If any of these is missing, the campaign create wizard will tell you and link directly to the fix.

## Open the wizard

[Email → Campaigns](https://app.splashifypro.com/email/campaigns) → **New campaign**.

The wizard has 4 steps. You can go Back at any point — nothing is saved until you finish step 4.

## Step 1 — Identity

Tell us who the email is from.

| Field | Notes |
|-------|-------|
| **Campaign name** (internal) | Just for your records — recipients never see this. e.g. *"Diwali sale 2026"* |
| **From name** | The sender display name. e.g. *"Acme Store"* |
| **From email** | Pick a verified domain from the dropdown, then edit the local part. e.g. `hello@acme-store.com`. Must be on a domain in [Sender Domains](https://app.splashifypro.com/settings/email-domain) with status=verified |
| **Reply-to** (optional) | Where customer replies should go (often your support inbox) |

> **Why does From email matter?** Recipients see the `From` line in their inbox. A friendly one (`hello@acme-store.com`) gets opened more than a noreply (`noreply@acme-store.com`). And replying to "noreply" feels cold — let customers actually respond.

## Step 2 — Pick a template

Grid of every template you've built. Click one to select.

> Don't have a template yet? The wizard will tell you and link to [Email → Templates → New](https://app.splashifypro.com/email/templates) so you can build one without losing your campaign-in-progress (the wizard preserves your name/from until you finish).

## Step 3 — Audience

Pick one or more segments. We send to every contact in those segments who:

- Has an email address (contacts without one are silently skipped — no error)
- Isn't on your suppression list (hard-bounced before, complained, or unsubscribed)
- Isn't a duplicate (the same contact in two segments = one email)

Segment counts shown next to each name help you estimate volume before you commit.

> **Segments only**: this version doesn't allow ad-hoc contact pickers. If you want to send to a specific list of people, build a segment first at [Settings → Segments](https://app.splashifypro.com/settings/segments) — that's also where the audience is reusable across campaigns.

## Step 4 — Schedule

Two options:

### Save as draft (default)

Best for first-time senders. Creates the campaign but doesn't send yet. You can review the recipient count on the campaign detail page, then click **Send now** when you're ready.

This is the safer flow — it lets you confirm "yes, send to 5,000 people" with one extra click rather than blasting on the wizard's last step.

### Schedule for later

Pick a date/time. We'll send at that moment.

> **Time zone**: schedule input uses your browser's local time. We convert to UTC server-side. Don't worry about DST or zone math.

When you click **Create campaign**, you land on the campaign detail page.

## Send the campaign

If you saved as draft, your campaign sits in **Draft** status. Hit **Send now** on the detail page when you're ready.

A confirmation dialog asks you to acknowledge: *"Sends to all matching recipients in your selected segments. This action cannot be undone."*

Click **Send** — the campaign flips to **Sending** status. You'll see live counters tick up:

| Counter | Meaning |
|---------|---------|
| **Recipients** | Total addresses we'll attempt |
| **Sent** | We've handed off to recipient's MX server |
| **Delivered** | MX server accepted the message |
| **Opened** | Recipient opened (tracked via 1×1 pixel — sprint 5) |
| **Clicked** | Recipient clicked any link (tracked via redirect — sprint 5) |
| **Bounced** | Hard or soft bounce |
| **Unsubscribed** | Recipient hit Unsubscribe |

The page auto-refreshes every 5 seconds while sending. You can leave it open or come back later.

## Cancel an in-flight campaign

Hit the **Cancel** button while status is `sending`. We stop dispatching new messages immediately.

> **Already-delivered emails can't be unsent.** Cancel just stops the queue from processing more. If you cancelled at 50% sent, the other 50% never receive.

## Costs

- **First 100 emails per UTC day are free** across your entire account (campaigns + transactional API combined)
- Beyond that:
  - **Marketing email** (campaign sends): ₹0.10/email + reseller markup (if your platform is white-labeled)
  - **Transactional email** (public API): ₹0.05/email + reseller markup
- Charges show in [Settings → Track Expenses](https://app.splashifypro.com/settings/track-expenses) under category `email_marketing`

The campaign detail page doesn't show the running cost yet (sprint 6); use Track Expenses for the breakdown.

## Health flags

The campaign detail page surfaces warnings when something looks off:

- **Bounce rate > 5%** — your list has too many invalid addresses. Bounce rates above 5% damage your sender reputation. Clean the list before the next campaign — remove obvious typos and confirm contacts opted in
- **Multiple unsubscribes in quick succession** — common when sending to a stale list. Pause and review your audience definition

## Best practices

- **Start small** — first campaign should be 100–500 recipients. Confirm delivery + open rates look reasonable before scaling
- **Send time matters** — Tuesday/Wednesday/Thursday between 10am–2pm in the recipient's local time-zone gets the highest open rates for most B2B audiences
- **Subject line < 50 chars** — Gmail truncates after that on mobile. Make the first 5 words count
- **Personalise** — use `{{first_name}}` in subject + greeting. Open rates jump 20–30%
- **A/B subject lines** — split your audience 50/50, send 2 variants, see which wins. (A/B testing as a built-in feature is sprint 6+)
- **Don't send too often** — once-a-week is the typical sweet spot for B2C marketing. Daily blasts kill engagement

## See also

- [Templates →](./templates.mdx)
- [Sender domains →](./sender-domain.mdx)
- [Track Expenses →](https://app.splashifypro.com/settings/track-expenses)
- [Troubleshooting →](./troubleshooting.mdx)


========================================================================
## Connect Your Sender Domain
URL: https://docs.splashifypro.com/email/sender-domain
========================================================================

# Connect Your Sender Domain

Before you can send a single email, you need to authenticate the domain you want to send from (e.g., `acme-store.com`). This proves to recipient servers that emails claiming to be from your domain are actually authorized by you.

We give you 3 DNS records to publish; once they resolve, your domain is verified and email-sender signs every outbound mail with your domain's DKIM signature so recipients see `dkim=pass header.d=acme-store.com` instead of our shared zone.

## When to do this

Once. Per domain. Setup takes ~5 minutes; DNS propagation takes 5 to 60 minutes.

You can authenticate up to 5 domains. Common pattern is to verify your apex (`acme-store.com`) plus a marketing subdomain (`mail.acme-store.com`) — keeps marketing send reputation isolated from your transactional / corporate mail.

## Step 1 — Add the domain

1. Open [Settings → Email Domain](https://app.splashifypro.com/settings/email-domain)
2. Click **Add domain**
3. Type your domain (e.g., `acme-store.com`) — without `https://`, without `@`
4. Click **Add**

The page now shows your domain in **Pending** status with the 3 DNS records you need to publish.

## Step 2 — Publish 3 DNS records

Open your domain's DNS provider in another tab — Cloudflare, Route 53, Namecheap, GoDaddy, DigitalOcean, whatever you use.

Copy each record from the Email Domain page and add it to your DNS:

### SPF — TXT record

```
Type:     TXT
Hostname: _spf.acme-store.com
Value:    v=spf1 include:_spf.splashifypro.com ~all
```

> **Already have an SPF record?** Most DNS providers allow only one TXT record at the same name. If `_spf.acme-store.com` already has an SPF (e.g., for Google Workspace), append our `include:` to the existing value:
>
> `v=spf1 include:_spf.google.com include:_spf.splashifypro.com ~all`

### DKIM — CNAME record

```
Type:     CNAME
Hostname: splashify._domainkey.acme-store.com
Value:    splashify._domainkey.mail.splashifypro.com
```

This is a CNAME chain — your record points to ours, recipient servers follow the chain to fetch our public key. Your private key never leaves our infrastructure.

> **Cloudflare proxy "flattening"?** If Cloudflare flattens this CNAME to an IP, switch the proxy off (orange cloud → grey cloud) for this record. Email DNS records should never be proxied.

### DMARC — TXT record

```
Type:     TXT
Hostname: _dmarc.acme-store.com
Value:    v=DMARC1; p=quarantine; rua=mailto:dmarc@splashifypro.com; pct=100; adkim=r; aspf=r
```

`p=quarantine` is our recommended starting policy — emails that fail SPF/DKIM checks land in spam rather than being rejected outright. Once you're confident your sends authenticate cleanly (give it 30 days), upgrade to `p=reject` for stronger protection against spoofing.

## Step 3 — Verify

Back on the [Email Domain](https://app.splashifypro.com/settings/email-domain) page, click **Verify now** on your pending domain.

We query your DNS provider directly via Cloudflare 1.1.1.1 / Google 8.8.8.8 (bypassing any system caches) and report each record's status:

| Status        | Meaning |
|---------------|---------|
| ✓ Pass        | Record found and matches expected pattern |
| ✗ NXDOMAIN    | Record not yet published. DNS propagation can take up to 1 hour |
| ✗ Wrong value | Record exists but doesn't include our `include:` / point at the right CNAME / start with `v=DMARC1`. Compare "Found" vs "Expected" in the UI |
| ✗ DNS timeout | Your DNS provider is slow. Click Verify again in a moment |

When all 3 are green, status flips to **Verified** and the green badge appears.

> **Auto-recheck**: even if you don't click Verify, we re-check every 15 minutes for pending domains. So if you publish DNS at 10:00 and forget about it, the domain auto-flips to Verified by 10:15.

## What happens after verification

Email-sender signs every outbound message from `<anything>@acme-store.com` with your domain's DKIM:

```
DKIM-Signature: v=1; a=rsa-sha256; d=acme-store.com; s=splashify; ...
```

Recipients (Gmail "Show original", etc.) see:

```
SPF:    PASS  with IP 203.174.23.244
DKIM:   PASS  with domain acme-store.com
DMARC:  PASS
```

Your brand. Your domain. Our infrastructure.

## What you can't do until verified

You can build templates and create campaigns in draft. But:

- **You can't actually send** from a non-verified `from_email` — campaign Send button errors with "domain not verified"
- **Public API `/email/send` returns 400** with `from_email domain '<x>' is not verified.` until verification is complete

This is intentional. Sending from an unverified domain hits recipient spam folders 60–90% of the time and damages our shared sending IP's reputation.

## Removing a domain

Click **Remove** on the domain card. Confirm. The domain is removed from your account and future sends from that `from_email` will be blocked.

> **Old DNS records**: removing a domain in our UI doesn't unpublish the DNS records on your side — those are yours to manage. If you want to fully clean up, delete the SPF / DKIM / DMARC records from your DNS provider too.

## Reseller-specific note

If you're an end customer of a reseller (your platform domain is `app.<reseller-domain>` rather than `app.splashifypro.com`):

- The verification flow is identical
- Your DKIM CNAME still points to `splashify._domainkey.mail.splashifypro.com` — that's our shared signing infrastructure regardless of which reseller you're under
- Your reseller's branding doesn't change the technical setup

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| All 3 records published but still pending after an hour | Click "Verify now" once. If still stuck: confirm records resolve via `dig +short TXT _spf.your-domain.com` and `dig +short CNAME splashify._domainkey.your-domain.com` from any computer. If those return empty, your DNS provider hasn't propagated yet — wait. |
| SPF shows "wrong_value" | The recommended SPF didn't get into the TXT record at `_spf.your-domain.com`. Check the actual published value (the UI shows "Found"). Make sure `include:_spf.splashifypro.com` is part of the SPF string. |
| DKIM shows "wrong_value" | The CNAME isn't pointing at the right target. Make sure it's `splashify._domainkey.mail.splashifypro.com.` (note the trailing dot in some DNS providers). |
| DMARC shows "wrong_value" | The TXT exists but doesn't start with `v=DMARC1`. Re-paste the recommended value. |
| Verified yesterday, today shows pending | We re-check every 24h on verified domains. If a record was rotated by your DNS provider or accidentally deleted, you'll get an in-app notification + status flip. Re-publish and click Verify. |

## See also

- [Build a template →](./templates.mdx)
- [Send a campaign →](./campaigns.mdx)
- [Troubleshooting →](./troubleshooting.mdx)


========================================================================
## Build Email Templates
URL: https://docs.splashifypro.com/email/templates
========================================================================

# Build Email Templates

Templates are reusable email designs. Build one with the visual editor, then send it to any audience from a campaign — or one-to-one via the public API.

> **Cross-client compatibility**: templates compile through [react-email](https://github.com/resend/react-email) (the same library Resend ships) so the final HTML works across Gmail, Outlook, Apple Mail, Yahoo, and mobile clients without you hand-rolling table-based markup.

## When to use a template

- Sending the same email shape repeatedly (order confirmations, OTP codes, password resets)
- Marketing campaigns where the design should be consistent across sends
- Anything you want non-developers on your team to update without redeploying

For one-off sends with bespoke HTML, the [public API `/email/send`](https://docs.splashifypro.com/public-api/send-email) endpoint takes inline HTML directly — no template needed.

## Open the editor

[Email → Templates](https://app.splashifypro.com/email/templates) → **New template**.

A blank template opens with three default blocks (heading, text, footer) so you have something to edit immediately.

## Editor layout

Three panes:

```
┌──────────────┬─────────────────────────────────┬──────────────┐
│ LEFT         │ CENTER                          │ RIGHT        │
│              │                                 │              │
│ Block        │ Live HTML preview               │ Selected     │
│ palette  +   │ (debounced 600ms after          │ block's      │
│ ordered      │  every edit, rendered through   │ properties   │
│ block list   │  the email-renderer sidecar)    │              │
│              │                                 │              │
└──────────────┴─────────────────────────────────┴──────────────┘
```

**Top bar**: template name + Save button + mobile/desktop preview toggle.

**Subject line**: shown above the editor in its own input. Subject is a property of the template, not a block.

## Available blocks

| Block | What it does |
|-------|--------------|
| **Heading** | H1 / H2 / H3 with bold styling. Use for section titles |
| **Text** | Paragraph — plain prose. Supports `{{variable}}` substitution |
| **Image** | Image with src, alt text, and width. Use absolute HTTPS URLs |
| **Button** | CTA button with custom background colour. Set href + text |
| **Divider** | Horizontal rule between sections |
| **Spacer** | Blank vertical space — set height in pixels |
| **Footer** | Auto-injects company name, address, and unsubscribe link. Required for compliance |

Click a block in the palette to add it to the bottom of your layout. Click any block in the layout list to select it; its properties appear in the right pane. Use the up/down chevrons to reorder.

## Variables

Use `{{variable_name}}` syntax anywhere in your subject, headings, or text.

Variables are substituted per recipient at send-time. For campaigns, the values come from contact attributes (e.g., `{{first_name}}` resolves to each contact's first name). For public API sends, the values come from the `variables` object in your request payload.

### Reserved variables

These are always available — no need to set them:

| Variable | Value |
|----------|-------|
| `{{recipient_email}}` | The recipient's email address |
| `{{unsubscribe_url}}` | Auto-injected by the Footer block |

### Unknown variables

Render as empty strings rather than failing the send. This makes optional fields safe — `{{coupon_code}}` shows nothing for recipients without a coupon.

## Live preview

The preview pane re-renders 600ms after your last edit (debounced). It calls the [email-renderer](https://github.com/resend/react-email) sidecar through our backend, so what you see is the actual cross-client HTML that gets shipped to recipients.

**Mobile preview**: click the mobile/desktop icon in the top bar to toggle. The preview pane resizes to 375px (mobile) or full-width (desktop) so you can confirm responsive behaviour.

## Save + test send

Click **Save** to persist your template. The save also pre-compiles the final HTML so per-recipient sends don't have to re-render — they just substitute variables into the snapshot.

> **Save before sending**: variable substitution + sending uses the **last saved version** of the template. If you change a template but don't save, the change won't appear in sends. Click Save before testing.

To test a saved template, the easiest path is:

1. Send a one-off campaign to a single contact (yourself)
2. Or via API: `POST /api/v1/public/email/send-template` with `template_id` + your email

## Compliance: the Footer block

Every email must include sender identification + an unsubscribe mechanism. The Footer block handles this automatically — it renders:

```
{{sender_company_name}}
{{sender_address}}
Unsubscribe
```

Set the company name + mailing address in the Footer block's properties. The unsubscribe link is auto-generated per recipient by the email-sender at send-time (HMAC-signed token).

> **Don't delete the Footer block.** Sending without it means your emails will fail Gmail / Yahoo's policy checks and likely land in spam. CAN-SPAM (US), GDPR (EU), and DPDP (India) all require sender identification + a working unsubscribe path.

## Editing an existing template

Click any template card in [Email → Templates](https://app.splashifypro.com/email/templates) to reopen the editor.

> **Already used in a campaign?** Editing a template doesn't change emails that have already been sent. It only affects FUTURE sends from this template. So you can safely tweak a template after a campaign launches without breaking the ones that already went out.

If you want a totally different design without losing the original, **duplicate**: click the template, change the name, then re-save → currently this requires copy-paste of the JSON; full duplicate-as-action button lands in a future sprint.

## Deleting a template

Trash icon on the template card → confirm. Past sends keep their already-rendered HTML; future campaigns can no longer reference this template.

## Best practices

- **Width**: 600px for the body container is the email industry standard — most clients render this cleanly without scrollbars
- **Images**: host them on a public CDN (DigitalOcean Spaces, Cloudflare R2, S3). Don't link to your private app URLs — many email clients block authenticated image fetches
- **Alt text**: always set `alt` on images. ~50% of inbox previews block images by default; alt text is what shows
- **Buttons**: use one primary CTA per email. Multiple CTAs hurt click-through rate
- **Plain text fallback**: don't worry about it — we auto-generate a plaintext version from your blocks. Recipients on text-only mail clients see a clean version
- **Test on mobile**: ~70% of marketing email opens are on mobile. Toggle to mobile preview before saving

## Limits

- **Max 200 templates per account** — this is generous; reach out if you need more
- **No custom CSS** in this version — block properties cover ~95% of typical email styling. Sprint 6+ may add an "advanced HTML" block for power users
- **No drag-drop** — reorder via the up/down arrows in the block list. Drag-drop adds 30 KB+ of JS for marginal UX gain

## See also

- [Send a campaign →](./campaigns.mdx)
- [Public API: Send Template Email →](https://docs.splashifypro.com/public-api/send-template-email)
- [Troubleshooting →](./troubleshooting.mdx)


========================================================================
## Email Troubleshooting
URL: https://docs.splashifypro.com/email/troubleshooting
========================================================================

# Email Troubleshooting

Hit something unexpected? Find your symptom below.

## "Email Marketing requires an active plan"

Shown when you visit `/email`, `/email/templates`, `/email/campaigns`, or `/settings/email-domain`.

**Cause**: your plan doesn't have the Email Marketing feature flag enabled.

**Fix**:
- If you're on a **trial**, the feature is free during the trial window. Confirm trial isn't expired in [Settings → Manage Subscriptions](https://app.splashifypro.com/settings/subscriptions)
- If you're on a **paid plan**, ask the platform admin to enable Email Marketing on your plan via Admin → Plans → [your plan] → Bundled Features → Email Marketing
- Refresh after enabling

## "from_email domain is not verified"

Shown when you try to send a campaign or call the public API.

**Cause**: the `from_email` you specified is on a domain you haven't completed DNS verification for.

**Fix**:
1. Go to [Settings → Email Domain](https://app.splashifypro.com/settings/email-domain)
2. Find the domain in question
3. If status is **Pending**, click **Verify now**. Per-record errors (SPF / DKIM / DMARC) tell you which DNS record is missing
4. If the domain isn't there at all, click **Add domain** and publish the 3 DNS records — see [Sender Domain →](./sender-domain.mdx)

## "domain not verified" on send (sprint 1+)

Same root cause as above, surfaced from the `email-sender` worker. Check the campaign detail page or outbox row's `last_error` for the exact failure.

## DNS records published but verification fails

**Cause**: DNS propagation lag, wrong hostname, or value mismatch.

**Fixes** in order of likelihood:

1. **Wait 15 minutes**. We auto-recheck pending domains every 15 min via Cloudflare 1.1.1.1 / Google 8.8.8.8 directly (bypassing system caches). Most resolve themselves
2. **Confirm the record exists** by querying any external DNS checker (e.g. [dnschecker.org](https://dnschecker.org)) — paste the exact hostname (e.g., `_spf.acme-store.com`)
3. **Check "Found" vs "Expected"** in the verify result on [Email Domain](https://app.splashifypro.com/settings/email-domain). If Found is blank, the record isn't published yet. If Found has a value but doesn't match Expected, you have a typo
4. **Double-suffix issue**: some DNS providers (DigitalOcean, etc.) auto-append your zone to the hostname. If you typed `_spf.acme-store.com` as the hostname, the provider stored it at `_spf.acme-store.com.acme-store.com`. Fix: re-enter the hostname as just `_spf` (the provider adds your domain automatically)
5. **Cloudflare proxy**: if your DKIM CNAME is showing the orange-cloud (proxied) icon, switch it to grey (DNS-only). Cloudflare flattens proxied CNAMEs to A records, breaking the chain

## "daily_free_limit_exceeded"

**Cause**: you hit 100 emails for the day across all sources (campaigns + public API). The counter resets at 00:00 UTC.

**Fix**:
- Wait until midnight UTC for the counter to reset, or
- Wait for sprint 6 (wallet billing) — beyond the free limit, additional sends will charge ₹0.10 (marketing) / ₹0.05 (transactional) per email from your wallet. Currently still in dev

## "insufficient_balance"

**Cause** (post sprint 6): wallet doesn't have enough to cover a paid send.

**Fix**: recharge at [Wallet](https://app.splashifypro.com/wallet) — minimum top-up varies by plan.

## Email landed in spam

**Causes** in rough order:
1. **Sender domain not yet verified** → verify it
2. **Brand new domain or IP** → reputation takes 4-8 weeks to build. Send small volumes (50/day → 200/day → 1k/day) for the first 6 weeks
3. **Spam-trigger words** in subject or body → "FREE!!!", "100% guaranteed", excessive caps, !!!! style punctuation
4. **No unsubscribe** → impossible since the Footer block auto-injects, but if you removed Footer from the template, restore it
5. **Image-only email** → ratio of images to text matters. Keep at least 60% of body as readable text
6. **Too many links** → 1 primary CTA + 2 secondary is fine. 10 links per email looks like phishing
7. **Bounce rate above 5%** → your list has invalid addresses, hurting reputation. Suppress hard bounces, remove obvious typos before sending

Use [mail-tester.com](https://www.mail-tester.com) to score your template — aim for 9+/10.

## "Renderer service unavailable" in template editor

**Cause**: the email-renderer Node sidecar is unreachable.

**Fix**: should auto-recover within seconds. If it persists, refresh the page; if still broken, raise a support ticket — this is platform-side, not on you.

## High bounce rate on a campaign

**Cause**: list quality. Common patterns:

- **Imported from a CSV with old contacts** — emails go stale. ~10% of B2B emails decay/year
- **Imported from a public source** (LinkedIn, etc.) — opt-in is questionable, addresses unreliable
- **Wrong format** — typos like `gmial.com`, missing TLD, etc.

**Fix**:
1. Stop the campaign if bounce rate > 5% on the first batch
2. Use a list-cleaning service (NeverBounce, ZeroBounce, etc.) before the next send
3. Build segments based on engagement — only send to contacts who interacted in the last 90 days

## Variable showing as `{{first_name}}` literally in the email

**Cause**: variable substitution didn't fire. Two reasons:

1. **You changed the template but didn't save** — sends use the last-saved version. Click Save, then send again
2. **Variable name doesn't match the contact attribute** — `{{first_name}}` looks for an attribute literally named `first_name`. Check the attribute spelling at [Settings → Attributes](https://app.splashifypro.com/settings/attributes). Common: `firstName` vs `first_name`

For the public API, `{{var}}` looks up `var` in the `variables` object you sent. Mismatched key = empty replacement.

## Recipients say they didn't unsubscribe but still got marked

**Cause**: gmail's native "Unsubscribe" button (powered by RFC 8058 List-Unsubscribe-Post) is one click — sometimes accidental. Or someone reported as spam, which counts as unsubscribe.

**Fix**: admin can manually remove from the suppression list at Admin → Email System → Suppression. But only do this with explicit confirmation from the recipient — re-mailing a suppressed address damages your reputation.

## Public API: `Invalid API key.`

**Cause**:
- Key revoked or regenerated since last use
- Wrong header format (`Authorization: Basic <key>` is correct; `Bearer` is wrong for our public API)
- Key copied with leading/trailing whitespace

**Fix**: regenerate at [Settings → Developer](https://app.splashifypro.com/settings/developer). Test with `curl`:

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/email/send \
  -H "Authorization: Basic sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"to":"you@example.com","subject":"test","html":"<p>test</p>","from_email":"hello@your-verified-domain.com"}'
```

## Public API: `Rate limit exceeded`

**Cause**: per-plan rate limit (e.g., 40 requests/minute on starter plans).

**Fix**:
- Reduce send rate
- Implement exponential backoff in your code on 429 responses
- Upgrade your plan for a higher limit
- See [Rate Limits](https://docs.splashifypro.com/public-api/rate-limits)

## Status endpoint returns "queued" forever

**Cause**: the `email-sender` worker isn't processing your queue. Either it's down (rare) or your specific message hit a permanent error early.

**Fix**:
1. Wait 30 seconds — most queued messages reach `sent` within 5 sec
2. If still queued after 60 sec, check Settings → Track Expenses to see if any deduction happened (suggests it actually sent)
3. If genuinely stuck, raise a support ticket with the `message_id`

## Still stuck?

- Try the [Public API Live API Tester](https://docs.splashifypro.com/public-api/try-it) for API issues
- Ask Maya — the in-app AI assistant has the full email-marketing knowledge base loaded. Open Maya from the headset icon
- Raise a support ticket from [Settings → Support](https://app.splashifypro.com/support) — include the `message_id` if it's a delivery issue

## See also

- [Sender domain setup →](./sender-domain.mdx)
- [Templates →](./templates.mdx)
- [Campaigns →](./campaigns.mdx)


========================================================================
## Lead Capture Widget
URL: https://docs.splashifypro.com/lead-widget
========================================================================

# WhatsApp Lead Capture Widget

A floating WhatsApp bubble you embed on your website. Visitors fill a
short form (name + phone + optional message), the contact is auto-
created in your Splashify Pro CRM, and they're redirected to WhatsApp
with their message prefilled — landing the conversation in your team
inbox already linked to the new contact.

## What you get

- **One-line embed** — paste a `<script>` tag in your site and the
  bubble appears at the bottom of every page.
- **Customizable bubble + form** — theme color, position (bottom-right
  or bottom-left), headline, subheadline, button label, prefilled
  WhatsApp message, optional name/message fields.
- **Auto-CRM** — every submission creates a contact tagged
  `lead-widget` with attribution metadata (page URL, referrer,
  widget ID).
- **Inbox routing** — when the visitor sends their first WhatsApp
  message, it lands in `/messages` already linked to the contact you
  captured.
- **Spam protection** — domain allowlist (Origin header check),
  per-IP rate limit (10 captures/hour), optional Cloudflare Turnstile.
- **Shadow DOM** — the widget runs in an isolated CSS scope so it
  never collides with your site's styles, even on heavy frameworks
  like React, Vue, or jQuery.

## Plan requirements

- Growth or Business plan (or active free trial).
- A connected WhatsApp Business number — visitors will be redirected
  to chat with this number.

## Quick start

1. Open **Settings → Lead Widget** in Splashify Pro.
2. Add the domains you'll embed on (e.g. `acme.com`, `www.acme.com`).
3. Customise the bubble (theme color, headline, button text) — preview
   updates live.
4. Copy the `<script>` snippet from the Embed section.
5. Paste it into the `<body>` of every page on your site.

That's it. The bubble appears at the bottom of every page within
seconds. Captured leads show up in **Settings → Lead Widget → Captures**
and in your main **Contacts** list with the `lead-widget` tag.

## How it works

```
Visitor on your site
   ↓ clicks bubble → small form opens (name, phone, message)
   ↓ submits → POST /widget/<id>/capture
        ↓ origin check (must match allowed_domains)
        ↓ rate limit check (10/hour per IP)
        ↓ optional Turnstile verification
        ↓ creates app_contacts row + tag = "lead-widget"
        ↓ creates conversation linked to contact
        ↓ returns wa.me deep-link
   ↓ same-tab redirect to wa.me
   ↓ WhatsApp app/web opens with message prefilled
   ↓ visitor sends → conversation lands in /messages
```

The contact and conversation exist before the visitor even sends their
first message — so you can run automations, send templates, or assign
to a team member as soon as the form lands.

## Continue reading

- [Setup & Embed](/lead-widget/setup) — step-by-step embed guide
- [Customize](/lead-widget/customize) — theme color, copy, fields, branding
- [Capturing Leads](/lead-widget/captures) — what data is captured + segments
- [Troubleshooting](/lead-widget/troubleshooting) — common issues


========================================================================
## Capturing Leads
URL: https://docs.splashifypro.com/lead-widget/captures
========================================================================

# Capturing Leads

Every form submission creates two artifacts in your account: a row in
the **Captures activity feed** (90-day retention, your dashboard view)
and a permanent **Contact** record (no expiry, lives in `/contacts`).

## What gets stored

For every successful submission:

**On `app_contacts` (permanent)**
- `display_name` — the visitor's name (or `+<phone>` if name field
  was off)
- `whatsapp_id` / `phone_number` — normalised E.164
- `tags` — `["lead-widget"]`
- `column_data` — JSON with attribution metadata:
  - `lead_source`: `"lead_widget"`
  - `widget_id`: the widget that captured them
  - `lead_page_url`: which page on your site they were on
  - `lead_referrer`: where they came from before that

**On `app_lead_widget_captures` (90-day TTL)**
- All of the above plus IP address, user agent, raw message, captured
  timestamp. Used by the activity feed in the settings page so you
  can see recent submissions at a glance.

**On `app_conversations`**
- A new conversation linked to the contact. So when the visitor sends
  their first WhatsApp message after the redirect, it lands in
  Messages already attached to the right contact.

## Building segments off captured leads

Every contact tagged `lead-widget` shows up in
**Settings → Segments** when you build a segment with that tag
condition. Use this to:

- Send a follow-up broadcast to recent leads who didn't reply
- Apply automation flows to all widget submissions
- Track conversion rates from widget → paid customer in analytics

You can also segment by `lead_page_url` to target visitors who came
from specific pages (pricing, demo request, etc.) using contact
attribute conditions.

## Viewing recent captures

**Settings → Lead Widget → Captures** shows the last 100 submissions
with:

| Column | What it shows |
|--------|---------------|
| When | Relative timestamp |
| Name | What the visitor entered |
| Phone | Normalised E.164 |
| Message | Their note (truncated) |
| From page | Page URL where they submitted (linked) |

Click the row → open the linked conversation in `/messages`.

The tab auto-refreshes every 30 seconds, so new submissions appear
without a manual reload.

## Re-submissions

If a visitor submits the form twice with the same phone number:

- The contact is **not duplicated** — the existing contact is reused.
- A new capture row IS created (so the activity feed shows both).
- Tags are not reset — if you'd manually added other tags to the
  contact, they're preserved.

## Privacy + compliance

The widget stores IP address + user agent on each capture for abuse
investigation. These age out automatically after 90 days via the
table TTL. Names + phones on `app_contacts` are permanent (until you
delete them) since that's the persistent CRM record.

If you need to delete a captured contact for GDPR / DPDP compliance:

1. Open `/contacts`.
2. Find the contact (filter by tag `lead-widget`).
3. Delete — wipes the contact, conversation, and all captures.

## Data export

The Captures tab doesn't currently have a CSV export. Use
**Contacts → Export** with the `lead-widget` tag filter for full data
including the attribution `column_data`.

## Webhook delivery (coming soon)

v1 doesn't fire a webhook on capture. To trigger automations now, use
the **Flows** builder with the trigger condition:

- "Inbound message arrives on conversation tagged `lead-widget`"

Once the visitor sends their first WhatsApp message, the flow runs.
A direct on-capture webhook is on the v2 roadmap so you can act
before the visitor even reaches WhatsApp.


========================================================================
## Customize the Widget
URL: https://docs.splashifypro.com/lead-widget/customize
========================================================================

# Customize the Widget

Every visible element of the widget is editable from
**Settings → Lead Widget**. Changes save automatically when you tab
out of a field, and apply within ~60 seconds on every site (the
widget's config endpoint is cached briefly to keep load times fast).

## Theme color

Pick any hex color. The bubble background, the form header, and the
submit button all adopt the color. Default is WhatsApp green (`#25D366`)
which feels native to the use case — most users keep it.

If you change it to match your brand, pick something that contrasts
well with white text since the headline + button label are always
white.

## Position

Bottom-right (default) or bottom-left. Pick whichever doesn't collide
with other floating elements you have (chat support, cookie banners,
back-to-top buttons).

## Copy

| Field | Max | Where it appears |
|-------|-----|------------------|
| Bubble text | 40 | Tooltip next to the floating bubble |
| Headline | 60 | Top of the open form |
| Subheadline | 120 | Below the headline |
| Button text | 40 | Submit button on the form |
| Prefilled message | 500 | Pre-typed in WhatsApp after redirect |

The prefilled message is what visitors see waiting in the WhatsApp
input field after they click submit — they can edit it before sending,
or send as-is. Use it to give your team context about where the lead
came from:

```
Hi! I saw your pricing page and want to know about the Growth plan.
```

If the visitor wrote their own message in the form, that overrides
the prefill — your team gets their actual intent rather than a
generic template.

## Form fields

- **Phone number** — always required. Visitors must enter a valid
  phone in E.164-ish format (10–15 digits, optional `+` prefix).
- **Name** — toggle on/off. Defaults to required since name massively
  improves lead quality.
- **Message** — toggle on/off. Defaults to optional since a forced
  message field reduces submissions ~30%.

## Branding

By default the form shows a small "Powered by Splashify Pro" credit
line at the bottom. Toggle it off to hide. Your visitors won't know
the widget exists as a third-party tool.

## Anti-spam

### Domain allowlist

The most important defense — the widget refuses any submission from
a domain not on your list. Origin spoofing is hard from a browser
(browsers always set Origin on cross-site POSTs), so this catches
99% of abuse attempts.

### Rate limit

10 submissions per IP per hour, automatic. Above the limit, the
widget shows "Too many submissions" and the next attempt is rejected
at the API level.

### Cloudflare Turnstile (optional)

If you start seeing scripted abuse from real-looking IPs, enable
Turnstile:

1. Sign up at [Cloudflare](https://dash.cloudflare.com/?to=/:account/turnstile)
   (free).
2. Add a new site, get the **Site Key**.
3. Toggle Turnstile on in the widget settings, paste the Site Key.
4. The widget loads the Turnstile script and shows a small invisible
   challenge before submission.

The challenge is invisible to legitimate users on most browsers; bots
fail it silently and submissions are rejected with `turnstile_failed`.

## Live preview

The right pane in the settings page shows a faithful preview of how
the widget will look on a visitor's site. It updates the moment you
change theme color, copy, or toggle form fields. Use it to nail the
look without redeploying anything.

## What you CAN'T customize (yet)

These are deliberate limits in v1:

- Form layout — fields appear in a fixed order (name → phone →
  message). No multi-step forms.
- Custom CSS / HTML overrides on the form body
- Multiple widget configs per user (one widget per account)
- A/B testing variants
- Meta CAPI / GA4 / GTM event firing on submission

If any of these are blockers, [contact support](mailto:support@splashifypro.in)
— we prioritise customer requests for the v2 spec.


========================================================================
## Setup & Embed
URL: https://docs.splashifypro.com/lead-widget/setup
========================================================================

# Setup & Embed

## 1. Open the widget settings

Navigate to **Settings → Lead Widget** (the gear icon in the top right
of the app, then the **Lead Widget** tile under Analytics & Commerce).

If your plan doesn't include the widget, you'll see an upgrade card —
the widget ships with Growth and Business plans plus the free trial.

## 2. Add allowed domains

The widget refuses submissions from any domain not on this list. Add
each host where you'll embed the snippet:

- `acme.com` (apex)
- `www.acme.com` (www subdomain — if you use both)
- `landing.acme.com` (any subdomain you also want enabled)
- `acme.in` (additional TLDs you own)

You can add or remove domains anytime; changes take effect immediately.

## 3. Connect a WhatsApp number

The bubble redirects visitors to chat with your connected WhatsApp
Business number. If you haven't set one up yet, head to
**Dashboard → WhatsApp Setup** first — you'll need:

- A Meta Business account
- A WhatsApp Business number (phone or virtual)
- Embedded Signup completed

Until a number is connected, the widget won't function — visitors
clicking the bubble will see "Chat is currently unavailable".

## 4. Copy the embed snippet

In the Embed section you'll see a `<script>` tag like:

```html
<script src="https://app.splashifypro.com/widget.js"
        data-widget="lw_a3f8z2k9wp" async></script>
```

Click **Copy** to grab it.

## 5. Paste into your site

### Plain HTML / static site

Add the snippet just before the closing `</body>` tag of every page
you want the widget on:

```html
<!DOCTYPE html>
<html>
<head>...</head>
<body>
  <!-- your site content -->

  <script src="https://app.splashifypro.com/widget.js"
          data-widget="lw_a3f8z2k9wp" async></script>
</body>
</html>
```

### WordPress

- **Header/Footer plugin** — paste into the Footer Scripts box
  (Insert Headers and Footers, WPCode, or similar).
- **Theme functions** — add to `footer.php` just before `</body>`.
- **Elementor** — use a Custom Code element set to "Insert in body
  end".

### Shopify

`Online Store → Themes → Edit code → theme.liquid` → paste before
`</body>`.

### Wix / Squarespace / Webflow

Each platform has a "custom code" / "embed code" feature. Paste the
snippet in the **body end** position so it loads after the rest of
the page.

### React / Next.js

```tsx
// app/layout.tsx (Next.js 13+)
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <script
          src="https://app.splashifypro.com/widget.js"
          data-widget="lw_a3f8z2k9wp"
          async
        />
      </body>
    </html>
  );
}
```

The widget initialises lazily — it doesn't fetch any config until the
visitor clicks the bubble — so the page-load impact is just one tiny
async script (~10 KB).

## 6. Verify it works

1. Open your site in an incognito window.
2. The bubble appears at the bottom-right (or whatever position you
   picked).
3. Click → form opens.
4. Fill it in with a real phone number → click submit.
5. Check **Settings → Lead Widget → Captures** — your submission
   should appear within a few seconds.
6. Check **Contacts** — there's a new entry tagged `lead-widget`.
7. Send the WhatsApp message your visitor flow ends with — it lands
   in **Messages** linked to that contact.

If the bubble doesn't appear, see [Troubleshooting](/lead-widget/troubleshooting).

## Multiple sites

You can embed the same snippet on as many sites as you want — just
make sure every domain is in the allowlist. Each captured contact
records its `lead_page_url` and `widget_id` so you can build segments
per source.

## Rotating the widget ID

If your snippet leaks publicly (e.g. you've published it in a code
sample) and you start seeing abuse from unauthorized domains, click
**Regenerate widget ID** on the settings page. This invalidates every
deployed snippet and gives you a fresh one — you'll need to update
the embed on every site.

The old widget_id immediately starts returning 404 on both the config
fetch and capture POST, so leaked snippets stop working without delay.


========================================================================
## Lead Widget Troubleshooting
URL: https://docs.splashifypro.com/lead-widget/troubleshooting
========================================================================

# Troubleshooting

Symptom-first list of the most common issues with embedding and using
the lead widget.

## Bubble doesn't appear on my site

**Check the browser console.** Most issues are visible there:

- `Splashify Widget: missing data-widget attribute` → the snippet was
  pasted incorrectly. Make sure `data-widget="lw_..."` is present.
- `Failed to fetch` on click → the widget config endpoint is
  unreachable. Check that your network/firewall isn't blocking
  `app.splashifypro.com`.
- Nothing logged at all → the script tag may not have loaded. View
  page source and confirm the `<script>` tag is actually in the
  HTML (some site builders strip JS unless explicitly allowed).

**Page caching.** If you just embedded, your CDN / page cache might
still serve the pre-embed HTML. Hard refresh (Ctrl+Shift+R) or
purge your CDN cache.

**Disabled widget.** Open Settings → Lead Widget and verify the
"Widget enabled" toggle is on. When disabled, the bubble doesn't
render even if the snippet is on the page.

## "This widget isn't authorised on this site"

The page domain isn't in your allowed_domains list. Add it:

- `acme.com` AND `www.acme.com` are different — list both if you use
  both.
- Subdomains aren't wildcarded — add `landing.acme.com` separately
  from `acme.com`.
- HTTP vs HTTPS doesn't matter — the host name is what's matched.

## Submissions get "Chat is currently unavailable"

This means the widget tried to redirect to wa.me but you don't have
a WhatsApp number connected. Open **Dashboard → WhatsApp Setup** and
complete Embedded Signup.

## "Too many submissions in the last hour"

The 10/hour per-IP rate limit kicked in. Common causes:

- A single user kept submitting the form (legit user — wait an hour
  or test from a different network).
- A bot is targeting your widget — enable Turnstile.
- You're testing from your office and multiple devices share the
  same NAT IP — switch to mobile data for testing.

## Form opens but submit button doesn't work

Open the browser DevTools network tab and click submit:

- 400 with `invalid_phone` → phone format wrong (must be 10–15 digits
  with optional `+`).
- 403 with `origin_not_allowed` → see "isn't authorised" above.
- 403 with `widget_disabled` → widget toggle is off.
- 429 with `rate_limited` → see "Too many submissions" above.
- 400 with `turnstile_failed` → Turnstile rejected the challenge;
  verify the sitekey matches what Cloudflare shows.

## Submitted but nothing showed in CRM

Open **Settings → Lead Widget → Captures** first. If the row is there,
the submission worked. Check **Contacts** filtered by tag
`lead-widget` — should be the same record.

If the capture row is NOT there but the visitor reports submission
went through:

- They might have hit a transient error and we returned 500. Check
  the network response in their browser (or yours, replay the test).
- If they got the wa.me redirect, the contact + capture should both
  exist. Search by phone number.

## Visitor went to WhatsApp but nothing in /messages

The wa.me deep-link puts your number in their WhatsApp — the
conversation only appears in `/messages` after they actually press
send on their device. Many visitors land on the WhatsApp app and
abandon. The contact + capture are still in your CRM.

## Widget styles look broken on my site

The widget runs in a Shadow DOM, which means CSS from your site
shouldn't affect it AND the widget's CSS shouldn't leak into your
site. If you see styling issues:

- Right-click the bubble → Inspect. The widget should be inside
  `<div id="splashify-lead-widget">` followed by `#shadow-root (open)`.
- If the shadow root isn't there → your browser is too old (IE11 /
  very old Safari). The widget refuses to initialize on these
  browsers.
- If something looks off inside the form, take a screenshot and
  email [support@splashifypro.in](mailto:support@splashifypro.in).

## CSP (Content Security Policy) blocks the script

Some sites have a CSP header that blocks third-party scripts. You'll
see in the browser console:

```
Refused to load the script 'https://app.splashifypro.com/widget.js'
because it violates the following Content Security Policy directive:
"script-src 'self'"
```

Add `app.splashifypro.com` to your CSP `script-src` directive:

```
Content-Security-Policy: script-src 'self' https://app.splashifypro.com;
                         connect-src 'self' https://app.splashifypro.com;
```

The widget also makes `fetch()` calls to the same host, so
`connect-src` needs to include it too.

## Plan-locked even though I have a paid plan

Open **Settings → Subscriptions** and confirm your plan is **active**
and the billing cycle hasn't expired. The widget gates on
`lead_widget_enabled` AND `plan_status === "active"`.

If you upgraded but the gate didn't lift after a few minutes, contact
support — the plan flag may not have been set on your specific plan
record.

## Still stuck?

Email [support@splashifypro.in](mailto:support@splashifypro.in) with:

- Your widget ID (`lw_...`) from the settings page
- Browser console screenshot if applicable
- The URL where you embedded
- A description of what should happen vs what does


========================================================================
## Integrations Overview
URL: https://docs.splashifypro.com/integrations
========================================================================

# Integrations Overview

Splashify Pro's integrations let any external platform (Razorpay, Stripe, Shopify, Zapier, HubSpot, etc.) fire a WhatsApp template message to your customers in response to an event — a successful payment, a new order, a dropped checkout, a ticket reply.

Every integration uses the same primitive: **you paste a webhook URL into the other platform; we receive the payload; we pick a template, fill in the variables from the payload, and send.**

## How it works

```
Vendor event  →  Splashify webhook receiver  →  Template send
┌──────────┐     ┌──────────────────────┐     ┌─────────────┐
│ Razorpay │ ──▶ │ POST /webhooks/integ.│ ──▶ │ WhatsApp    │
│ payment  │     │ /{user_id}/{slug}    │     │ template to │
│ captured │     │                      │     │ customer    │
└──────────┘     └──────────────────────┘     └─────────────┘
```

Behind the scenes each inbound request passes through four gates:

1. **Signature verification** — for Razorpay, Stripe, Shopify, and WooCommerce we check the HMAC signature using your configured `webhook_secret`. Forged requests get rejected with HTTP 401. If you haven't set a secret yet, the request is accepted but flagged as *unverified* in the audit log.
2. **Idempotency** — every request is identified by the vendor's event ID (or a content hash). We insert-if-not-exists into a 7-day dedupe table. Retries of the same event return `200 {duplicate: true}` without re-sending.
3. **Event routing** — for multi-event integrations (Razorpay, Stripe, Shopify, WooCommerce, Freshdesk, Calendly) we pick the template configured for that specific event type. Events you haven't mapped are skipped silently.
4. **Template send** — we extract the recipient phone number from the configured `phone_field` path, resolve template variables via your variable mapping, and send via your WABA.

Every outcome — sent, duplicate, signature failed, phone missing, send failed — is captured in the audit log with the raw body, so "my webhook fired but no message went out" is always debuggable.

## Core concepts

### Webhook URL

Every integration has a single inbound URL of the shape:

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/{YOUR_USER_ID}/{slug}
```

You'll find the exact URL (with your user id already filled in) on each integration's detail page in Splashify. Paste it into the vendor's webhook configuration.

### Phone field

Tells us **where in the payload to find the customer's phone number**. Dot notation for nested fields:

- `contact` — `{"contact": "919876543210"}` → the top-level `contact` string
- `customer.phone` — `{"customer": {"phone": "..."}}`
- `billing.phone` — `{"billing": {"phone": "..."}}`

The phone is sent as-is to Meta — it should include the country code, no `+` or spaces needed (we strip `+` automatically).

### Variable mapping

For each template variable `{{1}}`, `{{2}}`, etc., you choose a payload field path. Example for a Razorpay payment success:

| Template var | Field path           | Example value |
|--------------|----------------------|---------------|
| `{{1}}`      | `amount`             | `50000`       |
| `{{2}}`      | `id`                 | `pay_abc...`  |
| `{{3}}`      | `notes.order_id`     | `ORD-123`     |

Fields that don't exist on a given payload resolve to an empty string — check the audit log when your message shows up with blanks where values should be.

### Multi-event automations

Some vendors fire webhooks for many event types to the same URL. For these you set up one template per event:

| Vendor        | Events supported                                                 |
|---------------|------------------------------------------------------------------|
| Razorpay      | `payment.captured`, `payment.failed`                             |
| Stripe        | `payment_intent.succeeded`, `payment_intent.payment_failed`      |
| Shopify       | `checkouts/create`, `orders/paid`, `orders/cancelled`            |
| WooCommerce   | `order.created`, `order.updated`                                 |
| Freshdesk     | `ticket_created`, `ticket_updated`                               |
| Calendly      | `invitee.created`, `invitee.canceled`                            |

Event types you don't map are received but skipped — no template fires. That's fine, just configure the ones you care about.

### Audit log

Every inbound webhook writes one row to the audit log (30-day retention). View it under the integration's **Logs** tab. Each row shows:

- Timestamp, slug, event type, event id
- Status — `sent`, `duplicate`, `signature_failed`, `config_missing`, `phone_missing`, `send_failed`
- HTTP status returned to the vendor
- Error message (if any)
- Template name + recipient phone
- Raw request body (up to 16KB) and Interakt response (up to 4KB)

If a webhook didn't behave the way you expected, start here.

## Security model

### Signature verification (recommended)

Any vendor with a signing scheme — Razorpay, Stripe, Shopify, WooCommerce — should have `webhook_secret` set. Once set, requests missing or failing signature validation are rejected with HTTP 401 and the vendor will stop retrying forged requests.

Without a secret the URL is public and anyone who discovers it could inject fake events. The audit log flags these as `unverified`.

### Credential storage

API keys, webhook secrets, and OAuth tokens are stored in ScyllaDB scoped to your user. They're accessible only to the webhook receiver running under your account.

### Plan limits

Some plans cap which integrations you can enable. The list of allowed slugs is surfaced on the integrations page — disallowed integrations show an **Upgrade** prompt instead of a **Connect** button.

## Pick a guide

- **Payments:** [Razorpay](/integrations/razorpay), [Stripe](/integrations/stripe), [PayPal](/integrations/paypal), [Cashfree](/integrations/cashfree), [PayU](/integrations/payu), [Xendit](/integrations/xendit), [Aspire](/integrations/aspire)
- **E-Commerce:** [Shopify](/integrations/shopify-marketing), [WooCommerce](/integrations/woocommerce)
- **Automation:** [Zapier](/integrations/zapier), [Pabbly](/integrations/pabbly), [Make](/integrations/make), [Google Sheets](/integrations/google-sheets)
- **CRM:** [Zoho CRM](/integrations/zoho-crm), [HubSpot](/integrations/hubspot), [Salesforce](/integrations/salesforce), [Freshworks CRM](/integrations/freshworks-crm)
- **Finance & Support:** [Zoho Billing](/integrations/zoho-billing), [Freshdesk](/integrations/freshdesk), [Calendly](/integrations/calendly)
- **Custom:** [Generic Webhook](/integrations/generic-webhook) — bring any platform that can fire an HTTP POST
- **Debugging:** [Troubleshooting](/integrations/troubleshooting)


========================================================================
## Aspire
URL: https://docs.splashifypro.com/integrations/aspire
========================================================================

# Aspire

## Setup

### 1. Copy the Splashify webhook URL

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/aspire
```

### 2. Configure in Aspire

Aspire dashboard → **Settings → Webhooks / API**. Add an endpoint pointing to the URL above.

### 3. Configure in Splashify

- **Phone Field** — depends on the Aspire event shape; typical path is `customer.phone` or `merchant.contact_phone`
- **Variables** — map to `amount`, `currency`, `transaction_id`, etc. based on your capture-mode inspection

Signature verification is not yet implemented for Aspire — keep the URL private.

## Related

- [Troubleshooting](/integrations/troubleshooting)


========================================================================
## Calendly
URL: https://docs.splashifypro.com/integrations/calendly
========================================================================

# Calendly

Calendly fires webhooks when an invitee books or cancels — perfect for instant WhatsApp booking confirmations and reminders.

| Event               | Typical template                           |
|---------------------|--------------------------------------------|
| `invitee.created`   | `Your call is confirmed for {{date}}`      |
| `invitee.canceled`  | "Your call has been cancelled"             |

## Setup

### 1. Copy the Splashify webhook URL

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/calendly
```

### 2. Create the webhook in Calendly

Calendly has no UI for webhooks — use the [Calendly API](https://developer.calendly.com/api-docs/create-webhook-subscription):

```bash
curl -X POST https://api.calendly.com/webhook_subscriptions \
  -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "YOUR_SPLASHIFY_URL_HERE",
    "events": ["invitee.created", "invitee.canceled"],
    "organization": "YOUR_ORG_URI",
    "user": "YOUR_USER_URI",
    "scope": "user"
  }'
```

Get the org + user URIs from [api.calendly.com/users/me](https://api.calendly.com/users/me) (authenticated).

### 3. Configure in Splashify

Calendly payload shape: `payload.invitee.{name, email, text_reminder_number}` etc.

- **Phone Field** → `payload.text_reminder_number` (Calendly uses this key for the phone the invitee provides at booking; only present when your event type collects it)
- Variables:

  | Var     | Field path                    | Sample                 |
  |---------|-------------------------------|------------------------|
  | `{{1}}` | `payload.name`                | `Ramesh`               |
  | `{{2}}` | `payload.scheduled_event.start_time` | `2026-05-01T10:00:00Z` |
  | `{{3}}` | `payload.scheduled_event.name` | `Discovery Call`      |

- Map one template per event via **Event Automations**.
- **Enabled** → **Save**.

## Gotchas

- **Phone collection is opt-in per event type.** In Calendly event-type settings, enable SMS reminders (which collects phone) or add a custom "Phone number" question.
- **Time format is ISO 8601 UTC.** Your template should display the time in the invitee's timezone — Calendly sends `payload.invitee.timezone` which you can pass through but formatting is up to the recipient's phone.
- **Signature verification not yet wired.** If you need it, Calendly does publish an `X-Calendly-Signature` header for future support.

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [Calendly webhooks API →](https://developer.calendly.com/api-docs/webhooks-overview)


========================================================================
## Cashfree
URL: https://docs.splashifypro.com/integrations/cashfree
========================================================================

# Cashfree

Cashfree wraps its events as `{ "data": { "order": {...}, "payment": {...}, "customer_details": {...} } }`. Splashify flattens those three sub-objects into one namespace so your field paths stay simple.

## Setup

### 1. Copy the Splashify webhook URL

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/cashfree
```

### 2. Add in Cashfree

[merchant.cashfree.com](https://merchant.cashfree.com) → **Developers → Webhooks → Add Webhook**.

| Field          | Value                        |
|----------------|------------------------------|
| Webhook URL    | URL from step 1              |
| Events         | `PAYMENT_SUCCESS_WEBHOOK`    |

Cashfree generates a webhook secret — copy it.

### 3. Configure in Splashify

**Configuration** tab:

- **Webhook Secret** — paste from Cashfree
- **Phone Field** — `customer_phone` (Cashfree customer_details flattens into root after normalization)
- **Variables:**

  | Var     | Field path         | Sample          |
  |---------|--------------------|-----------------|
  | `{{1}}` | `customer_name`    | `Rahul`         |
  | `{{2}}` | `order_amount`     | `1499`          |
  | `{{3}}` | `cf_payment_id`    | `1234567`       |
  | `{{4}}` | `order_id`         | `order_abc123`  |

- **Enabled** → **Save**.

## Gotchas

- **Signature verification not yet wired** for Cashfree specifically — stored but not checked. Treat the URL as semi-private.
- **Multiple sub-objects get merged**. If `data.order.foo` and `data.payment.foo` both exist, the second-loaded one wins. Pick unambiguous field names in your path config.

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [Cashfree webhooks docs →](https://www.cashfree.com/docs/api-reference/payments/latest/webhooks)


========================================================================
## Freshdesk
URL: https://docs.splashifypro.com/integrations/freshdesk
========================================================================

# Freshdesk

Trigger WhatsApp messages when a support ticket is created or updated — great for first-response SLAs ("we've received your ticket, ref #123") and reply notifications.

| Event            | Typical template                             |
|------------------|----------------------------------------------|
| `ticket_created` | Ticket received with ref #                   |
| `ticket_updated` | Status change or reply posted                |

## Setup

### 1. Copy the Splashify webhook URL

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/freshdesk
```

### 2. Configure Freshdesk automations

Freshdesk admin → **Automations → Ticket creation** (or **Ticket updates**) → **+ New Rule**.

1. Conditions — as narrow or broad as you want.
2. Actions → **Trigger Webhook**:

   | Field            | Value                                      |
   |------------------|--------------------------------------------|
   | Request type     | POST                                       |
   | Callback URL     | URL from step 1                            |
   | Encoding         | JSON                                       |
   | Authentication   | (none)                                     |
   | Content          | Advanced — build a JSON body:              |

   ```json
   {
     "event": "ticket_created",
     "data": {
       "ticket": {
         "id": {{ticket.id}},
         "subject": "{{ticket.subject}}",
         "requester": {
           "name": "{{ticket.requester.name}}",
           "phone": "{{ticket.requester.phone}}"
         }
       }
     }
   }
   ```

3. Save + activate.

### 3. Configure in Splashify

Freshdesk's `data.ticket` is unwrapped by Splashify automatically.

- **Phone Field** → `requester.phone`
- Variables:

  | Var     | Field path            | Sample        |
  |---------|-----------------------|---------------|
  | `{{1}}` | `id`                  | `1042`        |
  | `{{2}}` | `subject`             | `Can't login` |
  | `{{3}}` | `requester.name`      | `Deepika`     |

- Map one template per event via **Event Automations** (`ticket_created`, `ticket_updated`).
- **Enabled** → **Save**.

## Gotchas

- **Requester phone is often blank** — Freshdesk's default form only collects email. Add a "Phone" field to your ticket form if you want reliable WhatsApp routing.
- **Event name is in the JSON body**, not a header — make sure your Automations template includes `"event": "ticket_created"` (or `_updated`) verbatim.

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [Freshdesk Automations docs →](https://support.freshdesk.com/en/support/solutions/articles/37541)


========================================================================
## Freshworks CRM
URL: https://docs.splashifypro.com/integrations/freshworks-crm
========================================================================

# Freshworks CRM

## Setup

### 1. Copy the Splashify webhook URL

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/freshworks_crm
```

### 2. Create a Freshworks workflow

Freshworks CRM → **Admin Settings → Workflows → + Workflow**.

1. Module — Contact / Deal
2. Event — When a Contact/Deal is created / updated / matches conditions
3. Action → **Trigger a Webhook**:
   - URL: step-1 URL
   - Method: POST
   - Content: Simple / Advanced
   - For Advanced, craft a flat JSON with the fields you want

### 3. Configure in Splashify

- **API Key** — optional
- **Phone Field** → `mobile_number` or `phone_numbers.0.value` (the latter isn't supported due to array indexing — prefer mobile_number or a flat field)
- Variables → map to Freshworks field names
- **Enabled** → **Save**.

## Gotchas

- **Array fields (like `phone_numbers[]`) don't work in field paths.** Copy the primary mobile to a flat field via the workflow or use simple content.
- **Signature verification not yet wired.**

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [Freshworks webhooks →](https://developers.freshworks.com/)


========================================================================
## Generic Webhook
URL: https://docs.splashifypro.com/integrations/generic-webhook
========================================================================

# Generic Webhook

The Generic Webhook is the most powerful integration — it doesn't assume a vendor shape at all. Point any system that can POST JSON to a URL at Splashify, define conditions on the payload, and attach actions (send template, update contact tags, delay, chain). Used for custom back-office systems, internal events from your own backend, or niche platforms that aren't in the first-class integration list.

## What makes it different from the vendor integrations

| Feature                      | Vendor integration | Generic Webhook     |
|------------------------------|--------------------|---------------------|
| Fixed slug per vendor        | ✅                 | ❌ (custom)         |
| Fixed event detection        | ✅                 | ❌ (conditions)     |
| One template per event       | ✅                 | ❌ (multi-action)   |
| Capture mode to inspect payload | ❌              | ✅                  |
| Chain actions (delay + tag + send) | ❌           | ✅                  |
| ALL / ANY condition matching | ❌                 | ✅                  |

## Setup

### 1. Create a connection

Splashify Pro → **Integrations → Generic Webhook → Create Connection**. You'll get a unique URL:

```
https://apis.splashifypro.com/api/v1/webhooks/generic/<connection-id>
```

### 2. Turn on **Capture Mode**

Capture Mode is the secret weapon. When enabled:

1. Fire a test request from your source system at the URL above.
2. Splashify stores the first payload it receives and shows it to you in the connection editor.
3. You now know the exact JSON shape — field names, nesting, types.
4. Capture Mode auto-disables after the first payload, so production traffic doesn't fill up storage.

### 3. Build workflows

Each connection can have up to 5 workflows. A workflow is `conditions → actions`.

**Conditions** (all or any must match):

| Operator    | Behaviour                                |
|-------------|------------------------------------------|
| Equal       | Exact string match                       |
| Not equal   | —                                        |
| Contains    | Substring                                |
| Starts with | Prefix                                   |
| Ends with   | Suffix                                   |
| Exists      | Field is present in payload              |
| Not exists  | Field is absent                          |

Example conditions:

- `body.event` equals `user.upgraded`
- `body.customer.country` starts with `IN`
- `headers.x-source` exists

**Actions:**

1. **Send message** — pick template, map variables using `{{body.field}}` or `{{headers.x-custom-header}}` tokens, optional delay (0s / 60s / 5min / 1h).
2. **Update contact tags** — adds or removes tags on the contact matched by phone. Silent no-op if contact doesn't exist yet.

Actions chain in order — a workflow can send a template now, update a tag, and send a follow-up template after 1 hour.

### 4. Variable tokens

Unlike vendor integrations (which use numeric `{{1}}`, `{{2}}` keyed to a field path), Generic Webhook uses inline tokens. Inside any template variable value you can write:

- `{{body.customer.name}}` — nested payload field
- `{{headers.x-event-id}}` — request header (lowercased)
- Plain text around tokens: `Hi {{body.customer.first_name}}, your order {{body.order_id}} is ready`

## Use cases

- **Custom SaaS signup flow** — Your backend fires `POST /webhooks/generic/{id}` when a new user signs up → Splashify sends welcome template + tags contact as `new-signup`.
- **Stock back-in-stock alerts** — Inventory system fires when SKU crosses threshold → Splashify sends template to everyone tagged `wishlist-SKU-1234`. (You'd build this as a broadcast, not per-event — but the trigger could come from here.)
- **Internal ops notifications** — Fire from your CI/CD on a failed deploy → Splashify pings ops team's WhatsApp.
- **CRM that isn't in the first-class list** — If your CRM can fire webhooks (most can), use Generic Webhook instead of waiting for us to add first-class support.

## Limits

- **5 workflows per connection** (hard cap; upgrade request: [support](/support))
- **Condition operators** are plain string ops — no regex yet
- **Delays** are discrete values (0 / 60 / 300 / 3600 seconds) — no arbitrary timestamps
- **Array indexing in paths** isn't supported (`body.items[0].name` won't resolve) — use Zapier or Make as a formatting proxy if you need it

## Troubleshooting

- **Payload isn't matching my conditions.** Re-enable Capture Mode, fire the request, and verify the exact field path Splashify sees.
- **Phone lookup fails for tag updates.** The phone has to exist as a contact first. Either create the contact via the send-message action (which implicitly writes it) or import/sync contacts first.
- **Same webhook fires my message multiple times.** Generic Webhook doesn't have per-request idempotency like the vendor integrations. Add a content-hash condition or debounce at the sender.

## Related

- [Troubleshooting](/integrations/troubleshooting)


========================================================================
## Google Sheets
URL: https://docs.splashifypro.com/integrations/google-sheets
========================================================================

# Google Sheets

Trigger a WhatsApp message every time a new row is added (or edited) in a Google Sheet. Because Google Sheets doesn't have a native webhook, this uses a short **Apps Script** that POSTs to Splashify on change.

## Setup

### 1. Copy the Splashify webhook URL

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/google_sheets
```

### 2. Open Apps Script on your sheet

Sheet → **Extensions → Apps Script**. Paste:

```js
function onEdit(e) {
  // Only fire on edits in the main data sheet
  if (e.range.getSheet().getName() !== 'Sheet1') return;

  const row = e.range.getRow();
  if (row === 1) return; // header row

  const sheet = e.range.getSheet();
  const values = sheet.getRange(row, 1, 1, sheet.getLastColumn()).getValues()[0];

  // Map your columns — adjust to match your sheet
  const payload = {
    phone: String(values[0]),
    first_name: String(values[1]),
    amount: String(values[2]),
    order_id: String(values[3]),
  };

  UrlFetchApp.fetch('PASTE_SPLASHIFY_URL_HERE', {
    method: 'post',
    contentType: 'application/json',
    payload: JSON.stringify(payload),
  });
}
```

Replace `PASTE_SPLASHIFY_URL_HERE` with the URL from step 1. Save the script.

### 3. Grant permissions

First time the script runs, Google prompts for permissions (UrlFetch + read sheet). Approve.

### 4. Configure in Splashify

- **Phone Field** → `phone`
- Variables → `first_name`, `amount`, `order_id` (match what you sent in the Apps Script payload)
- **Enabled** → **Save**.

### 5. Test

Add a row with a real phone number. The `onEdit` trigger fires within a second; check the Splashify logs.

## Alternatives

- If you want **new row** events (not just edits), use `onChange` instead and filter `e.changeType === 'INSERT_ROW'`.
- For **batched syncs** (daily send based on a column value), use a time-based trigger in Apps Script instead.

## Gotchas

- **Apps Script triggers don't fire on API / external edits** — only on human edits in the UI. For API-driven updates, you need an installable trigger plus a time-based check.
- **Rate limit.** Apps Script limits UrlFetch to 20,000 calls/day (business), 2000/day (consumer). Past that, batch the notifications.
- **Sheet changes are lossy under high-frequency writes.** Don't expect millisecond-precise ordering.

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [Apps Script triggers →](https://developers.google.com/apps-script/guides/triggers)


========================================================================
## HubSpot
URL: https://docs.splashifypro.com/integrations/hubspot
========================================================================

# HubSpot

HubSpot Operations Hub workflows can POST JSON to any URL on contact / deal events. Use it for "thanks for your inquiry" auto-replies or "deal-stage moved" messaging.

## Setup

### 1. Copy the Splashify webhook URL

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/hubspot
```

### 2. Create a HubSpot workflow

[hubspot.com](https://app.hubspot.com) → **Automation → Workflows → Create workflow** (requires **Operations Hub Professional or higher**).

1. Object — Contact-based
2. Enrollment trigger — e.g. "Contact form submission received"
3. Add action → **Trigger a webhook** → **Webhook URL** → URL from step 1 → method **POST**
4. Save + publish

HubSpot will send the full contact record as JSON. Look at Capture/Logs in Splashify to see the exact shape.

### 3. Configure in Splashify

- **API Key** — optional (future 2-way sync via Private App access token)
- **Phone Field** → `properties.phone` (HubSpot nests all contact properties under `properties`)
- **Variables:**

  | Var     | Field path                       | Sample               |
  |---------|----------------------------------|----------------------|
  | `{{1}}` | `properties.firstname`           | `Aarav`              |
  | `{{2}}` | `properties.email`               | `aarav@example.com`  |
  | `{{3}}` | `properties.lifecyclestage`      | `lead`               |

- **Enabled** → **Save**.

## Gotchas

- **Phone must be stored in HubSpot's `phone` property** — if you stored it in a custom property, update the field path to `properties.your_custom_field_name`.
- **Workflow webhooks require Ops Hub Professional** — free/starter plans don't have this action.
- **Signature verification not yet wired** for HubSpot. Use HubSpot's app-scoped tokens if you want extra lockdown.

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [HubSpot workflow webhooks →](https://knowledge.hubspot.com/workflows/use-webhooks-with-workflows)


========================================================================
## Make (Integromat)
URL: https://docs.splashifypro.com/integrations/make
========================================================================

# Make (Integromat)

Make (formerly Integromat) is the visual-scenario alternative to Zapier/Pabbly. Same integration shape on our side.

## Setup

### 1. Copy the Splashify webhook URL

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/make
```

### 2. Build the scenario

[make.com](https://www.make.com) → **Create a new scenario**.

1. **Trigger** — any app + event.
2. **Action** — add an **HTTP → Make a request** module.
3. Configure:

   | Field          | Value                                         |
   |----------------|-----------------------------------------------|
   | URL            | URL from step 1                               |
   | Method         | POST                                          |
   | Headers        | `Content-Type: application/json`              |
   | Body type      | Raw                                           |
   | Request content | JSON with flat keys (`phone`, `name`, etc.)  |
   | Parse response | Yes                                           |

4. Run once to test.

### 3. Configure in Splashify

- **Phone Field** → `phone` (or whatever key you used)
- Variables → map to your JSON keys

## Gotchas

- Same as [Zapier](/integrations/zapier) — no event routing, no signing. Keep the webhook URL private.

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [Make HTTP module docs →](https://www.make.com/en/help/app/http)


========================================================================
## Pabbly Connect
URL: https://docs.splashifypro.com/integrations/pabbly
========================================================================

# Pabbly Connect

Same shape as Zapier — Pabbly is the cost-effective alternative with unlimited tasks on a flat plan. If your volume is above 100 events/day, this is usually cheaper.

## Setup

### 1. Copy the Splashify webhook URL

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/pabbly
```

### 2. Build the workflow in Pabbly

[pabbly.com/connect](https://www.pabbly.com/connect) → **Create Workflow**.

1. **Trigger** — pick your source app + event.
2. **Action** — **API by Pabbly → POST**.
3. Configure:

   | Field          | Value                                    |
   |----------------|------------------------------------------|
   | URL            | URL from step 1                          |
   | Method         | POST                                     |
   | Content Type   | `application/json`                       |
   | Body           | JSON with flat keys (`phone`, `first_name`, etc.) |

4. **Test** — fires a sample request → keep the Splashify logs tab open to watch it arrive.

### 3. Configure the integration in Splashify

Same as Zapier — **Phone Field** set to `phone` (or your chosen key), variables mapped by key name, toggle **Enabled**.

## Gotchas

- Same as [Zapier](/integrations/zapier) — no event routing, no signing, JSON shape is yours to design.

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [Pabbly Connect docs →](https://www.pabbly.com/connect/features/)


========================================================================
## PayPal
URL: https://docs.splashifypro.com/integrations/paypal
========================================================================

# PayPal

Trigger a WhatsApp message when PayPal reports a successful transaction. PayPal uses IPN or Webhooks — Splashify receives the PayPal Webhook format.

## Setup

### 1. Copy your Splashify webhook URL

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/paypal
```

### 2. Add the webhook in PayPal

[developer.paypal.com](https://developer.paypal.com) → **Apps & Credentials** → pick your app → scroll to **Webhooks** → **Add Webhook**.

| Field           | Value                                               |
|-----------------|-----------------------------------------------------|
| Webhook URL     | URL from step 1                                     |
| Event types     | `Payment capture completed` (and optionally `Payment capture denied`) |

Save. PayPal issues a Webhook ID — keep it visible.

### 3. Configure in Splashify

**Configuration** tab:

- **API Key / Webhook ID** — paste PayPal's Webhook ID (used for future verification support)
- **Phone Field** — depends on how you collect phone. PayPal doesn't always return it. Two options:
  - Pass phone at order-creation time as `custom_id` or inside `purchase_units[0].custom_id` → set field path to `custom_id`
  - Use PayPal's *Buyer contact info* experience and map `payer.phone.phone_number.national_number`
- **Variables:**

  | Var     | Field path                           | Sample     |
  |---------|--------------------------------------|------------|
  | `{{1}}` | `amount.value`                       | `299.00`   |
  | `{{2}}` | `amount.currency_code`               | `USD`      |
  | `{{3}}` | `id`                                 | `3C679...` |

- Toggle **Enabled** → **Save**.

### 4. Test

From the PayPal Webhooks UI → **Webhooks Simulator** → pick `PAYMENT.CAPTURE.COMPLETED` → **Send Test**. Check the Splashify logs.

## Gotchas

- **Phone isn't guaranteed.** PayPal only returns phone when the buyer explicitly shares it — store it yourself at checkout time.
- **Signature verification not yet enabled.** Keep the URL secret and consider rotating by creating a new integration + deleting the old one if exposed.

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [PayPal webhook docs →](https://developer.paypal.com/api/rest/webhooks/)


========================================================================
## PayU
URL: https://docs.splashifypro.com/integrations/payu
========================================================================

# PayU

## Setup

### 1. Copy the Splashify webhook URL

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/payu
```

### 2. Configure in PayU

[dashboard.payu.in](https://dashboard.payu.in) → **Settings → Webhooks / Server-to-Server**.

| Field          | Value                                |
|----------------|--------------------------------------|
| Notification URL | URL from step 1                    |
| Events         | Success (S) + optionally Failure (F) |

PayU will post a form-encoded or JSON body back on every payment state change — pick JSON if offered.

### 3. Configure in Splashify

**Configuration** tab:

- **Phone Field** — `phone` (PayU places it on root)
- **Variables:**

  | Var     | Field path     | Sample                  |
  |---------|----------------|-------------------------|
  | `{{1}}` | `firstname`    | `Kavita`                |
  | `{{2}}` | `amount`       | `799.00`                |
  | `{{3}}` | `txnid`        | `TXN_1704567890`        |
  | `{{4}}` | `productinfo`  | Your product descriptor |

- **Enabled** → **Save**.

## Gotchas

- **PayU posts form-urlencoded by default.** Switch your PayU config to **Server-to-Server JSON** mode — Splashify only parses JSON bodies.
- **Event routing isn't wired for PayU.** Use your PayU notification filter to only subscribe to the one state you want (usually Success).
- **Signature verification not yet enabled** in Splashify for PayU. Keep the URL private.

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [PayU webhooks docs →](https://docs.payu.in/docs/payment-webhooks)


========================================================================
## Razorpay
URL: https://docs.splashifypro.com/integrations/razorpay
========================================================================

# Razorpay

Route Razorpay payment events to WhatsApp — order confirmations on success, retry prompts on failure. Signed with HMAC-SHA256 so forged events are rejected.

## What you get

| Event                | Typical template       |
|----------------------|------------------------|
| `payment.captured`   | "Payment received ✅" — amount, id, order link |
| `payment.failed`     | "Payment didn't go through" — amount, retry link |

You can wire one or both events. Each event gets its own template + variable mapping.

## Prerequisites

- Razorpay **Live** or **Test** account ([dashboard.razorpay.com](https://dashboard.razorpay.com))
- At least one **approved WhatsApp template** in Splashify — usually with 2-3 variables (amount, customer name, order id)
- Your Splashify WABA active (Dashboard shows *WABA connected*)

## Setup

### 1. Copy your Splashify webhook URL

In Splashify Pro, open **Integrations → Razorpay**. Copy the webhook URL — it looks like:

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/razorpay
```

### 2. Add the webhook in Razorpay

Razorpay dashboard → **Settings → Webhooks → + Add New Webhook**.

| Field           | Value                                        |
|-----------------|----------------------------------------------|
| Webhook URL     | The URL from step 1                          |
| Secret          | Generate a random string (32+ chars). **Save this — you'll paste it into Splashify next.** |
| Alert Email     | Your email                                   |
| Active Events   | `payment.captured` and/or `payment.failed`   |

Click **Create Webhook**.

### 3. Paste the secret + pick your template in Splashify

Back on the Razorpay integration page in Splashify → **Configuration** tab:

1. Paste the secret from step 2 into **Webhook Secret**. This is what locks down forged requests — once set, any unsigned or wrongly-signed POST gets rejected with 401.
2. Pick your approved template for `payment.captured`.
3. Set **Phone Field** → `contact` (Razorpay puts the customer phone on the payment entity's `contact` field).
4. **Variable Mappings** — for each template variable, choose the payload field:

| Template var | Field path (`payment.captured` payload) | Sample value                 |
|--------------|-----------------------------------------|------------------------------|
| `{{1}}`      | `amount`                                | `50000` (in paise)           |
| `{{2}}`      | `currency`                              | `INR`                        |
| `{{3}}`      | `id`                                    | `pay_29QQoUBi66xm2f`         |
| `{{4}}`      | `email`                                 | `customer@example.com`       |
| `{{5}}`      | `notes.order_id`                        | Your passed-through note     |

5. Repeat for `payment.failed` — typically `amount` + `error_description`.
6. Toggle **Enabled** on and **Save**.

### 4. Test

In Razorpay dashboard → the webhook you just created → **Send Test Event**. Splashify receives it, fires the template, and logs the outcome.

Check **Integrations → Razorpay → Logs** — you should see a `sent` row within 5 seconds.

## Payload reference

Razorpay wraps the payment in `payload.payment.entity` — Splashify normalizes this so you just use the inner field name (`id`, `amount`, `contact`, etc.) in your field paths.

Key fields on a payment:

- `id` — `pay_...`, unique per payment
- `amount` — in paise (divide by 100 for rupees; Razorpay doesn't do this for you)
- `currency` — `INR`, `USD`, etc.
- `status` — `captured` / `failed`
- `method` — `card` / `netbanking` / `upi` / `wallet`
- `email`, `contact` — customer details
- `notes` — any custom key/value you passed at order creation
- `error_code`, `error_description` — only on failed payments

For the full shape, see [Razorpay's payment webhook docs](https://razorpay.com/docs/webhooks/payloads/payments/).

## Common gotchas

- **Amount is in paise.** `{{1}} = amount` renders as "50000" for a ₹500 charge. Template it as `₹{{1}}` and educate users, or pre-divide by 100 in your template variable copy.
- **Secret mismatch** — every attempt logs `signature_failed` with status 401. Double-check you pasted the same secret in both dashboards (no trailing newline).
- **`notes` fields need to be sent at order creation.** If you didn't pass them, they won't show up on the webhook.
- **Test events have dummy data.** Real phone/email fields are blank on test events — the message will target an empty phone. Test with a real small-amount payment when you can.

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [Razorpay webhook docs →](https://razorpay.com/docs/webhooks/)


========================================================================
## Salesforce
URL: https://docs.splashifypro.com/integrations/salesforce
========================================================================

# Salesforce

Salesforce doesn't expose a native "webhook to URL" button — you wire it via **Flow → Action → HTTP Callout** (Lightning) or **Outbound Messages** (classic).

## Setup

### 1. Copy the Splashify webhook URL

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/salesforce
```

### 2. Create a Named Credential (one-time)

Salesforce Setup → **Named Credentials → New Legacy**.

| Field       | Value                                  |
|-------------|----------------------------------------|
| Label       | Splashify Pro                          |
| URL         | `https://apis.splashifypro.com`        |
| Identity    | Anonymous                              |

Save.

### 3. Build a Flow with an HTTP Callout

Setup → **Flows → New Flow → Record-Triggered Flow**.

1. Object — **Lead** (or Contact / Opportunity)
2. Trigger — **A record is created**
3. Add element → **Action → HTTP Callout → Create Invocable Action**:
   - Label: `Splashify webhook`
   - URL: `{!$Credentials.Splashify_Pro}/api/v1/webhooks/integrations/<your-user-id>/salesforce`
   - Method: POST
   - Body: JSON with the lead's fields you want to pass

   ```json
   {
     "Phone": "{!$Record.Phone}",
     "FirstName": "{!$Record.FirstName}",
     "Company": "{!$Record.Company}"
   }
   ```

4. Save + activate the Flow.

### 4. Configure in Splashify

- **Phone Field** → `Phone`
- Variables → `FirstName`, `Company`, etc.
- **Enabled** → **Save**.

## Gotchas

- **HTTP Callouts require Named Credentials** on recent API versions — set it up once and reuse for every flow.
- **Outbound Messages send XML, not JSON.** Splashify expects JSON — always use HTTP Callouts for new integrations.
- **Salesforce trial orgs can't make external callouts** — upgrade to a Developer or Enterprise edition.

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [Salesforce HTTP Callouts →](https://help.salesforce.com/s/articleView?id=sf.flow_ref_elements_actions_http.htm)


========================================================================
## Shopify
URL: https://docs.splashifypro.com/integrations/shopify-marketing
========================================================================

# Shopify

Shopify fires an event for practically every state change on a checkout or order. Splashify wires three:

| Event              | Best use                                         |
|--------------------|--------------------------------------------------|
| `checkouts/create` | Abandoned cart recovery — send 30 min later      |
| `orders/paid`      | Order confirmation with tracking link            |
| `orders/cancelled` | "Order cancelled" notice with refund ETA         |

Each event gets its own template + variable mapping.

## Prerequisites

- Shopify store on any plan
- Shop admin access to create webhooks
- Approved WhatsApp templates in Splashify

## Setup

### 1. Copy the Splashify webhook URL

**Integrations → Shopify** in Splashify → copy URL:

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/shopify_marketing
```

### 2. Generate a webhook secret

Shopify lets you sign webhooks with a shared secret. Use any random 40+ character string — we recommend a UUID or `openssl rand -hex 32`. Keep it safe.

Paste the secret into Splashify's **Webhook Secret** field first — otherwise any signed requests will be rejected (signature mismatch) until you do.

### 3. Add webhooks in Shopify

Shopify admin → **Settings → Notifications → Webhooks** (or **Settings → Developer → Webhooks** on newer UIs) → scroll to the **Webhooks** section at the bottom.

For each event:

| Field   | Value                                           |
|---------|-------------------------------------------------|
| Event   | Choose `Checkout creation`, `Order payment`, or `Order cancellation` |
| Format  | JSON                                            |
| URL     | The URL from step 1 (same URL for all three)    |
| Version | 2024-01 or later                                |

Click **Save webhook**.

**Set the shared secret:** at the bottom of the webhooks section there's a **webhook signature** key. Shopify doesn't let you set this — it shows you a key that's auto-generated per shop. Copy this value and paste it into Splashify's **Webhook Secret** field instead of generating your own.

Splashify validates the signature as `HMAC-SHA256(rawBody, webhook_secret)` → base64 → compared to `X-Shopify-Hmac-Sha256`.

### 4. Pick templates per event in Splashify

**Configuration → Event Automations**:

1. **`checkouts/create`** — abandoned cart recovery
   - Phone field: `phone` (Shopify puts contact phone on the root)
   - Variables:

     | Var     | Field path        | Sample                      |
     |---------|-------------------|-----------------------------|
     | `{{1}}` | `customer.first_name` | `Priya`                 |
     | `{{2}}` | `total_price`     | `1299.00`                   |
     | `{{3}}` | `abandoned_checkout_url` | Shopify-hosted recovery link |

2. **`orders/paid`** — order confirmation
   - Phone field: `phone` or `customer.phone`
   - Variables: order name (`name`), total (`total_price`), tracking URL (`fulfillments[0].tracking_url` — note: array indexing not supported yet, use metadata or a flat field)

3. **`orders/cancelled`** — refund notice
   - Phone field: same as above
   - Variables: `name`, `total_price`, `cancel_reason`

4. Toggle **Enabled** → **Save**.

### 5. Test

Easiest: add a product to your cart on the store, go to checkout, fill in name + email + phone, then **abandon** the checkout (close the tab). Shopify fires `checkouts/create` within seconds.

Check **Integrations → Shopify → Logs**.

For `orders/paid` and `orders/cancelled`, place a real test order with a test payment gateway.

## Payload reference

Shopify sends the full checkout/order object directly (no wrapper) — Splashify passes it through unchanged.

Key fields on a checkout:

- `id`, `token`
- `email`, `phone`
- `customer.first_name`, `customer.last_name`, `customer.phone`
- `total_price`, `currency`
- `abandoned_checkout_url` — use this for recovery; Shopify hosts the page
- `line_items[]` — array of products (array indexing not yet supported in field paths)

On an order:

- `name` — e.g. `#1042`
- `order_status_url`, `order_number`
- `financial_status` — `paid` / `pending` / `refunded`
- `fulfillments[]` — tracking numbers, carrier

## Common gotchas

- **Phone required.** Shopify checkouts don't *require* a phone — if the customer skipped it, we log `phone_missing`. Require phone at checkout in **Settings → Customer accounts** to ensure coverage.
- **`abandoned_checkout_url` expires after ~2 hours.** Don't schedule recovery messages more than 90 minutes out.
- **Test orders count toward retries.** Each test places a real webhook — if the template isn't ready, deliverability still counts (but won't send since integration is disabled).
- **Shopify's signature key is per-shop, not per-webhook.** One secret covers all three webhooks.
- **Array fields don't work in variable paths.** Use `line_items.0.title`? No — only simple dot paths. Capture array summaries in Shopify's order metadata or in your fulfillment app.

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [Shopify webhooks docs →](https://shopify.dev/docs/apps/webhooks)


========================================================================
## Stripe
URL: https://docs.splashifypro.com/integrations/stripe
========================================================================

# Stripe

Stripe fires dozens of event types; Splashify wires the two that matter for customer messaging out of the box: `payment_intent.succeeded` and `payment_intent.payment_failed`. Signatures use Stripe's standard `t=…,v1=…` scheme.

## What you get

| Event                             | Typical template                    |
|-----------------------------------|-------------------------------------|
| `payment_intent.succeeded`        | Order confirmation with total + id  |
| `payment_intent.payment_failed`   | Payment failure + retry nudge       |

## Prerequisites

- Stripe account ([dashboard.stripe.com](https://dashboard.stripe.com))
- Approved WhatsApp templates in Splashify

## Setup

### 1. Copy the Splashify webhook URL

**Integrations → Stripe** in Splashify → copy URL:

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/stripe
```

### 2. Add the endpoint in Stripe

Stripe dashboard → **Developers → Webhooks → + Add endpoint**.

| Field              | Value                                                                 |
|--------------------|-----------------------------------------------------------------------|
| Endpoint URL       | URL from step 1                                                       |
| Description        | Splashify Pro WhatsApp templates                                      |
| Events to send     | `payment_intent.succeeded`, `payment_intent.payment_failed`           |

Click **Add endpoint**. On the next screen, click **Reveal** under **Signing secret** — it looks like `whsec_XXXXXXX...`. Copy it.

### 3. Paste the signing secret in Splashify

**Configuration** tab → **Webhook Secret** → paste the `whsec_…` value. Save.

From now on, any unsigned or wrongly-signed POST to your Stripe webhook URL is rejected with 401. Stripe retries its own webhook for up to 3 days on 5xx; it will stop retrying on a persistent 401.

### 4. Pick templates + map variables

For each event you care about, in **Event Automations**:

1. Pick the approved template.
2. Set **Phone Field** — where on the `payment_intent` is the customer phone?
   - If you collect phone via Stripe Checkout: `receipt_email` works for email but phone lives on `shipping.phone` or `charges.data[0].billing_details.phone`. Splashify only supports simple dot paths — the cleanest pattern is to **store the phone in metadata** when you create the PaymentIntent:
     ```js
     await stripe.paymentIntents.create({
       amount: 5000,
       currency: 'usd',
       metadata: { phone: '919876543210', order_id: 'ORD-123' },
     })
     ```
     Then set **Phone Field** → `metadata.phone`.
3. **Variable Mappings**:

| Template var | Field path             | Sample                 |
|--------------|------------------------|------------------------|
| `{{1}}`      | `amount`               | `5000` (in cents)      |
| `{{2}}`      | `currency`             | `usd`                  |
| `{{3}}`      | `id`                   | `pi_3N1abc...`         |
| `{{4}}`      | `metadata.order_id`    | `ORD-123`              |
| `{{5}}`      | `last_payment_error.message` | (failed events)  |

4. Toggle **Enabled** and **Save**.

### 5. Test

Stripe CLI:

```bash
stripe trigger payment_intent.succeeded
```

Or in the dashboard, on the webhook endpoint, click **Send test webhook** → pick the event.

Then check **Integrations → Stripe → Logs** in Splashify.

## Payload reference

Stripe wraps the event in `data.object` — Splashify unwraps this so you address the inner fields directly (`id`, `amount`, `metadata.xxx`, etc.).

Key fields on a `payment_intent`:

- `id` — `pi_...`
- `amount` — smallest currency unit (cents / paise)
- `currency` — lowercase ISO code (`usd`, `inr`)
- `status` — `succeeded` / `requires_payment_method` / etc.
- `metadata.*` — whatever you stored at creation
- `receipt_email`
- `last_payment_error.{code,message,decline_code}` — on failures

Full reference: [Stripe PaymentIntent object](https://stripe.com/docs/api/payment_intents/object).

## Common gotchas

- **Amounts are in the smallest unit.** `amount=5000` in USD means $50.00; in INR it means ₹50.00. Put currency formatting in the template text.
- **Phone field is rarely on the root.** Use `metadata.phone` and attach it at PaymentIntent creation — the cleanest long-term pattern.
- **Test-mode webhooks have placeholder data.** Use `stripe trigger` with real metadata, or run an end-to-end real charge in test mode.
- **Signature check fails on 1-char mismatch.** Copy the secret with no whitespace. If you rotate the secret in Stripe, update it here too.

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [Stripe webhooks docs →](https://stripe.com/docs/webhooks)


========================================================================
## Integrations Troubleshooting
URL: https://docs.splashifypro.com/integrations/troubleshooting
========================================================================

# Troubleshooting

Every inbound webhook — whether it resulted in a message or not — is captured in the **Logs** tab of each integration's detail page. Start there. The list below maps each status value to the likely cause and fix.

## Reading the audit log

Open **Integrations → &lt;vendor&gt; → Logs**. Each row shows:

- **Timestamp** — when the webhook arrived
- **Event type** — what the vendor said happened (`payment.captured`, `orders/paid`, etc.)
- **Event ID** — the vendor's own id for the event
- **Status** — the outcome (see below)
- **HTTP status** — what we returned to the vendor
- **Error message** — specific reason if status ≠ sent

Click a row to see the raw request body, the captured headers, and the upstream Interakt response.

## Status reference

### `sent` ✅

Everything worked. Message left your WABA for the recipient. Check delivery separately via **Messages** or **Broadcasts**.

**Note:** if the row has `sent without signature verification — configure webhook_secret to enable` in the error column, the event went out but was *unverified*. Anyone who discovers the webhook URL could forge a fake event. Configure `webhook_secret` to lock it down.

### `duplicate`

The same event (by event ID or content hash) came in within the last 7 days. We deduped and didn't resend. This is normal — vendors retry aggressively on timeouts / 5xxs, and we'd rather drop a duplicate than double-send.

**Fix:** nothing to do. If you're testing and want the same event to fire twice, change a field in the payload between attempts or wait 7 days.

### `signature_failed` 🔒

HMAC signature verification failed. The request was rejected with HTTP 401.

**Fix:**

1. Open **Configuration** → copy `webhook_secret` from Splashify
2. Open the vendor's webhook settings → verify the secret matches **character-for-character** (no trailing newline or whitespace)
3. If you rotated the secret on either side, update it on the other

If you want to accept unsigned requests (not recommended in production), clear `webhook_secret` — requests will come through as `unverified`.

### `config_missing`

The integration is enabled but something in the config is missing — usually a template name or phone field, or an event that has no automation mapped.

**Fix:** go to **Configuration**, ensure:

- Enabled toggle is on
- A template is picked for the specific event you want to fire on
- **Phone Field** is set to a valid path that exists in this payload

### `phone_missing`

The phone field resolved to an empty string. Either the vendor didn't send a phone, or your field path is wrong.

**Fix:**

1. Click the log row → expand the **Request body**
2. Find where the phone actually is in the JSON
3. Update **Phone Field** in Configuration to the correct dot path (e.g. `customer.phone`, `billing.mobile`, `metadata.phone`)

Common vendor-specific fixes:

- **Stripe** — store phone in `metadata.phone` at PaymentIntent creation
- **Shopify** — require phone at checkout in store settings
- **Freshdesk** — add a Phone custom field to your ticket form
- **PayPal** — pass phone as `custom_id` at order creation

### `send_failed`

We received the webhook, picked a template, resolved the phone — but the downstream Interakt send API returned an error.

**Fix:** click the row → look at **Send response**. Common causes:

- **Template not approved / paused** by Meta — re-submit it in **Templates**
- **WABA not connected** — complete WhatsApp setup first
- **Invalid phone format** — country code missing / wrong
- **Insufficient wallet balance** — recharge

### `skipped_event`

Multi-event integration received an event type you haven't configured an automation for. Not an error — it just means "we saw `order.paid` but you only mapped `order.created`, so we did nothing."

**Fix:** add an automation for the event in **Configuration → Event Automations** if you want a template to fire on it.

### `disabled`

Integration exists but the Enabled toggle is off. We stored the webhook but didn't process it.

**Fix:** toggle **Enabled** on in Configuration.

### `unverified` (in the error column, not as a status)

Appears alongside `sent` when `webhook_secret` is empty for a signature-capable integration (Razorpay / Stripe / Shopify / WooCommerce). Message went through but the request wasn't authenticated.

**Fix:** follow the vendor's guide to configure a webhook secret and paste it into the integration.

## "The vendor says the webhook succeeded but no log shows up"

Rare — means the request arrived but the Splashify DB write failed. Check:

1. **Apex URL** — are you POSTing to the exact URL Splashify gave you? Typos in `user_id` silently 200.
2. **Content-Type** — we expect `application/json`. Form-urlencoded bodies (some PayU / PayPal legacy configs) get rejected at parse time and log `bad_request`.
3. **Firewall / origin** — your server or proxy may be stripping headers we rely on (`X-Shopify-Topic`, `X-WC-Webhook-Topic`, `Stripe-Signature`).

## "I'm getting duplicate messages"

If you haven't set up `webhook_secret`, your URL could have been leaked and someone is replaying old events.

**Fix:**

1. Set `webhook_secret` on both ends
2. Delete and re-create the integration to get a fresh URL (in the future we'll support rotating without deleting)

## Still stuck?

- Re-check the [Overview](/integrations) for shared concepts
- Look at the vendor-specific page (e.g. [Razorpay](/integrations/razorpay), [Shopify](/integrations/shopify-marketing))
- File a ticket via **Support → Raise a Ticket** — include the **Log ID** from the audit log and we can look at the exact request

## Related

- [Integrations Overview](/integrations)


========================================================================
## WooCommerce
URL: https://docs.splashifypro.com/integrations/woocommerce
========================================================================

# WooCommerce

WooCommerce has a built-in webhook system you configure from the WordPress admin. Splashify wires the two most useful events:

| Event           | Typical template                       |
|-----------------|----------------------------------------|
| `order.created` | Order received confirmation            |
| `order.updated` | Status change (processing / shipped / refunded) |

## Prerequisites

- WordPress site with WooCommerce active
- WordPress admin (or shop manager) access
- Approved WhatsApp templates in Splashify

## Setup

### 1. Copy the Splashify webhook URL

**Integrations → WooCommerce** in Splashify → copy:

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/woocommerce
```

### 2. Create the webhooks in WooCommerce

WordPress admin → **WooCommerce → Settings → Advanced → Webhooks → Add webhook**.

Create **two** webhooks (one per topic):

**Webhook 1:**

| Field         | Value                                         |
|---------------|-----------------------------------------------|
| Name          | Splashify — Order Created                     |
| Status        | Active                                        |
| Topic         | Order created                                 |
| Delivery URL  | URL from step 1                               |
| Secret        | Generate a strong random string (32+ chars). **Keep for next step.** |
| API Version   | v3                                            |

**Webhook 2:**

| Field         | Value                                         |
|---------------|-----------------------------------------------|
| Name          | Splashify — Order Updated                     |
| Status        | Active                                        |
| Topic         | Order updated                                 |
| Delivery URL  | URL from step 1                               |
| Secret        | **Same secret as above**                      |
| API Version   | v3                                            |

Both webhooks **must share the same secret** since Splashify stores one secret per integration.

### 3. Paste secret + configure in Splashify

**Configuration** tab:

1. **Webhook Secret** → paste the random string from step 2.
2. **Event Automations** — for each event:

   **`order.created`**
   - Phone field: `billing.phone`
   - Variables:

     | Var     | Field path           | Sample              |
     |---------|----------------------|---------------------|
     | `{{1}}` | `billing.first_name` | `Arjun`             |
     | `{{2}}` | `number`             | `1042`              |
     | `{{3}}` | `total`              | `1299.00`           |
     | `{{4}}` | `currency`           | `INR`               |

   **`order.updated`**
   - Phone field: `billing.phone`
   - Variables — include `status` (`processing`, `completed`, `refunded`, etc.) so the message reflects the new state.

3. Toggle **Enabled** → **Save**.

### 4. Test

Place a test order on the storefront. WooCommerce fires both webhooks (`created` at checkout, `updated` when you mark it Processing in admin). Check **Integrations → WooCommerce → Logs**.

## Payload reference

WooCommerce sends the full order object directly. Key fields:

- `id`, `number` (customer-facing), `status` (`pending` / `processing` / `completed` / `cancelled` / `refunded`)
- `total`, `currency`, `payment_method_title`
- `billing.{first_name, last_name, email, phone, address_1, city, postcode}`
- `shipping.*` (same shape as billing)
- `line_items[]` (array — not addressable via field path yet)
- `date_created_gmt`, `date_modified_gmt`

Full reference: [WooCommerce REST API → Order properties](https://woocommerce.github.io/woocommerce-rest-api-docs/#order-properties).

## Common gotchas

- **Two webhooks, one secret.** If you use different secrets, one topic will always fail signature verify.
- **Event detection uses the `X-WC-Webhook-Topic` header.** Don't strip headers at a proxy (Cloudflare, load balancer) that sits between WordPress and Splashify.
- **Local/staging sites.** WooCommerce can't reach `https://apis.splashifypro.com` from a site that isn't on the public internet. Use a test order on a staging domain that's publicly reachable.
- **Delayed delivery.** WooCommerce can delay webhook delivery up to 5 minutes under load. That's a WordPress cron quirk. Install [WP Crontrol](https://wordpress.org/plugins/wp-crontrol/) to debug.

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [WooCommerce webhooks docs →](https://woocommerce.com/document/webhooks/)


========================================================================
## Xendit
URL: https://docs.splashifypro.com/integrations/xendit
========================================================================

# Xendit

## Setup

### 1. Copy the Splashify webhook URL

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/xendit
```

### 2. Configure in Xendit

[dashboard.xendit.co](https://dashboard.xendit.co) → **Settings → Webhooks**.

| Field                | Value                                   |
|----------------------|-----------------------------------------|
| Callback URL         | URL from step 1                         |
| Callback event       | `invoice.paid` (and/or `invoice.expired`) |
| Callback verification token | Generate a random string          |

### 3. Configure in Splashify

- **API Key** — paste the **Callback verification token** from Xendit (stored for future verification)
- **Phone Field** — `payer_phone` (for Invoices API) or `metadata.phone` if you passed it in at creation
- **Variables:**

  | Var     | Field path             | Sample            |
  |---------|------------------------|-------------------|
  | `{{1}}` | `payer_name`           | `Budi`            |
  | `{{2}}` | `amount`               | `150000` (IDR)    |
  | `{{3}}` | `currency`             | `IDR`             |
  | `{{4}}` | `external_id`          | Your order ref    |

- **Enabled** → **Save**.

## Gotchas

- **Phone often comes through only if you passed `payer_phone` at invoice creation.** Pass it explicitly to avoid `phone_missing` rows in the audit log.
- **Amount for IDR has no decimals.** Keep the template copy in line — e.g. `Rp{{2}}` works fine.

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [Xendit webhooks docs →](https://docs.xendit.co/api-reference/)


========================================================================
## Zapier
URL: https://docs.splashifypro.com/integrations/zapier
========================================================================

# Zapier

Zapier is the universal pivot — any event from 7000+ supported apps can fan out to Splashify with a single Zap step. No signing scheme (Zapier sends raw payloads); use the unique URL as your shared secret.

## Setup

### 1. Copy the Splashify webhook URL

**Integrations → Zapier** in Splashify → copy:

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/zapier
```

### 2. Build the Zap

[zapier.com](https://zapier.com) → **Create Zap**.

1. **Trigger** — pick any trigger app and event (e.g. New row in Google Sheets, New lead in Facebook Ads, New issue in GitHub).
2. **Action** — **Webhooks by Zapier → Custom Request**.
3. Configure:

   | Field        | Value                                         |
   |--------------|-----------------------------------------------|
   | Method       | POST                                          |
   | URL          | URL from step 1                               |
   | Data Pass-Through? | No                                      |
   | Data         | JSON object mapping fields you want in Splashify. Example: |

   ```json
   {
     "phone": "{{phone_from_trigger}}",
     "first_name": "{{first_name_from_trigger}}",
     "amount": "{{amount_from_trigger}}",
     "order_id": "{{id_from_trigger}}"
   }
   ```

   | Field         | Value                                        |
   |---------------|----------------------------------------------|
   | Unflatten     | Yes                                          |
   | Headers       | `Content-Type: application/json`             |
   | Basic Auth    | (leave empty)                                |

4. **Test Step** — Zapier fires a test request to Splashify. Keep that tab open.

### 3. Configure the integration in Splashify

**Configuration** tab:

- **Phone Field** → `phone` (or whatever key you used in the Zap's JSON body)
- **Variables** → map `{{1}}` to `first_name`, `{{2}}` to `amount`, etc.
- Toggle **Enabled** → **Save**.

### 4. Publish the Zap

Zapier → **Publish**. Going forward every matching trigger event fires your WhatsApp template.

## Use cases

- **Typeform submission → welcome message** — New form response → Splashify welcome template
- **Stripe payment in a different Stripe account** — If you have multi-account setups, one Stripe → Zapier → Splashify keeps the split clean without setting up our first-class Stripe integration
- **Google Sheets → reminder** — Add a row with phone + message → Splashify fires the template

## Gotchas

- **Zapier's free tier rate-limits you.** If you expect > 100 events/day, move to Pabbly Connect or Make for unlimited tasks.
- **JSON shape is yours to design.** Structure it to match Splashify's variable mapping — flat keys like `phone`, `name`, `amount` work best.
- **No event routing.** Every Zap-fired request is treated identically; use multiple integration slugs (one per scenario) if you need different templates per event type.

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [Zapier Webhooks docs →](https://zapier.com/apps/webhook/integrations)


========================================================================
## Zoho Payments
URL: https://docs.splashifypro.com/integrations/zoho
========================================================================

# Zoho Payments

Connect your Zoho Payments account so the chat composer's **₹** icon can issue real payment links and ship them to your customers as a beautiful interactive WhatsApp message — Pay Now button on top, your hosted Zoho checkout below.

> **API reference**: [zoho.com/in/payments/api/v1/payment-links](https://www.zoho.com/in/payments/api/v1/payment-links/#overview)

## What you get

| Event triggered by Zoho           | Splashify behaviour                                                |
|-----------------------------------|--------------------------------------------------------------------|
| Payment link **paid**             | Status flips to `paid` in real-time, contact's chat shows ✅, push notification |
| Payment link **expired** / cancel | Status updates everywhere, optional re-send via the Resend button  |

If you also use Zoho Billing for invoices, Splashify already wires that — this integration is **only** for the payment-link / payment-collection flow.

## Prerequisites

- Active **Zoho Payments** merchant account ([zoho.com/in/payments](https://www.zoho.com/in/payments))
- Completed merchant onboarding (KYC + bank verification) — payment links don't issue against an unverified account
- Splashify WABA connected (Dashboard shows *WABA connected*)

## Setup

### 1. Get your Zoho Payments **Account ID**

Zoho Payments dashboard → **Settings → API & Webhooks**. Copy the **Account ID** (also called `X-com-zoho-payments-accountsid`). It looks like a 14-digit number.

### 2. Create a Zoho Self-Client and get the OAuth triple

Zoho Payments uses Zoho's standard OAuth 2.0. Access tokens expire after 60 minutes — Splashify needs a long-lived **refresh token** so it can mint fresh access tokens automatically. The Self-Client flow gives you all three credentials. **Funds collected via these links go to YOUR bank, not ours — these credentials must be from your own Zoho account.**

1. Sign in to [api-console.zoho.com](https://api-console.zoho.com) with the same Zoho account that owns your Zoho Payments merchant.
2. Click **Add Client** → choose **Self Client**.
3. After creation, copy the **Client ID** and **Client Secret** from the Self Client dashboard. These are long-lived — no expiry.
4. Open the **Generate Code** tab. In the *Scope* field paste:
   ```
   ZohoPay.payments.CREATE,ZohoPay.payments.READ,ZohoPay.payments.UPDATE
   ```
   *Time Duration* = 10 minutes. *Scope Description* = anything (e.g. "Splashify Pro payment links"). Click **Create**.
5. A grant code appears (looks like `1000.xxxxxxxxxxxxxxxx.yyyyyyyyyyyy`). Copy it within 10 minutes — it expires.
6. Exchange the grant code for a **refresh token** via curl:
   ```bash
   curl -X POST 'https://accounts.zoho.in/oauth/v2/token' \
     -d 'grant_type=authorization_code' \
     -d 'client_id=<your-client-id>' \
     -d 'client_secret=<your-client-secret>' \
     -d 'redirect_uri=https://app.splashifypro.com/integrations/zoho/callback' \
     -d 'code=<the-grant-code-from-step-5>'
   ```
   The response is JSON containing `access_token` (1hr lifetime — discard) and `refresh_token` (long-lived — **save this**).

> Splashify stores your `refresh_token` encrypted in our database. We use it on every API call to mint a fresh `access_token` automatically — you don't have to repeat this exchange. Refreshed tokens are persisted back so the rotation is invisible to you.

### 3. Create a webhook secret

Zoho Payments dashboard → **Settings → Webhooks → + Add Webhook**.

| Field        | Value                                                   |
|--------------|---------------------------------------------------------|
| URL          | `https://apis.splashifypro.com/api/v1/webhooks/payments/zoho` |
| Events       | `payment_link.paid`, `payment_link.expired`, `payment_link.cancelled` |
| Auth method  | **HMAC** (recommended) or **Token**                     |
| Secret       | Generate a 32+ character random string. **Save this.**  |

Click **Save**.

### 4. Connect in Splashify

Open [Integrations → Zoho Payments](https://app.splashifypro.com/integrations/zoho).

| Field                       | What to paste                                              |
|-----------------------------|------------------------------------------------------------|
| Account ID                  | From step 1                                                |
| OAuth Client ID             | From step 2 (your Self-Client dashboard)                   |
| OAuth Client Secret         | From step 2 (your Self-Client dashboard)                   |
| OAuth Refresh Token         | From step 2 (the curl exchange response)                   |
| Webhook Verification Token  | The secret from step 3                                     |

Hit **Save Changes**. From this point on Splashify rotates the access token automatically using your refresh token. Funds collected via every link go straight into your Zoho merchant account / linked bank — Splashify never holds the money.

## Sending a payment link

Three ways:

### A. From the chat composer

In **Messages**, open any conversation. Tap the green **₹** icon next to the emoji button. Fill in:

- Amount (₹) — what you want to collect
- Reason / Description — shown to the customer on the Zoho checkout page
- Product (optional) — line-item name on the Zoho receipt
- Gateway — if you have multiple connected, pick **Zoho Payments**

Hit **Send payment link**. The platform creates the link via Zoho's `POST /paymentlinks` endpoint and ships an interactive WhatsApp message to the customer with a **Pay Now** button.

### B. From the Public API

```bash
curl -X POST 'https://apis.splashifypro.com/api/v1/app/payments/links' \
  -H 'Authorization: Bearer YOUR_APP_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "contact_phone": "919876543210",
    "contact_name": "Aditya",
    "amount": 500.00,
    "description": "Order #1234",
    "gateway": "zoho",
    "expires_in_hours": 168
  }'
```

Returns the `link_id`, `gateway_link_id` (Zoho's `paymentlink_id`), and the public `short_url`.

### C. As a default

Set Zoho Payments as your default gateway:

```bash
curl -X POST 'https://apis.splashifypro.com/api/v1/app/payments/default-gateway' \
  -H 'Authorization: Bearer YOUR_APP_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"gateway": "zoho"}'
```

After this every link created without an explicit `gateway` field uses Zoho.

## How the webhook works

Zoho POSTs to `/api/v1/webhooks/payments/zoho` with a signed payload. Splashify:

1. Reads the raw body before parsing.
2. Verifies `X-Zoho-Webhook-Signature` (HMAC-SHA256 over the body) against your stored secret. Falls back to `X-Zoho-Webhook-Token` equality if you set up token-mode auth.
3. Looks up the link by `payment_link.paymentlink_id` → resolves your `user_id`.
4. Idempotency-checks via the `event_id` → skips if already processed (Zoho retries on 5xx).
5. Updates the link status, denormalises into the listing tables, pushes a real-time `payment.received` event to your WebSocket so the chat UI flips to ✅ without a refresh.

Always 200s back to Zoho on signature pass — internal failures get logged but don't trigger Zoho's retry storm.

## Variables surfaced from Zoho payloads

When you build templates / chatbot flows on top of Zoho events:

| Variable                       | Source                                             |
|--------------------------------|----------------------------------------------------|
| `customer.phone_number`        | Customer phone (E.164)                             |
| `customer.name`                | Customer name                                      |
| `amount`                       | Collected amount (rupees)                          |
| `paymentlink_id`               | Zoho's paymentlink ID                              |
| `payment_id`                   | Zoho's transaction ID (when status = paid)         |
| `status`                       | `paid` / `expired` / `cancelled` / `refunded`      |

## Pricing

Zoho Payments charges per transaction (typically 2% UPI / 2.5-3% cards — check your contract). Splashify Pro doesn't add a markup on payment-collection — you keep 100% of what Zoho passes through after their cut.

WhatsApp message charges still apply to the interactive message we ship to your customer — see [Pricing](https://splashifypro.com/pricing).

## Troubleshooting

| Symptom                                         | Likely cause                                                              |
|-------------------------------------------------|---------------------------------------------------------------------------|
| `Gateway not configured` on link creation        | One of Account ID / Client ID / Client Secret / Refresh Token is empty on the integration form |
| `zoho 401: Not An Authorized User`               | Refresh token rejected by Zoho — re-run step 2 (the grant code may have expired before the curl exchange, or you used a different client_id when minting it) |
| `zoho oauth: invalid_client`                     | Client ID + Client Secret don't match the Self-Client that issued the refresh token. Re-paste them from the same Self-Client dashboard. |
| Webhook returns 400 `invalid signature`          | Stored webhook secret doesn't match what Zoho is signing with — regenerate |
| Customer gets a plain text message, not the CTA  | Conversation is past the 24h customer-service window — restart by sending a template |
| Payment captured but Splashify still shows pending | Webhook not configured / wrong URL — check Zoho dashboard logs             |

For anything else email `support@splashifypro.in`.


========================================================================
## Zoho Billing
URL: https://docs.splashifypro.com/integrations/zoho-billing
========================================================================

# Zoho Billing

Zoho Billing (formerly Zoho Subscriptions) fires webhooks for subscription creation, invoice payments, card expiry — great for SaaS customer lifecycle messaging.

## Setup

### 1. Copy the Splashify webhook URL

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/zoho_billing
```

### 2. Configure in Zoho Billing

[billing.zoho.com](https://billing.zoho.com) → **Settings → Automation → Webhooks → + New Webhook**.

| Field    | Value                                                 |
|----------|-------------------------------------------------------|
| URL      | URL from step 1                                       |
| Method   | POST                                                  |
| Events   | `invoice.thankyou` (paid), `subscription_activation`, `card_expiry_reminder`, etc. |

### 3. Configure in Splashify

Zoho Billing wraps the invoice/subscription in `data.{invoice,subscription}` — Splashify normalizes this so you address inner fields directly.

- **Phone Field** → `customer.mobile` (or wherever you stored phone on the customer record)
- Variables:

  | Var     | Field path            | Sample      |
  |---------|-----------------------|-------------|
  | `{{1}}` | `customer.first_name` | `Priya`     |
  | `{{2}}` | `invoice_number`      | `INV-0042`  |
  | `{{3}}` | `total`               | `599.00`    |

- **Enabled** → **Save**.

## Gotchas

- **Zoho Billing may send both data.invoice and data.customer** — Splashify flattens top-level sub-objects, but nested customer stays nested (`customer.mobile`).
- **Signature verification not yet wired.**

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [Zoho Billing webhooks →](https://www.zoho.com/billing/api/v1/webhooks/)


========================================================================
## Zoho CRM
URL: https://docs.splashifypro.com/integrations/zoho-crm
========================================================================

# Zoho CRM

Zoho CRM's workflow rules can fire webhooks on lead / contact / deal state transitions. Perfect for "thanks for the lead" auto-replies or "deal moved to X stage" notifications.

## Setup

### 1. Copy the Splashify webhook URL

```
https://apis.splashifypro.com/api/v1/webhooks/integrations/<your-user-id>/zoho_crm
```

### 2. Create a Zoho CRM workflow rule

[crm.zoho.com](https://crm.zoho.com) → **Setup → Workflow Rules → Create Rule**.

1. Module — **Leads** (or Contacts / Deals)
2. When to execute — on **Record Action → Create** (or edit, based on what you want)
3. Conditions — e.g. Lead Source = Website
4. **Actions → + Webhook**:

   | Field          | Value                                           |
   |----------------|-------------------------------------------------|
   | Name           | Splashify WhatsApp                              |
   | URL to Notify  | URL from step 1                                 |
   | Method         | POST                                            |
   | Module         | Leads                                           |
   | Body           | JSON. Map Zoho field → JSON key:                |

   ```json
   {
     "Phone": "${Leads.Phone}",
     "First_Name": "${Leads.First_Name}",
     "Lead_Source": "${Leads.Lead_Source}",
     "Company": "${Leads.Company}"
   }
   ```

5. Save the webhook + attach it to the rule.

### 3. Configure in Splashify

- **API Key / API Secret** — optional (for future 2-way sync)
- **Phone Field** → `Phone` (Zoho field names are capitalized)
- **Variables** — map `{{1}}` → `First_Name`, etc.
- **Enabled** → **Save**.

### 4. Test

Create a lead that matches your rule — webhook fires within 10 seconds.

## Gotchas

- **Zoho field names are case-sensitive.** `phone` won't match — use `Phone` as stored.
- **Two-way sync isn't implemented** — inbound webhook only. Contact updates in Splashify don't flow back to Zoho.
- **Signature verification not yet wired** for Zoho CRM.

## Related

- [Troubleshooting](/integrations/troubleshooting)
- [Zoho CRM webhooks docs →](https://www.zoho.com/crm/developer/docs/api/v2/webhooks.html)


========================================================================
## Public API Overview
URL: https://docs.splashifypro.com/public-api
========================================================================

# Public API Overview

The Splashify Pro Public API lets you trigger WhatsApp messages, send Meta Conversion API events, fetch your customer base, and assign live conversations to agents — all from your own backend.

You can call these endpoints as soon as a customer is created on your website / app, or wire them into your existing automation stack (Zapier, n8n, Make, your own cron job, anything that can POST JSON).

## Base URL

```
https://apis.splashifypro.com/api/v1/
```

All Public API endpoints sit under `/api/v1/public/` (and `/api/v1/app/meta-ads/capi/...` for the Conversions API).

## What you can do

| Group | Use case |
|-------|----------|
| **[Customer APIs](/public-api/get-users)** | Fetch your contact list with trait-level filtering (e.g. customers created after a given date) |
| **[Conversions API](/public-api/conversions-api)** | Forward Lead / Purchase / Subscribe events from your backend to Meta with the click-to-WhatsApp click ID we already store |
| **[Send Messages](/public-api/send-text)** | Send free-form text, image, video, audio, document, sticker, button, and list messages within the 24-hour customer service window |
| **[Send Templates](/public-api/send-template-no-header)** | Send any approved WhatsApp template — text/media/auth/dynamic CTA/carousel/order details — outside the 24-hour window |
| **[Chat Assignment](/public-api/chat-assignment)** | Programmatically assign an open conversation to a specific agent by their email |

## Quick start

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fullPhoneNumber": "919876543210",
    "callbackData": "order_12345",
    "type": "Text",
    "data": { "message": "Hello from the API!" }
  }'
```

```json
{
  "result": true,
  "message": "Message queued for sending via Splashify Pro. Check webhook for delivery status",
  "id": "d58aeff7-a81c-47a7-9b67-f381e13f6c4e"
}
```

The returned `id` is your handle on this message — use it to correlate with delivery webhooks (`message.sent`, `message.delivered`, `message.read`, `message.failed`) configured in **Settings → Developer**.

## Plan availability

Public APIs are available on **Growth**, **Advanced**, and **Enterprise** plans. They are **not** accessible on Starter.

See [Rate Limits](/public-api/rate-limits) for the per-plan request budgets.

## Where to next

1. **[Authentication](/public-api/authentication)** — generate your API key and set up the `Authorization` header.
2. **[Rate Limits](/public-api/rate-limits)** — what to expect at scale, plus retry strategy.
3. Pick the endpoint group that matches what you're building and copy the cURL sample.


========================================================================
## Authentication
URL: https://docs.splashifypro.com/public-api/authentication
========================================================================

# Authentication

Every Public API request uses HTTP **Basic** authentication with your Splashify Pro API key.

## Get your API key

1. Sign in to Splashify Pro.
2. Open **Settings → Developer**.
3. Click **Generate Secret Key**.
4. Copy the key — it is shown **only once**. Store it in your secrets manager.

If you lose the key, click **Regenerate Key** to mint a new one. The old key is invalidated instantly, so update every integration before you regenerate.

## Send the header

```
Authorization: Basic YOUR_API_KEY
Content-Type: application/json
```

The value is your raw API key — Splashify accepts it as-is, you do not need to base64-encode it the way "real" HTTP Basic does. The `Basic` prefix is required.

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

## Errors

| HTTP code | Cause |
|-----------|-------|
| `401 Unauthorized` | Header missing, key invalid, or key was regenerated |
| `403 Forbidden` | Key valid but the workspace is on a Starter plan (Public API not available), the WABA is suspended, or the request IP is not on the IP allowlist (`code: ip_blocked`) — see [Allowed IPs](/settings/allowed-ips) |
| `429 Too Many Requests` | Rate limit hit — see [Rate Limits](/public-api/rate-limits) |

## IP allowlisting

Workspaces on enterprise plans can restrict API calls to a list of trusted IPs. When enabled, requests from IPs not on the allowlist return:

```json
{
  "success": false,
  "code": "ip_blocked",
  "ip": "203.0.113.45",
  "message": "Access denied — your IP address is not on this account's allowlist."
}
```

The block is enforced on the public API surface (`sk_live_…` Bearer, GraphQL Bearer, SMTP relay) but not on webhook receivers. Account owners get an email alert the first time each new IP is blocked. See [Allowed IPs](/settings/allowed-ips) for full setup.

## Security checklist

- **Never put the API key in client-side code** (web, mobile, anywhere a user can open DevTools). Always call from your backend.
- **Rotate** the key on team turnover or any suspected leak.
- **Scope** integrations: each integration should call only the endpoints it needs. There is no per-key scoping yet — separation is by which integration holds the key.
- **Never log** the full key. Truncate to the last 4 characters in logs.


========================================================================
## Chat Assignment
URL: https://docs.splashifypro.com/public-api/chat-assignment
========================================================================

# Chat Assignment

Assign an open conversation to a specific agent by their email. Useful when your routing logic lives outside Splashify — e.g. you decide assignment based on CRM ownership, language preference, or an external scheduling system, and just want to push the result back into Splashify so the agent gets the conversation in their inbox.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/assignment/
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "user_phone_number": "919876543210",
  "agent_email": "test.agent@interakt.ai"
}
```

| Field               | Required | Notes |
|---------------------|----------|-------|
| `user_phone_number` | yes      | The customer's phone in **country-code + number** format with no `+` and no special characters. E.g. `+91 9876543210` → `919876543210` |
| `agent_email`       | yes      | Email of the agent in your Splashify workspace. The agent must already exist as a team member |

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/assignment/ \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_phone_number": "919876543210",
    "agent_email": "test.agent@interakt.ai"
  }'
```

## Successful response — `200 OK`

```json
{
  "result": true,
  "message": "Chat Assigned Successfully"
}
```

## Error response — `400 Bad Request`

```json
{
  "result": false,
  "message": "Error_Message"
}
```

The `message` field carries the actual reason — common ones:

- `Agent not found` — the email doesn't match any team member.
- `Conversation not found` — no open conversation exists for that phone number. The contact may need to message your WABA first.
- `Agent inactive` — the team member exists but their access is disabled.

## Status codes

| Code | Meaning |
|------|---------|
| `200 OK` | Conversation assigned |
| `400 Bad Request` | Malformed payload, missing fields, agent not found |
| `401 Unauthorized` | API key invalid or missing |
| `500 Internal Server Error` | Unexpected error — retry with backoff |

## Implementation tips

- **Normalize phone numbers** at the boundary — strip `+`, spaces, dashes, parentheses before sending. The validator only accepts pure digits.
- **Check the agent is active** in Splashify (Settings → Team) before sending — a deactivated agent won't accept assignment.
- **Idempotent** — re-assigning to the same agent is a no-op.
- Pair with the **inbound webhook** (`message.received`) on your side: when a new conversation opens, look up the customer in your CRM, decide the right agent, then call this endpoint.


========================================================================
## Conversions API (Meta CAPI)
URL: https://docs.splashifypro.com/public-api/conversions-api
========================================================================

# Conversions API (Meta CAPI)

When a customer clicks a Click-to-WhatsApp ad, Meta sends us their `ctwa_clid` in the WhatsApp webhook and we store it on the conversation. The Conversions API endpoint lets your backend fire a Meta Conversion API event (Lead, Subscribe, Purchase, AddToCart, etc.) using that `ctwa_clid` so Meta can attribute the conversion back to the original ad — no Pixel cookie required.

This is the right tool for **server-side conversion tracking** of customers who came in through a CTWA ad and converted later via your own checkout, CRM, or subscription flow.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/app/meta-ads/capi/send-event
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

| Field          | Required                                  | Description |
|----------------|-------------------------------------------|-------------|
| `event_name`   | yes                                       | Standard Meta event name — `Lead`, `Subscribe`, `Purchase`, `AddToCart`, `CompleteRegistration`, `InitiateCheckout`, `ViewContent` |
| `phone_number` | yes                                       | E.164 phone (e.g. `+919876543210`) — must match a contact whose conversation has a stored `ctwa_clid` |
| `currency`     | required for Purchase / Subscribe         | ISO 4217, e.g. `INR`, `USD` |
| `value`        | required for Purchase / Subscribe         | Numeric value of the conversion |

We hash PII (email, phone) on the server before forwarding to Meta — your backend only ships plaintext to us, the Pixel never sees it.

## Lead event

```bash
curl -X POST https://apis.splashifypro.com/api/v1/app/meta-ads/capi/send-event \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "Lead",
    "phone_number": "+919876543210"
  }'
```

## Purchase event

Use this on order-paid in your backend so Meta records the actual purchase value against the originating ad:

```bash
curl -X POST https://apis.splashifypro.com/api/v1/app/meta-ads/capi/send-event \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "Purchase",
    "phone_number": "+919876543210",
    "currency": "INR",
    "value": 1499.00
  }'
```

## Successful response — `200 OK`

```json
{
  "success": true,
  "event_name": "Purchase",
  "ctwa_clid": "ARAkLkA8rmlFei..."
}
```

The returned `ctwa_clid` is the click ID we attached the event to. If the contact came through more than one CTWA ad, we use the most recent click.

## When the contact is not a CTWA conversion

If we don't have a `ctwa_clid` stored for this phone number (e.g. the customer reached you organically), the call returns:

```json
{
  "success": false,
  "reason": "no_ctwa_click_id_for_phone"
}
```

This is **not** an error — it just means there's no ad to attribute the conversion to, so nothing is sent to Meta. Your backend can safely treat this as a no-op.

## Implementation notes

- Send `Lead` immediately when the customer takes a qualifying action (form fill, demo booking).
- Send `Purchase` on payment success only — Meta penalizes duplicate or pending events.
- Combine with **Pixel**-side events on your website for full deduplication. Meta dedups by `event_id`; if you want explicit dedup, generate a UUID v4 client-side, send it as an `eventID` to Pixel and as `event_id` here (this endpoint accepts it as an optional field).


========================================================================
## Get Users
URL: https://docs.splashifypro.com/public-api/get-users
========================================================================

# Get Users

Fetch the contacts in your Splashify workspace with arbitrary trait-level filters and pagination. Useful for syncing Splashify customers back into your data warehouse, building a custom segment outside the app, or auditing who you've imported.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/apis/users/?offset=0&limit=100
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Query parameters

| Param    | Type | Default | Notes |
|----------|------|---------|-------|
| `offset` | int  | 0       | Number of customers to skip — use for pagination |
| `limit`  | int  | 100     | Page size, max 100 |

## Request body

The request body is a list of trait filters. Each filter targets a single trait (`created_at_utc`, `email`, `phone_number`, anything you've stored) and applies a comparison operator.

```json
{
  "filters": [
    {
      "trait": "created_at_utc",
      "op": "gt",
      "val": "2021-09-08T11:35:47.089Z"
    },
    {
      "trait": "created_at_utc",
      "op": "lt",
      "supr_op": "and",
      "val": "2021-09-08T11:40:47.089Z"
    }
  ]
}
```

| Field      | Required                       | Description |
|------------|--------------------------------|-------------|
| `trait`    | yes                            | The trait name to filter on |
| `op`       | yes                            | Comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `in` |
| `val`      | yes                            | The value to compare against. ISO 8601 strings for timestamps, numbers, plain strings, or arrays for `in` |
| `supr_op`  | required for filters 2..N      | Combinator with the previous filter — `and` or `or` |

The first filter in the list does not need `supr_op`; every subsequent filter does.

## Example

```bash
curl -X POST 'https://apis.splashifypro.com/api/v1/public/apis/users/?offset=0&limit=100' \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {
        "trait": "created_at_utc",
        "op": "gt",
        "val": "2021-09-08T11:35:47.089Z"
      },
      {
        "trait": "created_at_utc",
        "op": "lt",
        "supr_op": "and",
        "val": "2021-09-08T11:40:47.089Z"
      }
    ]
  }'
```

## Successful response — `200 OK`

```json
{
  "result": true,
  "message": "Customers",
  "data": {
    "total_customers": 1,
    "offset": 0,
    "limit": 100,
    "has_next_page": false,
    "customers": [
      {
        "id": "a537a43e-49b7-4306-9763-6a97417de0bb",
        "created_at_utc": "2021-08-27T08:48:02.970000",
        "modified_at_utc": "2021-08-27T08:48:03.112000",
        "phone_number": "9999999999",
        "country_code": "+376",
        "user_id": "",
        "traits": {
          "name": "John Doe",
          "email": null,
          "whatsapp_opted_in": true,
          "total_orders_count": 1,
          "last_order_id": 3993626378418,
          "last_order_name": "#1025",
          "total_spent": "7080.00",
          "address": {
            "address1": "abc",
            "address2": "test",
            "city": "Pune",
            "state": "Maharashtra",
            "country": "India",
            "zip_code": "411002"
          },
          "created_at": "2021-08-27T08:47:56",
          "currency": "INR",
          "first_name": "John",
          "last_name": "Doe"
        },
        "customer_created_at_source": "Shopify"
      }
    ]
  }
}
```

| Field                          | Description |
|--------------------------------|-------------|
| `data.total_customers`         | Total number of customers matching your filter — use to build pagination UI |
| `data.has_next_page`           | `true` while more pages remain. Increment `offset` by `limit` until this becomes `false` |
| `data.customers[].id`          | Splashify-internal customer UUID |
| `data.customers[].traits`      | Free-form key/value bag of traits — every event you've sent us is reflected here |
| `customer_created_at_source`   | Which source created the contact (Shopify, manual import, API, etc.) |

## Pagination loop

```js
let offset = 0;
const pageSize = 100;
while (true) {
  const r = await fetch(
    `https://apis.splashifypro.com/api/v1/public/apis/users/?offset=${offset}&limit=${pageSize}`,
    { method: 'POST', headers, body: JSON.stringify({ filters: [] }) }
  ).then(r => r.json());
  for (const c of r.data.customers) await ingest(c);
  if (!r.data.has_next_page) break;
  offset += pageSize;
}
```


========================================================================
## GraphQL API
URL: https://docs.splashifypro.com/public-api/graphql
========================================================================

# GraphQL API

Splashify Pro exposes a **GraphQL endpoint** alongside the REST API. Use it when you want to:

- Fetch nested data in one round-trip (e.g. last 10 messages + the contact's tags + the broadcast they came from)
- Subscribe to real-time events over WebSocket (message received, broadcast progress, payment received)
- Build a custom dashboard / CRM integration without making 5–10 REST calls per page load

REST is still recommended for simple "send one message" flows. GraphQL shines for read-heavy integrations.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/graphql
```

## Authentication

Same as REST — pass your `sk_live_…` API key in the `Authorization` header:

```bash
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxx
```

> Get your API key from **Settings → Developer → Generate Secret Key** (shown once, regenerate invalidates the old one).

## Quick example

Fetch your wallet balance + last 5 broadcasts:

```bash
curl -X POST 'https://apis.splashifypro.com/api/v1/graphql' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "query Dashboard { wallet { balance currency } broadcasts(page: { limit: 5 }) { edges { id name status sent_count delivered_count } } }"
  }'
```

Response:

```json
{
  "data": {
    "wallet": { "balance": 12345.67, "currency": "INR" },
    "broadcasts": {
      "edges": [
        { "id": "uuid", "name": "Diwali sale", "status": "completed", "sent_count": 1200, "delivered_count": 1187 },
        ...
      ]
    }
  }
}
```

## Schema overview

### Queries (read)

| Type | Examples |
|--|--|
| `me` | Your account, plan, wallet balance |
| `contact(id)` / `contacts(filter)` | Single contact or filtered list with pagination |
| `conversation(id)` / `conversations(filter)` | Conversations with assignee + last message |
| `messages(conversationId)` | Paginated message history |
| `template(id)` / `templates(status, category)` | Approved/pending templates |
| `broadcast(id)` / `broadcasts(filter)` | Broadcasts + progress counters |
| `broadcastReport(id)` | Per-recipient delivery breakdown |
| `wallet` / `walletTransactions` | Balance + ledger |
| `call(id)` / `calls(filter)` | WhatsApp Business calls + recordings |

### Mutations (write) — currently shipped

| Mutation | Purpose |
|--|--|
| `sendText(input: SendTextInput!)` | Send a plain WhatsApp text message → returns `SendResult { message_id, status }` |
| `createContact(input: CreateContactInput!)` | Idempotent — returns existing contact if phone already saved |
| `addTags(contactId: ID!, tags: [String!]!)` | Append + dedupe tags |
| `removeTags(contactId: ID!, tags: [String!]!)` | Remove a subset of tags |
| `assignConversation(conversationId: ID!, agentEmail: String!)` | Pass empty string to unassign |
| `resolveConversation(conversationId: ID!)` | Marks status='resolved' |

#### Coming soon (Phase 2.x roadmap)

| Mutation | Status |
|--|--|
| `sendTemplate` / `sendMedia` / `sendInteractive` | In progress — wraps existing handler logic |
| `createBroadcast` / `cancelBroadcast` | After messaging mutations land |
| `createPaymentLink` | Reuses the chat composer ₹ icon flow |

#### Example — send a text message

```bash
curl -X POST 'https://apis.splashifypro.com/api/v1/graphql' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "mutation Send($input: SendTextInput!) { sendText(input: $input) { message_id status } }",
    "variables": { "input": { "to": "919876543210", "text": "Hello from GraphQL!" } }
  }'
```

#### Example — add tags to a contact

```bash
curl -X POST 'https://apis.splashifypro.com/api/v1/graphql' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "mutation Tag { addTags(contactId: \"<uuid>\", tags: [\"vip\", \"q4-promo\"]) { contact_id name tags } }"
  }'
```

### Subscriptions (real-time over WebSocket)

| Subscription | Fires when |
|--|--|
| `messageReceived(conversationId)` | New inbound message in the conversation (or any if id omitted) |
| `messageStatusUpdated` | Sent → delivered → read transitions |
| `broadcastProgress(broadcastId)` | Sent/delivered/failed counters bump |
| `paymentReceived` | Customer paid a payment-link |

WebSocket endpoint: `wss://apis.splashifypro.com/api/v1/graphql` (same URL, upgraded protocol). Authenticate via the `connection_init` payload:

```json
{ "type": "connection_init", "payload": { "Authorization": "Bearer sk_live_..." } }
```

## Pagination

All `connection`-style queries use cursor-based pagination:

```graphql
contacts(page: { limit: 50, cursor: "<from prev page>" }) {
  edges { id name phone }
  pageInfo { hasNextPage endCursor }
}
```

## Error handling

GraphQL never returns a non-200 HTTP status (except for auth/network errors). Check the `errors` array in the response:

```json
{
  "data": null,
  "errors": [
    { "message": "rate limit exceeded", "extensions": { "code": "RATE_LIMITED", "retry_after_sec": 60 } }
  ]
}
```

| Code | Meaning | Fix |
|--|--|--|
| `UNAUTHENTICATED` | API key missing/invalid | Check Authorization header |
| `RATE_LIMITED` | Plan rate limit hit | Backoff per `retry_after_sec` |
| `QUERY_TOO_EXPENSIVE` | Query complexity > 1000 | Reduce nesting or use pagination |
| `NOT_FOUND` | Resource doesn't exist | Verify the ID |
| `VALIDATION_ERROR` | Input shape wrong | Check the field marked in `path` |
| `FEATURE_LOCKED` | Plan doesn't include this feature | Upgrade plan |

## Rate limits

GraphQL **shares the same per-plan rate limit bucket** as REST. Mixed REST + GraphQL traffic counts toward the same quota.

| Plan | Limit |
|--|--|
| Growth | 300 req/min |
| Advanced | 600 req/min |
| Enterprise | configurable, up to Meta WABA cap |

Each GraphQL query is also limited by **complexity score** (max 1000). Roughly: each field = 1 point, each `connection { edges }` = N × child cost where N is the page limit. Keep queries focused.

## GraphQL Playground

For schema exploration + ad-hoc queries, use the in-browser playground:

```
https://apis.splashifypro.com/graphql/playground
```

Sign in with your API key (top-right "HTTP Headers" panel) to start exploring.

## Compared to AiSensy / Wati

| Feature | Splashify Pro | AiSensy | Wati |
|--|--|--|--|
| REST API | ✓ | ✓ | ✓ |
| GraphQL API | ✓ | ✗ | ✗ |
| Real-time subscriptions | ✓ (over WS) | ✗ | webhooks only |
| Single-request nested fetches | ✓ | ✗ | ✗ |
| Same auth as REST | ✓ | — | — |

## Need help?

- Slack-style developer chat: `support@splashifypro.in`
- Live SLA: 24h for Growth, 8h for Advanced, 2h for Enterprise
- Schema: introspect via standard GraphQL `{ __schema { types { name } } }` query


========================================================================
## Rate Limits
URL: https://docs.splashifypro.com/public-api/rate-limits
========================================================================

# Rate Limits

Each plan ships with its own request budget. When you exceed it, the API returns `429 Too Many Requests` with the message `Rate limit exceeded for this resource`.

## Limits by plan

| Plan        | Rate limit                                  |
|-------------|---------------------------------------------|
| Growth      | 300 requests / minute                       |
| Advanced    | 600 requests / minute                       |
| Enterprise  | Configurable — capped at Meta's allowed rate |

> Public APIs are **not available** on the Starter plan. Upgrade to Growth or higher to call any endpoint in this section.

## Retry strategy

When you receive a `429`, retry with **exponential backoff**:

```js
async function callWithRetry(req, attempt = 0) {
  const resp = await fetch(url, req);
  if (resp.status !== 429) return resp;
  if (attempt >= 5) throw new Error('rate-limit retries exhausted');
  const delay = Math.min(1000 * 2 ** attempt, 30000);  // 1s, 2s, 4s, 8s, 16s, max 30s
  await new Promise(r => setTimeout(r, delay));
  return callWithRetry(req, attempt + 1);
}
```

Tips:

- **Spread bursts** — instead of firing 300 requests in the first second of every minute, even out the load.
- **Use broadcasts** for one-to-many sends. A 50,000-recipient campaign through `/app/broadcasts` uses one API call; the same campaign as 50,000 individual `/public/message` calls will exceed your budget.
- **Persist the message `id`** so retries idempotently reference the same logical message.

## What counts toward the limit

Every authenticated request to `/api/v1/public/*` (and the CAPI endpoint `/api/v1/app/meta-ads/capi/send-event`) counts. The rate limit is per workspace, not per API key — regenerating a key does not reset the counter.

## Beyond the limit

If you genuinely need more than 600 req/min sustained, talk to your account manager about Enterprise. The ceiling there is Meta's WABA messaging cap — typically the messaging tier (TIER_1K → TIER_UNLIMITED) on your phone number.


========================================================================
## Official SDKs
URL: https://docs.splashifypro.com/public-api/sdks
========================================================================

# Official SDKs

Splashify Pro publishes official SDKs for the three most-used backend languages. Each is **auto-generated from our OpenAPI 3.0 spec** so they're always in sync with the API — no drift, no out-of-date method signatures.

| Language | Package | Install |
|--|--|--|
| **Node.js / TypeScript** | [`@splashifypro/sdk`](https://www.npmjs.com/package/@splashifypro/sdk) | `npm install @splashifypro/sdk` |
| **Python** | [`splashifypro`](https://pypi.org/project/splashifypro) | `pip install splashifypro` |
| **PHP** | [`splashifypro/sdk`](https://packagist.org/packages/splashifypro/sdk) | `composer require splashifypro/sdk` |

All SDKs share:

- ✓ Full type definitions (TypeScript types, Python type hints, PHP PHPDoc)
- ✓ Async/await primitives idiomatic to each language
- ✓ Automatic retry on 5xx with exponential backoff
- ✓ Built-in webhook signature verification helpers
- ✓ Rate-limit aware (parses `Retry-After` automatically)
- ✓ Consistent error class hierarchy across languages

## Why use the SDK?

| Without SDK | With SDK |
|--|--|
| Read 30 docs pages, hand-build curl requests, parse JSON manually | `await splashify.messages.sendText({ to, text })` |
| Hard-code API URL versions, break on upgrades | SDK targets a stable API version, follows our compatibility policy |
| Roll your own retry/backoff logic | Built in |
| Manually verify webhook signatures with HMAC | `splashify.webhooks.verify(body, headers)` |

## Quickstart by language

### Node.js / TypeScript

```typescript

const splashify = new Splashify({ apiKey: process.env.SPLASHIFY_API_KEY });

// Send a WhatsApp text message
const result = await splashify.messages.sendText({
  to: '919876543210',
  text: 'Hello from Splashify Pro!',
});

console.log('Sent:', result.messageId);
```

[Full Node.js docs →](/public-api/sdks/nodejs)

### Python

```python
from splashifypro import Splashify

splashify = Splashify(api_key=os.environ["SPLASHIFY_API_KEY"])

# Send a WhatsApp text message
result = splashify.messages.send_text(
    to="919876543210",
    text="Hello from Splashify Pro!",
)

print(f"Sent: {result.message_id}")
```

[Full Python docs →](/public-api/sdks/python)

### PHP

```php
use Splashifypro\Splashify;

$splashify = new Splashify(['api_key' => getenv('SPLASHIFY_API_KEY')]);

$result = $splashify->messages->sendText([
    'to' => '919876543210',
    'text' => 'Hello from Splashify Pro!',
]);

echo "Sent: {$result->messageId}\n";
```

[Full PHP docs →](/public-api/sdks/php)

## What's in every SDK

All three SDKs cover the full Public API surface:

- **Messaging** — sendText, sendTemplate, sendMedia, sendInteractive (button/list/cta_url), sendLocation, sendContact
- **Conversations** — list, get, assign, resolve, send read receipts
- **Contacts** — create, update, delete, list (filters + pagination), addTags, blockContact
- **Templates** — list, sync from Meta, send
- **Broadcasts** — create, get, cancel, listMessages, broadcastReport
- **Calling** — initiate WhatsApp Business call, listCalls, getCall (with recording URL)
- **Payment Links** — create, list, get, cancel, sendReceipt
- **Email** — sendEmail, sendTemplateEmail (Splashify Pro email-marketing add-on)
- **Webhooks** — verifySignature helper for inbound webhooks
- **Wallet** — getWallet, listTransactions

## Versioning + backward compatibility

- SDK major versions track our API major versions (`@splashifypro/sdk@1.x` ↔ API v1).
- Method names + signatures are stable within a major version.
- New endpoints are added in minor versions (no breaking changes).
- Removed endpoints get a 6-month deprecation window with a clear console warning.

## Auto-publish pipeline

When the backend ships a new release tag (e.g. `v1.45.0`):

1. CI regenerates the OpenAPI spec from annotated handlers
2. SDK generators run for all three languages
3. Version is bumped (`1.45.0` everywhere)
4. Packages publish automatically to npm, PyPI, Packagist
5. Changelog gets posted to docs.splashifypro.com/changelog

You'll never have to wait for "the SDK to catch up" — it's literally generated from the same source as the API.

## Comparison vs AiSensy / Wati

| Feature | Splashify Pro | AiSensy | Wati |
|--|--|--|--|
| Official Node SDK | ✓ | ✗ | ✗ |
| Official Python SDK | ✓ | ✗ | ✗ |
| Official PHP SDK | ✓ | ✗ | ✗ |
| Auto-generated from OpenAPI | ✓ | n/a | n/a |
| Type definitions | ✓ | n/a | n/a |
| Webhook signature helpers | ✓ | ✗ | ✗ |
| < 10 LOC quickstart | ✓ | ~30 LOC curl | ~30 LOC curl |

## Need help?

- GitHub issues per SDK: `github.com/splashifypro/sdk-node`, `sdk-python`, `sdk-php`
- Email: `support@splashifypro.in`
- Stack Overflow tag: `splashifypro`


========================================================================
## Node.js SDK
URL: https://docs.splashifypro.com/public-api/sdks/nodejs
========================================================================

# Node.js SDK

Official Splashify Pro SDK for Node.js (works with TypeScript out of the box).

**Package:** [`@splashifypro/sdk`](https://www.npmjs.com/package/@splashifypro/sdk)

## Install

```bash
npm install @splashifypro/sdk
# or
yarn add @splashifypro/sdk
# or
pnpm add @splashifypro/sdk
```

Requires Node 18+ (uses native `fetch`).

## Configure

Get your API key from **Settings → Developer → Generate Secret Key**.

```typescript

const splashify = new Splashify({
  apiKey: process.env.SPLASHIFY_API_KEY!,
  // optional:
  baseUrl: 'https://apis.splashifypro.com', // override for testing
  timeout: 30_000,                            // ms, default 30s
  retries: 3,                                 // 5xx auto-retry with backoff
});
```

## First message — under 10 lines

```typescript

const splashify = new Splashify({ apiKey: process.env.SPLASHIFY_API_KEY! });

const result = await splashify.messages.sendText({
  to: '919876543210',
  text: 'Hello from Splashify Pro!',
});

console.log('Sent:', result.messageId);
```

## Common patterns

### Send a template

```typescript
await splashify.messages.sendTemplate({
  to: '919876543210',
  templateName: 'order_confirmation',
  language: 'en',
  bodyParameters: ['Aditya', '#1234', '₹2,499'],
});
```

### Send media

```typescript
await splashify.messages.sendMedia({
  to: '919876543210',
  type: 'image',
  mediaUrl: 'https://your-cdn.com/photo.jpg',
  caption: 'Check this out!',
});
```

### Create a broadcast

```typescript
const broadcast = await splashify.broadcasts.create({
  name: 'Diwali sale',
  templateName: 'diwali_offer_v1',
  language: 'en',
  audienceType: 'segments',
  segmentIds: ['<segment-uuid>'],
  scheduledAt: null, // send immediately
});

console.log('Broadcast', broadcast.id, 'queued');

// Poll progress
const report = await splashify.broadcasts.report(broadcast.id);
console.log(`${report.sent}/${report.total} sent`);
```

### List contacts with pagination

```typescript
let cursor: string | null = null;
do {
  const page = await splashify.contacts.list({ limit: 100, cursor });
  for (const c of page.edges) {
    console.log(c.phone, c.name);
  }
  cursor = page.pageInfo.hasNextPage ? page.pageInfo.endCursor : null;
} while (cursor);
```

### Verify a webhook

```typescript

app.post('/splashify/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const isValid = splashify.webhooks.verify({
    rawBody: req.body,
    signature: req.headers['x-splashify-signature'] as string,
  });
  if (!isValid) return res.status(401).end();

  const event = JSON.parse(req.body.toString());
  console.log('Event:', event.type, event.payload);
  res.status(200).end();
});
```

## Error handling

The SDK throws typed errors:

```typescript

try {
  await splashify.messages.sendText({ to: '919876543210', text: 'Hi' });
} catch (err) {
  if (err instanceof SplashifyRateLimitError) {
    console.log(`Rate limited, retry after ${err.retryAfterSec}s`);
  } else if (err instanceof SplashifyError) {
    console.error(`API error ${err.code}: ${err.message}`);
  } else {
    throw err; // network / unexpected
  }
}
```

| Error class | When |
|--|--|
| `SplashifyError` | Base — any 4xx/5xx with parsed body |
| `SplashifyRateLimitError` | 429 — has `retryAfterSec` |
| `SplashifyAuthError` | 401 — invalid API key |
| `SplashifyValidationError` | 400 — has `field` + `reason` |
| `SplashifyNotFoundError` | 404 — resource doesn't exist |

## TypeScript types

Every method has full input + output types — no need to consult the docs once you've installed:

```typescript

```

Auto-completion works in VS Code, IntelliJ, Vim/Neovim with TypeScript LSP.

## Source + issues

- npm: https://www.npmjs.com/package/@splashifypro/sdk
- GitHub: https://github.com/splashifypro/sdk-node
- Issues: file at the GitHub repo above; we triage daily


========================================================================
## PHP SDK
URL: https://docs.splashifypro.com/public-api/sdks/php
========================================================================

# PHP SDK

Official Splashify Pro SDK for PHP. Built on Guzzle for HTTP, fully PSR-4 autoloaded, framework-agnostic.

**Package:** [`splashifypro/sdk`](https://packagist.org/packages/splashifypro/sdk)

## Install

```bash
composer require splashifypro/sdk
```

Requires PHP 8.1+ + ext-curl + ext-json.

## Configure

```php
use Splashifypro\Splashify;

$splashify = new Splashify([
    'api_key' => getenv('SPLASHIFY_API_KEY'),
    // optional:
    'base_url' => 'https://apis.splashifypro.com',
    'timeout'  => 30,        // seconds
    'retries'  => 3,         // 5xx auto-retry with backoff
]);
```

## First message — under 10 lines

```php
<?php
require 'vendor/autoload.php';

use Splashifypro\Splashify;

$splashify = new Splashify(['api_key' => getenv('SPLASHIFY_API_KEY')]);

$result = $splashify->messages->sendText([
    'to' => '919876543210',
    'text' => 'Hello from Splashify Pro!',
]);

echo "Sent: {$result->messageId}\n";
```

## Common patterns

### Send a template

```php
$splashify->messages->sendTemplate([
    'to' => '919876543210',
    'templateName' => 'order_confirmation',
    'language' => 'en',
    'bodyParameters' => ['Aditya', '#1234', '₹2,499'],
]);
```

### Send media

```php
$splashify->messages->sendMedia([
    'to' => '919876543210',
    'type' => 'image',
    'mediaUrl' => 'https://your-cdn.com/photo.jpg',
    'caption' => 'Check this out!',
]);
```

### Create a broadcast

```php
$broadcast = $splashify->broadcasts->create([
    'name' => 'Diwali sale',
    'templateName' => 'diwali_offer_v1',
    'language' => 'en',
    'audienceType' => 'segments',
    'segmentIds' => ['<segment-uuid>'],
]);

echo "Broadcast {$broadcast->id} queued\n";

$report = $splashify->broadcasts->report($broadcast->id);
echo "{$report->sent}/{$report->total} sent\n";
```

### List contacts with pagination

```php
$cursor = null;
do {
    $page = $splashify->contacts->list(['limit' => 100, 'cursor' => $cursor]);
    foreach ($page->edges as $c) {
        echo "{$c->phone}\t{$c->name}\n";
    }
    $cursor = $page->pageInfo->hasNextPage ? $page->pageInfo->endCursor : null;
} while ($cursor !== null);
```

### Verify a webhook (Laravel)

```php
use Splashifypro\Webhooks;

Route::post('/splashify/webhook', function (Request $request) {
    if (!Webhooks::verify(
        rawBody: $request->getContent(),
        signature: $request->header('X-Splashify-Signature', ''),
        secret: env('SPLASHIFY_WEBHOOK_SECRET'),
    )) {
        return response('', 401);
    }

    $event = $request->json()->all();
    Log::info("Splashify event: {$event['type']}", $event['payload']);
    return response('', 200);
});
```

### Verify a webhook (vanilla PHP)

```php
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SPLASHIFY_SIGNATURE'] ?? '';

if (!Splashifypro\Webhooks::verify(
    rawBody: $rawBody,
    signature: $signature,
    secret: getenv('SPLASHIFY_WEBHOOK_SECRET'),
)) {
    http_response_code(401);
    exit;
}

$event = json_decode($rawBody, true);
// Process $event['type'] + $event['payload']
http_response_code(200);
```

## Error handling

```php
use Splashifypro\Exceptions\{
    SplashifyException,
    RateLimitException,
    AuthException,
    ValidationException,
    NotFoundException,
};

try {
    $splashify->messages->sendText(['to' => '919876543210', 'text' => 'Hi']);
} catch (RateLimitException $e) {
    echo "Rate limited, retry after {$e->retryAfterSec}s\n";
} catch (AuthException $e) {
    echo "Bad API key\n";
} catch (ValidationException $e) {
    echo "Bad input: {$e->field} — {$e->reason}\n";
} catch (SplashifyException $e) {
    echo "API error {$e->code}: {$e->getMessage()}\n";
}
```

## PHPDoc + IDE autocomplete

Every method has full PHPDoc — works with PHPStorm, VS Code + Intelephense, Vim + intelephense LSP.

## Source + issues

- Packagist: https://packagist.org/packages/splashifypro/sdk
- GitHub: https://github.com/splashifypro/sdk-php
- Issues: file at the GitHub repo above


========================================================================
## Python SDK
URL: https://docs.splashifypro.com/public-api/sdks/python
========================================================================

# Python SDK

Official Splashify Pro SDK for Python.

**Package:** [`splashifypro`](https://pypi.org/project/splashifypro/)

## Install

```bash
pip install splashifypro
# or with poetry
poetry add splashifypro
```

Requires Python 3.9+.

## Configure

```python

from splashifypro import Splashify

splashify = Splashify(
    api_key=os.environ["SPLASHIFY_API_KEY"],
    # optional:
    base_url="https://apis.splashifypro.com",
    timeout=30,        # seconds
    retries=3,         # 5xx auto-retry with backoff
)
```

## First message — under 10 lines

```python

from splashifypro import Splashify

splashify = Splashify(api_key=os.environ["SPLASHIFY_API_KEY"])

result = splashify.messages.send_text(
    to="919876543210",
    text="Hello from Splashify Pro!",
)

print(f"Sent: {result.message_id}")
```

## Async support

```python

from splashifypro.aio import AsyncSplashify

async def main():
    splashify = AsyncSplashify(api_key=os.environ["SPLASHIFY_API_KEY"])
    result = await splashify.messages.send_text(
        to="919876543210",
        text="Hello async!",
    )
    print(result.message_id)

asyncio.run(main())
```

## Common patterns

### Send a template

```python
splashify.messages.send_template(
    to="919876543210",
    template_name="order_confirmation",
    language="en",
    body_parameters=["Aditya", "#1234", "₹2,499"],
)
```

### Send media

```python
splashify.messages.send_media(
    to="919876543210",
    type="image",
    media_url="https://your-cdn.com/photo.jpg",
    caption="Check this out!",
)
```

### Create a broadcast

```python
broadcast = splashify.broadcasts.create(
    name="Diwali sale",
    template_name="diwali_offer_v1",
    language="en",
    audience_type="segments",
    segment_ids=["<segment-uuid>"],
)
print(f"Broadcast {broadcast.id} queued")

report = splashify.broadcasts.report(broadcast.id)
print(f"{report.sent}/{report.total} sent")
```

### List contacts with pagination

```python
cursor = None
while True:
    page = splashify.contacts.list(limit=100, cursor=cursor)
    for c in page.edges:
        print(c.phone, c.name)
    if not page.page_info.has_next_page:
        break
    cursor = page.page_info.end_cursor
```

### Verify a webhook (Flask)

```python
from flask import Flask, request
from splashifypro import verify_webhook

app = Flask(__name__)

@app.post("/splashify/webhook")
def webhook():
    if not verify_webhook(
        raw_body=request.get_data(),
        signature=request.headers.get("X-Splashify-Signature", ""),
        secret=os.environ["SPLASHIFY_WEBHOOK_SECRET"],
    ):
        return "", 401
    event = request.get_json()
    print(f"Event: {event['type']}", event["payload"])
    return "", 200
```

### Verify a webhook (FastAPI)

```python
from fastapi import FastAPI, Request, HTTPException
from splashifypro import verify_webhook

app = FastAPI()

@app.post("/splashify/webhook")
async def webhook(request: Request):
    body = await request.body()
    if not verify_webhook(
        raw_body=body,
        signature=request.headers.get("x-splashify-signature", ""),
        secret=os.environ["SPLASHIFY_WEBHOOK_SECRET"],
    ):
        raise HTTPException(401)
    event = await request.json()
    return {"received": True}
```

## Error handling

```python
from splashifypro import (
    SplashifyError,
    SplashifyRateLimitError,
    SplashifyAuthError,
    SplashifyValidationError,
    SplashifyNotFoundError,
)

try:
    splashify.messages.send_text(to="919876543210", text="Hi")
except SplashifyRateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after_sec}s")
except SplashifyAuthError:
    print("Bad API key")
except SplashifyValidationError as e:
    print(f"Bad input: {e.field} — {e.reason}")
except SplashifyError as e:
    print(f"API error {e.code}: {e.message}")
```

## Type hints

Every method has full type hints — works with mypy, pyright, and IDE autocomplete out of the box:

```python
from splashifypro.types import SendResult, Contact, Broadcast
```

## Source + issues

- PyPI: https://pypi.org/project/splashifypro/
- GitHub: https://github.com/splashifypro/sdk-python
- Issues: file at the GitHub repo above


========================================================================
## Send Audio Message
URL: https://docs.splashifypro.com/public-api/send-audio
========================================================================

# Send Audio Message

Send an audio file to a customer. Like every free-form message, this works only within the 24-hour customer service window. The audio file must be reachable at a public HTTPS URL — Splashify fetches it and forwards to WhatsApp.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "919876543210",
  "callbackData": "some_callback_data",
  "type": "Audio",
  "data": {
    "message": "This is a test",
    "mediaUrl": "https://your-cdn.example.com/voice/123.mp3",
    "fileName": "Test"
  }
}
```

| Field             | Required | Notes |
|-------------------|----------|-------|
| `phoneNumber`     | yes      | Recipient phone (use `fullPhoneNumber` if you want to inline country code) |
| `type`            | yes      | Must be `"Audio"` |
| `data.message`    | optional | Caption shown alongside the audio |
| `data.mediaUrl`   | yes      | Public HTTPS URL of the audio file. Allowed: `audio/aac`, `audio/mp4`, `audio/mpeg`, `audio/amr`, `audio/ogg`. Max 16 MB |
| `data.fileName`   | optional | Display name in WhatsApp |

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "919876543210",
    "callbackData": "some_callback_data",
    "type": "Audio",
    "data": {
      "message": "This is a test",
      "mediaUrl": "MEDIA_URL",
      "fileName": "Test"
    }
  }'
```

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message queued for sending via Splashify Pro. Check webhook for delivery status",
  "id": "d58aeff7-a81c-47a7-9b67-f381e13f6c4e"
}
```

## Common errors

- **`Customer has not messaged within last 24 hours`** — outside the customer service window. Use a template instead.
- **`Could not download media`** — the `mediaUrl` returned non-200, redirected too many times, or doesn't serve a supported audio mime. Confirm the URL works in `curl -I` first.
- **`Unsupported media type`** — convert to MP3 or OGG/Opus and retry.


========================================================================
## Send Button Message
URL: https://docs.splashifypro.com/public-api/send-button
========================================================================

# Send Button Message

Send an interactive message with up to **3 quick-reply buttons** to a customer. When the customer taps a button, you receive an inbound webhook carrying the button `id` and `title`, so you can route the conversation to the right flow without parsing free text.

Like every free-form message, this requires the customer to be inside the 24-hour customer service window.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "919876543210",
  "callbackData": "feedback_prompt",
  "type": "InteractiveButton",
  "data": {
    "message": {
      "type": "button",
      "body": {
        "text": "Hello, please give your feedback."
      },
      "action": {
        "buttons": [
          { "type": "reply", "reply": { "id": "id1", "title": "Ok"   } },
          { "type": "reply", "reply": { "id": "id2", "title": "Good" } },
          { "type": "reply", "reply": { "id": "id3", "title": "Bad"  } }
        ]
      }
    }
  }
}
```

| Field                                | Required | Notes |
|--------------------------------------|----------|-------|
| `type` (top level)                   | yes      | Must be `"InteractiveButton"` |
| `data.message.type`                  | yes      | Must be `"button"` |
| `data.message.body.text`             | yes      | The body shown above the buttons. Max 1024 chars |
| `data.message.action.buttons`        | yes      | Array of 1–3 reply buttons |
| `buttons[].type`                     | yes      | Must be `"reply"` |
| `buttons[].reply.id`                 | yes      | Stable identifier you choose — echoed back when the customer taps. Max 256 chars |
| `buttons[].reply.title`              | yes      | Visible button label. Max 20 chars |

WhatsApp also supports an optional `header` (text/image/video/document) and `footer` (text). Add them under `data.message.header` and `data.message.footer.text` when needed.

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "919876543210",
    "callbackData": "some_callback_data",
    "type": "InteractiveButton",
    "data": {
      "message": {
        "type": "button",
        "body": { "text": "Hello, please give your feedback." },
        "action": {
          "buttons": [
            { "type": "reply", "reply": { "id": "id1", "title": "Ok"   } },
            { "type": "reply", "reply": { "id": "id2", "title": "Good" } },
            { "type": "reply", "reply": { "id": "id3", "title": "Bad"  } }
          ]
        }
      }
    }
  }'
```

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message queued for sending via Splashify Pro. Check webhook for delivery status",
  "id": "8a35b1e1-fac5-49b4-84d8-526eaa4c4d77"
}
```

## When the user taps a button

The reply arrives via your inbound message webhook with `type: "button"` and the matching `id` and `title`:

```json
{
  "type": "button",
  "from": "919876543210",
  "button_reply": {
    "id": "id2",
    "title": "Good"
  }
}
```

Use the `id` for routing — it's stable, while titles can be translated or reworded later.


========================================================================
## Send Document Message
URL: https://docs.splashifypro.com/public-api/send-document
========================================================================

# Send Document Message

Send a document to a customer — PDFs, Word docs, spreadsheets, slide decks, anything WhatsApp accepts as a document. The file must be reachable at a public HTTPS URL.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "919876543210",
  "callbackData": "invoice_INV-001234",
  "type": "Document",
  "data": {
    "message": "This is a test",
    "mediaUrl": "https://your-cdn.example.com/invoice.pdf"
  }
}
```

| Field           | Required | Notes |
|-----------------|----------|-------|
| `phoneNumber`   | yes      | Recipient phone |
| `type`          | yes      | Must be `"Document"` |
| `data.message`  | optional | Caption shown above the document card |
| `data.mediaUrl` | yes      | Public HTTPS URL. Max 100 MB |
| `data.fileName` | optional | Filename shown to recipient. Defaults to URL filename if omitted |

## Allowed document types

`application/pdf`, `application/msword`, `application/vnd.openxmlformats-officedocument.*` (Office files), `text/plain`, `text/csv`, `application/vnd.ms-powerpoint`.

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "919876543210",
    "callbackData": "some_callback_data",
    "type": "Document",
    "data": {
      "message": "This is a test",
      "mediaUrl": "MEDIA_URL"
    }
  }'
```

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message queued for sending via Splashify Pro. Check webhook for delivery status",
  "id": "cc311ce6-4a31-4b50-b9e9-186357cd6fdf"
}
```

## Error — `400 Bad Request`

```json
{
  "result": false,
  "message": "Please correct the following error - Customer has not messaged within last 24 hours"
}
```

## Tips

- Prefer **PDF** — it renders inline on every WhatsApp client. Office docs always require a download tap.
- Set `fileName` so the customer sees `Invoice-INV-001234.pdf` instead of `123e4567-...pdf` from your CDN.
- For invoices and receipts, send via the [`Send Template — Document Header`](/public-api/send-template-document-header) endpoint outside the 24-hour window.


========================================================================
## Send Email
URL: https://docs.splashifypro.com/public-api/send-email
========================================================================

# Send Email

Send a transactional email — order confirmations, password resets, OTPs, receipts — to a single recipient. Same `sk_live_…` API key as the WhatsApp send endpoints.

> **Prefer SMTP?** Most CMS / eCommerce platforms (WordPress, Magento, Shopify) and frameworks (Django, Laravel, Rails) integrate with email via SMTP rather than a REST API. See [SMTP Setup](/public-api/smtp-setup) for drop-in credentials — same pricing, same pipeline, same DKIM signing.

> **Marketing vs transactional**: this endpoint is **transactional only** (₹0.05/email beyond the daily-100 free tier). For marketing blasts to a list, use the in-app `/email/campaigns` flow which carries a per-campaign analytics shape (open rate, click rate, unsubscribes).

## Prerequisites

1. **Plan with `email_marketing` enabled** — free during trial; paid plans need the Email Marketing feature flag set by the platform admin.
2. **A verified sender domain** at [Settings → Email Domain](https://app.splashifypro.com/settings/email-domain). The `from_email` you pass must be on a verified domain (or `mail.splashifypro.com` for transitional sends without your own DKIM).
3. **A `sk_live_…` API key** from [Settings → Developer](https://app.splashifypro.com/settings/developer).

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/email/send
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "to": "alice@example.com",
  "subject": "Your order #1234 is confirmed",
  "html": "<p>Hi Alice,</p><p>Thanks for your order.</p>",
  "text": "Hi Alice,\nThanks for your order.",
  "from_name": "Acme Store",
  "from_email": "orders@acme-store.com",
  "reply_to": "support@acme-store.com"
}
```

| Field        | Required | Notes |
|--------------|----------|-------|
| `to`         | yes      | Recipient email address |
| `subject`    | yes      | Subject line (UTF-8 supported, MIME-encoded automatically) |
| `html`       | one of html/text | HTML body. Use absolute URLs for images so they render in all clients |
| `text`       | one of html/text | Plaintext fallback. Recommended even when `html` is provided — improves deliverability |
| `from_name`  | recommended | Display name (e.g., "Acme Store"). Falls back to the local-part of `from_email` if omitted |
| `from_email` | yes      | Must be on a domain verified for your account |
| `reply_to`   | optional | Where customer replies should go (often your support inbox) |
| `attachments` | optional | Array of files (PDF, image, doc, etc.) to attach. Each entry takes `filename`, `content_type`, and `content_base64`. Up to 20 files / 10 MiB total. See [Send with Attachments](./send-with-attachments.mdx) for the full schema, inline-image (`cid:`) support, and blocked-extensions list. |

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/email/send \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "alice@example.com",
    "subject": "Your order #1234 is confirmed",
    "html": "<h1>Order confirmed</h1><p>Thank you, Alice — your order ships in 2 business days.</p>",
    "text": "Order confirmed\\n\\nThank you, Alice — your order ships in 2 business days.",
    "from_name": "Acme Store",
    "from_email": "orders@acme-store.com",
    "reply_to": "support@acme-store.com"
  }'
```

## Successful response — `200 OK`

```json
{
  "result": true,
  "status": "queued",
  "message_id": "0190ed42-1234-7c8e-9f0a-abcdef012345"
}
```

The email is queued — actual delivery happens within seconds. Use the `message_id` to poll the [status endpoint](#status-endpoint) for delivery confirmation.

## Common errors

| Status | `message` body | Meaning |
|--------|---------------|---------|
| `400`  | `to must be a valid email address` | Missing or malformed recipient |
| `400`  | `from_email domain '<x>' is not verified.` | Verify the domain at /settings/email-domain first |
| `400`  | `subject is required` | Subject must be non-empty |
| `400`  | `html or text body required` | Provide at least one body format |
| `401`  | `Invalid API key.` | Key revoked, wrong, or expired |
| `402`  | `email_marketing not enabled on your plan` | Plan flag is off; ask admin to upgrade |
| `429`  | `Rate limit exceeded` | Per-plan rate limit; check `Retry-After` header |
| `500`  | `Failed to enqueue: …` | Transient — retry with the same payload |

## Billing

- **First 100 emails per UTC day** are free across both the public API + in-app campaigns combined.
- Beyond that, transactional sends cost **₹0.05/email** + reseller markup (if any). Charges appear in [Settings → Track Expenses](https://app.splashifypro.com/settings/track-expenses) under category `email_transactional`.
- Hard bounces are billed (the SMTP attempt happened); soft bounces that retry are billed once on final acceptance.

## Delivery notes

- **DKIM** signed with `d=<your-verified-domain>` so recipients see `dkim=pass` against your brand.
- **List-Unsubscribe** + **List-Unsubscribe-Post** headers are added automatically. Some inbox providers (Gmail, Outlook) require these on bulk transactional too — they don't show the native Unsubscribe button on a single send, but headers don't hurt.
- **Suppression list** is checked at send-time. Recipients who unsubscribed from any of your past campaigns won't receive transactional sends either unless you explicitly remove them via [Settings → Email Domain → Manage Suppression](https://app.splashifypro.com/settings/email-domain).

## Status endpoint

Poll for delivery confirmation:

```
GET https://apis.splashifypro.com/api/v1/public/email/status/{message_id}
```

Returns:

```json
{
  "result": true,
  "message_id": "0190ed42-1234-7c8e-9f0a-abcdef012345",
  "to": "alice@example.com",
  "from": "orders@acme-store.com",
  "subject": "Your order #1234 is confirmed",
  "status": "delivered",
  "category": "email_transactional",
  "attempt_count": 1,
  "created_at": "2026-04-30T12:34:56Z",
  "sent_at": "2026-04-30T12:34:58Z",
  "delivered_at": "2026-04-30T12:35:01Z"
}
```

`status` is one of: `queued`, `sending`, `sent`, `delivered`, `bounced`, `failed`, `suppressed`.

## See also

- [Send Template Email](./send-template-email.mdx) — use a saved template + variables instead of inline HTML.
- [Send with Attachments](./send-with-attachments.mdx) — attach PDFs, images, and docs to your sends.
- [Authentication](./authentication.mdx) — how the `sk_live_…` key works.
- [Rate Limits](./rate-limits.mdx) — per-plan request budgets.


========================================================================
## Send Image Message
URL: https://docs.splashifypro.com/public-api/send-image
========================================================================

# Send Image Message

Send an image to a customer with an optional caption. The image must be reachable at a public HTTPS URL.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "919876543210",
  "callbackData": "order_12345",
  "type": "Image",
  "data": {
    "message": "This is a test",
    "mediaUrl": "https://your-cdn.example.com/image.jpg"
  }
}
```

| Field           | Required | Notes |
|-----------------|----------|-------|
| `phoneNumber`   | yes      | Recipient phone |
| `type`          | yes      | Must be `"Image"` |
| `data.message`  | optional | Caption rendered below the image. Supports `*bold*`, `_italic_` |
| `data.mediaUrl` | yes      | Public HTTPS URL. Allowed: `image/jpeg`, `image/png`. Max 5 MB |

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "919876543210",
    "callbackData": "some_callback_data",
    "type": "Image",
    "data": {
      "message": "This is a test",
      "mediaUrl": "MEDIA_URL"
    }
  }'
```

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message queued for sending via Splashify Pro. Check webhook for delivery status",
  "id": "078fedfa-d3bd-4b6b-b555-ddc10d1f309c"
}
```

## Error — `400 Bad Request`

```json
{
  "result": false,
  "message": "Please correct the following error - Customer has not messaged within last 24 hours"
}
```

## Tips

- **Sticker-pack images** (low-res, transparent) sometimes render with a black background on iOS. Use a solid background.
- **WebP** is allowed for stickers — see [Send Sticker Message](/public-api/send-sticker).
- **Animated GIFs** — WhatsApp converts them to MP4 and shows them as autoplay video. Use [Send Video Message](/public-api/send-video) for predictable behaviour.


========================================================================
## Send List Message
URL: https://docs.splashifypro.com/public-api/send-list
========================================================================

# Send List Message

Send an interactive list message — a single button that opens a sectioned menu. Each row is tappable and the customer's choice arrives as an inbound webhook carrying the row's `id`.

Lists are great for **menu-style flows**: pick a service, pick a slot, pick a product collection. They support more options than a Button message (up to 10 rows across multiple sections).

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "919876543210",
  "callbackData": "browse_collections",
  "type": "InteractiveList",
  "data": {
    "message": {
      "type": "list",
      "body": {
        "text": "Check out our top product collections below!"
      },
      "action": {
        "button": "View Collections",
        "sections": [
          {
            "title": "service",
            "rows": [
              {
                "id": "unique_id1",
                "title": "All products",
                "description": "hello"
              }
            ]
          }
        ]
      }
    }
  }
}
```

| Field                              | Required | Notes |
|------------------------------------|----------|-------|
| `type` (top level)                 | yes      | Must be `"InteractiveList"` |
| `data.message.type`                | yes      | Must be `"list"` |
| `data.message.body.text`           | yes      | Body shown above the menu button. Max 1024 chars |
| `data.message.action.button`       | yes      | Label on the trigger button (e.g. `"View Collections"`). Max 20 chars |
| `data.message.action.sections`     | yes      | Array of sections, each with a `title` and `rows` |
| `sections[].title`                 | optional | Section header. Max 24 chars |
| `sections[].rows`                  | yes      | 1+ rows per section. Up to **10 rows total across all sections** |
| `rows[].id`                        | yes      | Stable identifier — echoed back on tap. Max 200 chars |
| `rows[].title`                     | yes      | Primary row label. Max 24 chars |
| `rows[].description`               | optional | Secondary line below the title. Max 72 chars |

Optional `header` (text only) and `footer.text` are supported under `data.message`.

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "919876543210",
    "callbackData": "some_callback_data",
    "type": "InteractiveList",
    "data": {
      "message": {
        "type": "list",
        "body": { "text": "Check out our top product collections below!" },
        "action": {
          "button": "View Collections",
          "sections": [
            {
              "title": "service",
              "rows": [
                { "id": "unique_id1", "title": "All products", "description": "hello" }
              ]
            }
          ]
        }
      }
    }
  }'
```

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message queued for sending via Splashify Pro. Check webhook for delivery status",
  "id": "8a35b1e1-fac5-49b4-84d8-526eaa4c4d77"
}
```

## When the user taps a row

The selection arrives via your inbound webhook as a `list_reply`:

```json
{
  "type": "list",
  "from": "919876543210",
  "list_reply": {
    "id": "unique_id1",
    "title": "All products",
    "description": "hello"
  }
}
```

## Limits at a glance

- 1–10 sections
- **10 rows total** across all sections
- Title 24 chars, description 72 chars, row id 200 chars
- Body 1024 chars, button label 20 chars


========================================================================
## Send Sticker Message
URL: https://docs.splashifypro.com/public-api/send-sticker
========================================================================

# Send Sticker Message

Send a WhatsApp sticker to a customer. Stickers are static `.webp` images — typically square, transparent, ≤ 100 KB. They render larger than a regular image and don't show a caption.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "9999999999",
  "callbackData": "some_callback_data",
  "type": "Sticker",
  "data": {
    "mediaUrl": "https://img-06.stickers.cloud/packs/.../sticker.webp"
  }
}
```

| Field           | Required | Notes |
|-----------------|----------|-------|
| `phoneNumber`   | yes      | Recipient phone |
| `type`          | yes      | Must be `"Sticker"` |
| `data.mediaUrl` | yes      | Public HTTPS URL to a `.webp` file. Max 100 KB. WhatsApp requires 512×512 px static stickers |

> Stickers do not support captions. If you need text alongside, send a follow-up text message.

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "9999999999",
    "callbackData": "some_callback_data",
    "type": "Sticker",
    "data": {
      "mediaUrl": "https://img-06.stickers.cloud/packs/5df297e3-a7f0-44e0-a6d1-43bdb09b793c/webp/8709a42d-0579-4314-b659-9c2cdb979305.webp"
    }
  }'
```

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message queued for sending via Splashify Pro. Check webhook for delivery status",
  "id": "c1db48d6-c615-45ce-8ac2-4d878d73f6aa"
}
```

## Common errors

- **`Could not download media`** — the `mediaUrl` is unreachable or returns wrong content-type. Confirm the file is served as `image/webp`.
- **`Sticker too large`** — stickers must be ≤ 100 KB. Compress before uploading to your CDN.
- **`Customer has not messaged within last 24 hours`** — outside the customer service window. Stickers can't be sent as templates, so wait for a new inbound first.


========================================================================
## Authentication Template
URL: https://docs.splashifypro.com/public-api/send-template-authentication
========================================================================

# Send Authentication Template

Send a WhatsApp **authentication template** — typically a one-time password (OTP) flow with a copy-code or one-tap autofill button. Authentication templates have their own Meta-approved structure (no header, fixed body, special button) and a separate (lower) per-message price than utility / marketing.

These are the right pick for: login OTPs, signup verification, transaction confirmation codes, password resets.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "9028883545",
  "callbackData": "auth_attempt_42",
  "type": "Template",
  "template": {
    "name": "itk_auth_one_tap",
    "languageCode": "en",
    "bodyValues": [
      "LIPSUM"
    ],
    "buttonValues": {
      "0": [
        "LIPSUM"
      ]
    }
  }
}
```

| Field                            | Required | Notes |
|----------------------------------|----------|-------|
| `template.name`                  | yes      | The authentication template code name |
| `template.languageCode`          | yes      | Match the approved language |
| `template.bodyValues`            | yes      | Single-element array — the OTP code as a string. Max 15 chars |
| `template.buttonValues["0"]`     | yes      | Same OTP code, repeated for the **copy-code / one-tap** button |

The structure of `buttonValues` is `{"<button_index>": ["value", ...]}`. For an authentication template the OTP button is always at index `0`, and the value array has one entry — the OTP code itself.

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "9028883545",
    "callbackData": "some text here",
    "type": "Template",
    "template": {
      "name": "itk_auth_one_tap",
      "languageCode": "en",
      "bodyValues": ["LIPSUM"],
      "buttonValues": {
        "0": ["LIPSUM"]
      }
    }
  }'
```

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message created successfully",
  "id": "b90f02bd-1316-49ce-b5d0-f6be14fce2b8"
}
```

## Pricing & best practice

- **Authentication templates** are billed at the auth-conversation rate (lower than utility/marketing) when sent via Meta-approved authentication shapes.
- **Always pass the same OTP** in `bodyValues[0]` and `buttonValues["0"][0]`. WhatsApp uses the button value for the copy / one-tap flow; mismatching them confuses users.
- **Do not include the OTP in the URL** of any link button — Meta rejects auth templates with that pattern.
- Generate the OTP server-side, store its hash + expiry, and verify on the way back. Don't trust the client to echo it.


========================================================================
## Carousel Template — With Dynamic CTA
URL: https://docs.splashifypro.com/public-api/send-template-carousel-cta
========================================================================

# Carousel Template — With Dynamic CTA

Send a **carousel template** — a swipeable strip of cards. Each card can have its own image header, body variable values, and a dynamic CTA URL. Carousels are great for product recommendations, multi-deal promotions, or anything where one message body needs to introduce many actionable items.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "9999999999",
  "callbackData": "carousel_promo",
  "type": "Template",
  "template": {
    "name": "template_name_here",
    "languageCode": "en",
    "bodyValues": [
      "body_variable_value_1",
      "body_variable_value_2"
    ],
    "carouselCards": [
      {
        "headerValues": ["media_url_here"],
        "bodyValues":   ["body_variable_value_1"],
        "buttonValues": { "1": ["button_variable_value_1"] }
      },
      {
        "headerValues": ["media_url_here"],
        "bodyValues":   ["body_variable_value_1"],
        "buttonValues": { "1": ["button_variable_value_1"] }
      }
    ]
  }
}
```

| Field                                  | Required | Notes |
|----------------------------------------|----------|-------|
| `template.bodyValues`                  | yes (when intro body has variables) | The body shown **above** the carousel |
| `template.carouselCards`               | yes      | 2–10 cards. Each card mirrors the per-card structure of an approved template |
| `carouselCards[].headerValues`         | optional | Single-element array — image / video URL for that card |
| `carouselCards[].bodyValues`           | optional | One entry per body variable on the card |
| `carouselCards[].buttonValues`         | optional | Map of `{button_index: [variable_value]}` — same shape as [Dynamic CTA](/public-api/send-template-dynamic-cta) |

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "9999999999",
    "callbackData": "some text here",
    "type": "Template",
    "template": {
      "name": "template_name_here",
      "languageCode": "en",
      "bodyValues": ["body_variable_value_1", "body_variable_value_2"],
      "carouselCards": [
        {
          "headerValues": ["media_url_here"],
          "bodyValues":   ["body_variable_value_1"],
          "buttonValues": { "1": ["button_variable_value_1"] }
        },
        {
          "headerValues": ["media_url_here"],
          "bodyValues":   ["body_variable_value_1"],
          "buttonValues": { "1": ["button_variable_value_1"] }
        }
      ]
    }
  }'
```

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message created successfully",
  "id": "b90f02bd-1316-49ce-b5d0-f6be14fce2b8"
}
```

## Tips

- **All cards share the same template definition.** You can't mix image headers and video headers in the same carousel — the template defines a single header type that every card inherits.
- **Card count must match the template's approved card count.** If the template was approved with 4 cards, you must pass exactly 4 entries in `carouselCards`.
- Use [Without Dynamic CTA](/public-api/send-template-carousel-no-cta) when the buttons are static (e.g. a fixed `View on website` URL with no per-card variable).


========================================================================
## Carousel Template — Without Dynamic CTA
URL: https://docs.splashifypro.com/public-api/send-template-carousel-no-cta
========================================================================

# Carousel Template — Without Dynamic CTA

Same shape as a [Carousel Template — With Dynamic CTA](/public-api/send-template-carousel-cta), but the per-card buttons are **static** — no `buttonValues` payload because the template was approved with fixed URLs.

Use this when every card's CTA points to the same fixed URL or a phone number, and only the per-card image and body text vary by send.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "9999999999",
  "callbackData": "carousel_static",
  "template_category": "utility",
  "type": "Template",
  "template": {
    "name": "template_name_here",
    "languageCode": "en",
    "bodyValues": [
      "body_variable_value_1",
      "body_variable_value_2"
    ],
    "carouselCards": [
      {
        "headerValues": ["media_url_here"],
        "bodyValues":   ["body_variable_value_1"]
      },
      {
        "headerValues": ["media_url_here"],
        "bodyValues":   ["body_variable_value_1"]
      }
    ]
  }
}
```

| Field                                  | Required | Notes |
|----------------------------------------|----------|-------|
| `template_category`                    | optional | Lock the send to a category (`utility`, `marketing`, `authentication`) — surfaced at the top level here |
| `template.carouselCards[].headerValues`| optional | Image / video URL for the card |
| `template.carouselCards[].bodyValues`  | optional | Per-card body variables |
| `buttonValues`                         | not used | Omit entirely when the buttons have no dynamic part |

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "9999999999",
    "callbackData": "some text here",
    "template_category": "utility",
    "type": "Template",
    "template": {
      "name": "template_name_here",
      "languageCode": "en",
      "bodyValues": ["body_variable_value_1", "body_variable_value_2"],
      "carouselCards": [
        { "headerValues": ["media_url_here"], "bodyValues": ["body_variable_value_1"] },
        { "headerValues": ["media_url_here"], "bodyValues": ["body_variable_value_1"] }
      ]
    }
  }'
```

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message created successfully",
  "id": "8d620ba1-640f-42ee-a8dd-15363422144b"
}
```

## When to use this vs the dynamic variant

| You need                                                  | Use |
|-----------------------------------------------------------|-----|
| Each card linking to a different per-customer URL         | [Carousel — With Dynamic CTA](/public-api/send-template-carousel-cta) |
| Each card linking to the same fixed URL (e.g. catalog)    | This endpoint |
| Cards with phone-number buttons (always static)           | This endpoint |


========================================================================
## Template — Document Header
URL: https://docs.splashifypro.com/public-api/send-template-document-header
========================================================================

# Send Template — Document Header

Send an approved template whose **header** is a document. Common use cases: invoices, tickets, lab reports, statements — any document you want to attach to a transactional template.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "9999999999",
  "callbackData": "invoice_INV-001234",
  "type": "Template",
  "template": {
    "name": "template_name_here",
    "languageCode": "en",
    "headerValues": [
      "media_url_here"
    ],
    "fileName": "file_name.pdf",
    "bodyValues": [
      "body_variable_value"
    ]
  }
}
```

| Field                  | Required | Notes |
|------------------------|----------|-------|
| `template.headerValues`| yes      | Single-element array containing the document's **public HTTPS URL** |
| `template.fileName`    | optional | Display filename in WhatsApp. Defaults to URL basename if omitted |
| `template.bodyValues`  | yes (when body has variables) | One entry per body variable |

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "9999999999",
    "callbackData": "some text here",
    "type": "Template",
    "template": {
      "name": "template_name_here",
      "languageCode": "en",
      "headerValues": ["media_url_here"],
      "fileName": "file_name.pdf",
      "bodyValues": ["body_variable_value"]
    }
  }'
```

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message created successfully",
  "id": "36e7d39e-9e3b-4fe6-b21a-abec53ea021e"
}
```

## Error — Template category mismatch

```json
{
  "result": false,
  "message": "Message not sent. Template category mismatch: Expected 'utility', but received 'MARKETING'. Please update the request to match the approved template category."
}
```

## Tips

- Set `fileName` so the customer sees `Invoice-INV-001234.pdf` instead of a UUID from your CDN.
- Allowed types: PDF, DOCX, XLSX, PPTX, TXT, CSV. Max 100 MB.
- The same template can be re-used with a different document URL each time — no need to upload to Meta in advance.


========================================================================
## Template — Dynamic CTA
URL: https://docs.splashifypro.com/public-api/send-template-dynamic-cta
========================================================================

# Send Template — Dynamic CTA

Send an approved template that includes a **URL button with a dynamic suffix**. Common use cases: per-customer order tracking links, magic-login URLs, personalised landing pages.

The template is approved with a base URL like `https://yourdomain.com/order/{{1}}` and at send time you pass the variable value, which Meta substitutes into the button.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "9999999999",
  "callbackData": "order_12345",
  "type": "Template",
  "template": {
    "name": "template_name_here",
    "languageCode": "en",
    "bodyValues": [
      "body_variable_value_1",
      "body_variable_value_2"
    ],
    "buttonValues": {
      "1": [
        "button_variable_value"
      ]
    }
  }
}
```

| Field                          | Required | Notes |
|--------------------------------|----------|-------|
| `template.bodyValues`          | yes (when body has variables) | One entry per `{{n}}` in the body |
| `template.buttonValues`        | yes      | Map of `{button_index: [variable_value]}` — see below |

### Button index — important

`buttonValues` is keyed by **button index**, starting at `0`. If a template has two buttons:

- `0` — Phone number button (no dynamic part — never goes in `buttonValues`)
- `1` — URL button with a dynamic suffix

Then your payload has `"buttonValues": { "1": ["value"] }` — note the index `"1"`, not `"0"`.

If the template has only the URL button, it would be at index `0`:

```json
"buttonValues": { "0": ["value"] }
```

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "9999999999",
    "callbackData": "some text here",
    "type": "Template",
    "template": {
      "name": "template_name_here",
      "languageCode": "en",
      "bodyValues": ["body_variable_value_1", "body_variable_value_2"],
      "buttonValues": { "1": ["button_variable_value"] }
    }
  }'
```

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message created successfully",
  "id": "2d14b3d9-5dc2-4a76-b139-7394cac5888f"
}
```

## Error — Template category mismatch

```json
{
  "result": false,
  "message": "Message not sent. Template category mismatch: Expected 'utility', but received 'MARKETING'. Please update the request to match the approved template category."
}
```

## Tips

- **Encode the suffix** before passing it. If your dynamic value contains `&`, `=`, `#`, or spaces, the resulting button URL will break unless you `encodeURIComponent`.
- Meta enforces a **15-character limit** on dynamic suffixes for some plans. Use a short slug (`a1b2c3`) and resolve to the full URL on your server-side redirect.
- Combine with [Template — Image Header](/public-api/send-template-image-header) by adding `headerValues` — same template can have an image AND a dynamic URL button.


========================================================================
## Send Template Email
URL: https://docs.splashifypro.com/public-api/send-template-email
========================================================================

# Send Template Email

Send an email using a template you built in the [visual editor](https://app.splashifypro.com/email/templates). Pass `template_id` + a `variables` map; the backend pulls the rendered HTML snapshot, substitutes `{{variable}}` tokens, and queues the send.

This is the right endpoint when:

- You're sending the same shape of email repeatedly (order confirmations, OTP codes, password resets) and want to maintain the design in one place.
- You want non-developers to update the email body without redeploying your app.

For one-off sends with bespoke HTML, use [Send Email](./send-email.mdx) instead.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/email/send-template
```

## Headers

Same as [Send Email](./send-email.mdx#headers) — `Authorization: Basic YOUR_API_KEY` + `Content-Type: application/json`.

## Request body

```json
{
  "to": "alice@example.com",
  "template_id": "5d7e2a1f-3c4b-4d8a-9b1c-7e8f9a0b1c2d",
  "variables": {
    "first_name": "Alice",
    "order_number": "1234",
    "tracking_url": "https://acme-store.com/track/1234",
    "items": "2 × Widget, 1 × Gadget"
  },
  "from_name": "Acme Store",
  "from_email": "orders@acme-store.com",
  "reply_to": "support@acme-store.com",
  "subject": "Override the saved subject (optional)"
}
```

| Field          | Required | Notes |
|----------------|----------|-------|
| `to`           | yes      | Recipient email address |
| `template_id`  | yes      | UUID of a template you own. Find it in the URL when editing a template |
| `variables`    | optional | Key/value pairs substituted into `{{key}}` tokens in subject + body |
| `from_name`    | recommended | Display name, falls back to local-part of `from_email` |
| `from_email`   | yes      | Must be on a verified domain |
| `reply_to`     | optional | Customer reply address |
| `subject`      | optional | Overrides the template's saved subject when provided |
| `attachments`  | optional | Array of files to attach (up to 20 / 10 MiB total). See [Send with Attachments](./send-with-attachments.mdx) for the full schema. |

## Variable substitution

Tokens use double-brace syntax: `{{first_name}}`, `{{order_total}}`, etc. They're substituted in the **subject**, **HTML body**, and **plaintext body** independently — so you can use the same variable in all three places.

Reserved tokens (always populated):

| Token                 | Value |
|----------------------|-------|
| `{{recipient_email}}` | The `to` value |

Unknown tokens render as empty strings rather than failing the send. Use this to make optional fields safe (e.g., `{{coupon_code}}` is empty when no coupon applies).

Values can be strings, numbers, or booleans. Nested objects get JSON-stringified.

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/email/send-template \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "alice@example.com",
    "template_id": "5d7e2a1f-3c4b-4d8a-9b1c-7e8f9a0b1c2d",
    "variables": {
      "first_name": "Alice",
      "order_number": "1234",
      "tracking_url": "https://acme-store.com/track/1234"
    },
    "from_name": "Acme Store",
    "from_email": "orders@acme-store.com"
  }'
```

If the template's saved subject is `"Order #{{order_number}} confirmed"`, the recipient sees subject `"Order #1234 confirmed"`.

## Successful response — `200 OK`

```json
{
  "result": true,
  "status": "queued",
  "message_id": "0190ed42-1234-7c8e-9f0a-abcdef012345"
}
```

Same status polling endpoint as [Send Email](./send-email.mdx#status-endpoint):

```
GET /api/v1/public/email/status/{message_id}
```

## Common errors

| Status | `message` body | Meaning |
|--------|---------------|---------|
| `400`  | `template_id is required` | Missing field |
| `400`  | `invalid template_id` | Not a valid UUID |
| `404`  | `template not found` | Template doesn't exist or doesn't belong to your account |
| `400`  | `from_email domain '<x>' is not verified.` | Verify the domain first |
| `402`  | `email_marketing not enabled on your plan` | Plan flag is off |

## When to update the template snapshot

The render pipeline uses the **pre-compiled HTML snapshot** that was saved the last time you clicked Save in the visual editor — not a fresh render per send. This keeps per-recipient cost negligible (just string-replace) but means you need to **save** the template before changes show up in API sends.

If a customer reports the wrong template content, confirm the latest version was saved + re-test.

## Billing

Same as [Send Email](./send-email.mdx#billing): first 100/day combined free, then ₹0.05/email + reseller markup beyond. Category appears as `email_transactional` in Track Expenses.

## See also

- [Send Email](./send-email.mdx) — inline HTML send, no template needed.
- [Send with Attachments](./send-with-attachments.mdx) — attach PDFs, images, and docs to template sends.
- [Email Templates UI](https://app.splashifypro.com/email/templates) — visual editor.
- [Authentication](./authentication.mdx) — how the API key works.


========================================================================
## Template — Image Header
URL: https://docs.splashifypro.com/public-api/send-template-image-header
========================================================================

# Send Template — Image Header

Send an approved template whose **header** is an image. Common use cases: promotional templates, order confirmations with product photos, banner-style notifications.

The same template can be re-used with a different image URL each send — Meta does not require pre-upload.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "9999999999",
  "callbackData": "promo_2026_04",
  "type": "Template",
  "template": {
    "name": "template_name_here",
    "languageCode": "en",
    "headerValues": [
      "media_url_here"
    ],
    "bodyValues": [
      "body_variable_value"
    ]
  }
}
```

| Field                  | Required | Notes |
|------------------------|----------|-------|
| `template.headerValues`| yes      | Single-element array containing the image's **public HTTPS URL**. Allowed: JPEG, PNG. Max 5 MB |
| `template.bodyValues`  | yes (when body has variables) | One entry per body variable |

The same shape works for **video headers** — just point `headerValues[0]` at an MP4 (≤ 16 MB, H.264 + AAC).

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "9999999999",
    "callbackData": "some text here",
    "type": "Template",
    "template": {
      "name": "template_name_here",
      "languageCode": "bg",
      "headerValues": ["media_url_here"],
      "bodyValues": ["body_variable_value"]
    }
  }'
```

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message created successfully",
  "id": "b90f02bd-1316-49ce-b5d0-f6be14fce2b8"
}
```

## Error — Template category mismatch

```json
{
  "result": false,
  "message": "Message not sent. Template category mismatch: Expected 'utility', but received 'MARKETING'. Please update the request to match the approved template category."
}
```

## Image guidelines

- **1.91:1 aspect ratio** (landscape banner) renders cleanly on every WhatsApp client. Square works too.
- Avoid copy-heavy images — Meta sometimes rejects images that look like text-only graphics during template approval.
- Keep file size under 1 MB for best load time on slow networks.


========================================================================
## Template — No Header
URL: https://docs.splashifypro.com/public-api/send-template-no-header
========================================================================

# Send Template Message — No Header

Send an approved WhatsApp template that has **only a body** (no header section) and optionally uses body variables. This is the simplest template shape and the right starting point if you're new to template sends.

Template messages can be sent **at any time** — they are not bound to the 24-hour customer service window like free-form messages.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "9999999999",
  "callbackData": "order_12345",
  "type": "Template",
  "template": {
    "name": "template_name_here",
    "languageCode": "en",
    "bodyValues": [
      "body_variable_value_1",
      "body_variable_value_n"
    ]
  }
}
```

| Field                  | Required | Notes |
|------------------------|----------|-------|
| `phoneNumber`          | yes      | Use `phoneNumber` + `countryCode` OR `fullPhoneNumber` |
| `type`                 | yes      | Must be `"Template"` |
| `template.name`        | yes      | The template **code name** — find it next to the info icon at **Templates → List** in the app |
| `template.languageCode`| yes      | Must match the language the template was approved in (e.g. `en`, `en_US`, `hi`, `bg`) |
| `template.bodyValues`  | yes (when body has variables) | Array of strings, one per `{{1}}`, `{{2}}`, ... in the body |
| `template.template_category` | optional | `utility`, `marketing`, `authentication` — see [category lock](#protect-against-template-recategorisation) |
| `callbackData`         | optional | Up to 512 chars, echoed in webhooks |

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "9999999999",
    "callbackData": "some text here",
    "type": "Template",
    "template": {
      "name": "template_name_here",
      "languageCode": "en",
      "bodyValues": [
        "body_variable_value_1",
        "body_variable_value_n"
      ]
    }
  }'
```

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message created successfully",
  "id": "8d620ba1-640f-42ee-a8dd-15363422144b"
}
```

## Protect against template recategorisation

Meta periodically recategorises Utility templates as Marketing. Marketing messages are 5–6× more expensive and have noticeably lower delivery rates (50–70%). Pass `template_category` to lock the send to a category — if Meta has silently re-categorised, the API returns an error instead of a surprise marketing-priced send.

```json
{
  "phoneNumber": "9999999999",
  "type": "Template",
  "template": {
    "name": "order_confirmation",
    "languageCode": "en",
    "template_category": "utility",
    "bodyValues": ["John", "ORD-1234"]
  }
}
```

If the template's current category does not match:

```json
{
  "result": false,
  "message": "Message not sent. Template category mismatch: Expected 'utility', but received 'MARKETING'. Please update the request to match the approved template category."
}
```


========================================================================
## Order Details Carousel
URL: https://docs.splashifypro.com/public-api/send-template-order-details-carousel
========================================================================

# Order Details Carousel

Send a **carousel** where each card carries a complete WhatsApp Pay **order details** payload — itemised order, shipping address, totals, payment-option expiry. The customer can pay each order directly inside WhatsApp without leaving the chat.

Use this when you want to show multiple distinct orders (e.g. "Cake A" and "Cake B") in one message, each independently payable.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "9999999999",
  "callbackData": "wapay_carousel_001",
  "type": "Template",
  "template": {
    "name": "carousel_var",
    "languageCode": "en",
    "bodyValues": ["mj"],
    "carouselCards": [
      {
        "headerValues": ["https://your-cdn.example.com/cake-strawberry.mp4"],
        "bodyValues": ["mj"],
        "buttonValues": {}
      },
      {
        "headerValues": ["https://your-cdn.example.com/cake-chocolate.mp4"],
        "bodyValues": ["mj1"],
        "buttonValues": {}
      }
    ],
    "order_details": [
      {
        "reference_id": "22july25mjwapaytemp111",
        "order_items": [
          {
            "name": "Strawberry Cake",
            "quantity": 1,
            "amount": 1,
            "country_of_origin": "India"
          }
        ],
        "shipping_addresses": [
          {
            "name": "Akhil Kumar",
            "phone_number": "919000090000",
            "address": "Bandra Kurla Complex",
            "city": "Mumbai",
            "state": "Maharastra",
            "in_pin_code": "400051",
            "house_number": "12",
            "tower_number": "5",
            "building_name": "One BKC",
            "landmark_area": "Near BKC Circle",
            "country": "IN"
          }
        ],
        "subtotal": 1,
        "discount": 0,
        "tax": 0,
        "shipping": 0,
        "total_amount": 1,
        "currency": "INR",
        "payment_option_expires_in": {
          "value": 15,
          "unit": "minutes",
          "expiration_message": ""
        }
      },
      {
        "reference_id": "22july25mjwapaytemp2333",
        "order_items": [
          { "name": "Chocolate Cake", "quantity": 1, "amount": 1, "country_of_origin": "India" }
        ],
        "shipping_addresses": [
          {
            "name": "Akhil Kumar",
            "phone_number": "919000090000",
            "address": "Bandra Kurla Complex",
            "city": "Mumbai",
            "state": "Maharastra",
            "in_pin_code": "400051",
            "house_number": "12",
            "tower_number": "5",
            "building_name": "One BKC",
            "landmark_area": "Near BKC Circle",
            "country": "IN"
          }
        ],
        "subtotal": 1, "discount": 0, "tax": 0, "shipping": 0,
        "total_amount": 1,
        "currency": "INR",
        "payment_option_expires_in": { "value": 15, "unit": "minutes", "expiration_message": "" }
      }
    ]
  }
}
```

| Field                                              | Required | Notes |
|----------------------------------------------------|----------|-------|
| `template.carouselCards[]`                         | yes      | Same shape as a regular carousel — header + body + (no) buttons |
| `template.order_details[]`                         | yes      | One entry **per card** — index aligned with `carouselCards` |
| `order_details[].reference_id`                     | yes      | Unique id per order. Use this on your side to reconcile WhatsApp Pay webhooks |
| `order_details[].order_items[]`                    | yes      | Itemized list — `name`, `quantity`, `amount`, `country_of_origin` |
| `order_details[].shipping_addresses[]`             | conditional | **Mandatory for physical goods**, optional for digital goods |
| `order_details[].subtotal`/`discount`/`tax`/`shipping`/`total_amount` | yes | Numbers, in the smallest currency unit (paise for INR) |
| `order_details[].currency`                         | yes      | ISO 4217 — `INR`, `USD`, etc. |
| `order_details[].payment_option_expires_in`        | optional | `{ value, unit (minutes/hours), expiration_message }` — when the payment link expires |

## Example

The full request body shown above is a copy-pasteable example.

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message created successfully",
  "id": "8d620ba1-640f-42ee-a8dd-15363422144b"
}
```

## Tips

- **`reference_id` is your reconciliation key.** It comes back on every WhatsApp Pay webhook. Generate it server-side and persist it before the API call.
- **Country codes** in addresses use ISO 3166-1 alpha-2 (`IN`, `US`, `BD`).
- **Use [Order Status](/public-api/send-template-order-status)** to follow up after an order is paid / cancelled / shipped.
- For a single-image variant of the same flow, see [Order Details — Single Image](/public-api/send-template-order-details-single).


========================================================================
## Order Details — Single Image
URL: https://docs.splashifypro.com/public-api/send-template-order-details-single
========================================================================

# Order Details — Single Image

Send a **single-card** WhatsApp Pay order details message. Same payable order shape as the [carousel variant](/public-api/send-template-order-details-carousel), but with one card and one image header — use this for one-shot transactional sends like a single product order or a pre-filled cart.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "9999999999",
  "callbackData": "",
  "type": "Template",
  "template": {
    "name": "single_image",
    "languageCode": "en",
    "headerValues": [
      "https://your-cdn.example.com/strawberry-cake.jpg"
    ],
    "bodyValues": ["mj"],
    "order_details": [
      {
        "reference_id": "22july25mjwapaytemp1",
        "order_items": [
          {
            "name": "Strawberry Cake",
            "quantity": 1,
            "amount": 1,
            "country_of_origin": "India"
          }
        ],
        "shipping_addresses": [
          {
            "name": "Akhil Kumar",
            "phone_number": "919000090000",
            "address": "Bandra Kurla Complex",
            "city": "Mumbai",
            "state": "Maharastra",
            "in_pin_code": "400051",
            "house_number": "12",
            "tower_number": "5",
            "building_name": "One BKC",
            "landmark_area": "Near BKC Circle",
            "country": "IN"
          }
        ],
        "subtotal": 1,
        "discount": 0,
        "tax": 0,
        "shipping": 0,
        "total_amount": 1,
        "currency": "INR",
        "payment_option_expires_in": {
          "value": 15,
          "unit": "minutes",
          "expiration_message": ""
        }
      }
    ]
  }
}
```

| Field                                            | Required | Notes |
|--------------------------------------------------|----------|-------|
| `template.headerValues[0]`                       | yes      | Image URL for the card |
| `template.bodyValues`                            | optional | Body variables |
| `template.order_details[]`                       | yes      | **Exactly one entry** for this single-image variant |
| `order_details[].reference_id`                   | yes      | Unique id — used to reconcile WhatsApp Pay webhooks |
| `order_details[].order_items[]`                  | yes      | Itemised order line items |
| `order_details[].shipping_addresses[]`           | conditional | Mandatory for physical goods, optional for digital |
| `order_details[].subtotal/discount/tax/shipping/total_amount` | yes | Numeric; in smallest currency unit (paise for INR) |
| `order_details[].currency`                       | yes      | ISO 4217 |
| `order_details[].payment_option_expires_in`      | optional | When the WhatsApp Pay link expires |

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '@order-payload.json'
```

(See the JSON above — copy it into `order-payload.json` and send.)

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message created successfully",
  "id": "8d620ba1-640f-42ee-a8dd-15363422144b"
}
```

## Tips

- **Use a high-quality 1.91:1 image** for the header — Meta downscales for slow networks but the source affects perceived quality.
- The `reference_id` you pass here is the same reference you'll use later when sending an [Order Status](/public-api/send-template-order-status) update.
- All amounts are integers in the smallest unit. ₹1.00 → `100` paise, never `1.00`.


========================================================================
## Order Status Template
URL: https://docs.splashifypro.com/public-api/send-template-order-status
========================================================================

# Order Status Template

Send a **status update** for a previously dispatched WhatsApp Pay order — confirm receipt, cancel, ship, refund, etc. The update is keyed by the `reference_id` you used when you originally sent the [Order Details Carousel](/public-api/send-template-order-details-carousel) (or single-image variant).

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "9999999999",
  "callbackData": "",
  "type": "Template",
  "template": {
    "name": "payment_confirmation_whatsapp_pay",
    "languageCode": "en",
    "bodyValues": ["200"],
    "order_status": {
      "reference_id": "22july25mjwapaytemp1",
      "order": {
        "status": "canceled",
        "description": "Order failed"
      }
    }
  }
}
```

| Field                                  | Required | Notes |
|----------------------------------------|----------|-------|
| `template.bodyValues`                  | optional | Body variables for the template |
| `template.order_status.reference_id`   | yes      | Must match the `reference_id` you sent earlier in the order details |
| `template.order_status.order.status`   | yes      | One of `processing`, `partially_shipped`, `shipped`, `completed`, `canceled` |
| `template.order_status.order.description` | optional | Free-text reason / detail shown to the customer |

## Status values

| `status`             | Meaning |
|----------------------|---------|
| `processing`         | Order received, payment confirmed, being prepared |
| `partially_shipped`  | Some items dispatched, others still pending |
| `shipped`            | Fully dispatched |
| `completed`          | Delivered or fulfilled |
| `canceled`           | Cancelled — usually pair with a `description` explaining why |

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "9999999999",
    "callbackData": "",
    "type": "Template",
    "template": {
      "name": "payment_confirmation_whatsapp_pay",
      "languageCode": "en",
      "bodyValues": ["200"],
      "order_status": {
        "reference_id": "22july25mjwapaytemp1",
        "order": { "status": "canceled", "description": "Order failed" }
      }
    }
  }'
```

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message created successfully",
  "id": "8d620ba1-640f-42ee-a8dd-15363422144b"
}
```

## Notes

- Order status updates are **idempotent on `reference_id`** — sending the same status twice for the same order is harmless.
- The customer sees the order card update in-place inside the original conversation (no new message bubble is created in some clients), so transitions feel natural.
- Combine with your fulfilment webhooks — fire `processing` on payment-success, `shipped` when your courier picks up, `completed` on delivery.


========================================================================
## Template — Text Header (with variable)
URL: https://docs.splashifypro.com/public-api/send-template-text-header
========================================================================

# Send Template — Text Header with Variable

Send an approved template whose **header** is text and contains a variable (e.g. `Hi {{1}}!`). Use this when you want a personalised greeting at the top of the message.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "9999999999",
  "callbackData": "order_12345",
  "type": "Template",
  "template": {
    "name": "template_name_here",
    "languageCode": "en",
    "headerValues": [
      "header_variable_value"
    ],
    "bodyValues": [
      "body_variable_value_1",
      "body_variable_value_n"
    ]
  }
}
```

| Field                    | Required | Notes |
|--------------------------|----------|-------|
| `template.headerValues`  | yes (when header has a variable) | Single-element array — text headers support only **one** variable |
| `template.bodyValues`    | yes (when body has variables) | One entry per `{{1}}`, `{{2}}`, ... |
| Everything else          |          | Same as [Template — No Header](/public-api/send-template-no-header) |

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "9999999999",
    "callbackData": "some text here",
    "type": "Template",
    "template": {
      "name": "template_name_here",
      "languageCode": "en",
      "headerValues": ["header_variable_value"],
      "bodyValues": ["body_variable_value_1", "body_variable_value_n"]
    }
  }'
```

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message created successfully",
  "id": "96f0b7a2-6d4c-4983-99c6-eaf7591a5a56"
}
```

## Error — Template category mismatch

```json
{
  "result": false,
  "message": "Message not sent. Template category mismatch: Expected 'utility', but received 'MARKETING'. Please update the request to match the approved template category."
}
```

Pass `template_category` to lock the category — see [Template — No Header](/public-api/send-template-no-header#protect-against-template-recategorisation).


========================================================================
## Send Text Message
URL: https://docs.splashifypro.com/public-api/send-text
========================================================================

# Send Text Message

Send a free-form text message to a customer. Free-form messages can only be sent inside the **24-hour customer service window** — i.e. the customer must have messaged your WABA at least once in the past 24 hours. If the window is closed, use a [template message](/public-api/send-template-no-header) instead.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "fullPhoneNumber": "919876543210",
  "callbackData": "order_12345",
  "type": "Text",
  "data": {
    "message": "This msg is sent via API"
  }
}
```

| Field             | Required                                  | Notes |
|-------------------|-------------------------------------------|-------|
| `fullPhoneNumber` | one of `fullPhoneNumber` OR `phoneNumber` + `countryCode` | E.164 without `+` (e.g. `919876543210`) |
| `phoneNumber`     | alternative to `fullPhoneNumber`           | Phone without country code, no leading `0` |
| `countryCode`     | required when using `phoneNumber`          | E.164 country code with `+` (e.g. `+91`) |
| `callbackData`    | optional                                   | Up to 512 chars — echoed in the delivery webhooks for correlation |
| `type`            | yes                                        | Must be `"Text"` |
| `data.message`    | yes                                        | The text body. Supports WhatsApp formatting: `*bold*`, `_italic_`, `~strike~`, `` ``` ``code``` `` |

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fullPhoneNumber": "919876543210",
    "callbackData": "some_callback_data",
    "type": "Text",
    "data": { "message": "This msg is sent via API" }
  }'
```

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message queued for sending via Splashify Pro. Check webhook for delivery status",
  "id": "d58aeff7-a81c-47a7-9b67-f381e13f6c4e"
}
```

The `id` is your Splashify message id — use it to correlate with `message.sent`, `message.delivered`, `message.read`, `message.failed` webhooks.

## Error — `400 Bad Request`

```json
{
  "result": false,
  "message": "Please correct the following error - Customer has not messaged within last 24 hours"
}
```

When the 24-hour window has expired, switch to a template send. The error message names the exact reason — log it on your side for debugging.


========================================================================
## Send Video Message
URL: https://docs.splashifypro.com/public-api/send-video
========================================================================

# Send Video Message

Send a video to a customer with an optional caption. The video must be reachable at a public HTTPS URL.

## Endpoint

```
POST https://apis.splashifypro.com/api/v1/public/message
```

## Headers

| Header          | Value                       |
|-----------------|-----------------------------|
| `Authorization` | `Basic YOUR_API_KEY`        |
| `Content-Type`  | `application/json`          |

## Request body

```json
{
  "phoneNumber": "919876543210",
  "callbackData": "promo_drop",
  "type": "Video",
  "data": {
    "message": "This is a test",
    "mediaUrl": "https://your-cdn.example.com/promo.mp4",
    "fileName": "Test"
  }
}
```

| Field           | Required | Notes |
|-----------------|----------|-------|
| `phoneNumber`   | yes      | Recipient phone |
| `type`          | yes      | Must be `"Video"` |
| `data.message`  | optional | Caption rendered below the video |
| `data.mediaUrl` | yes      | Public HTTPS URL. Allowed: `video/mp4` (H.264 + AAC). Max 16 MB |
| `data.fileName` | optional | Display name |

## Example

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "919876543210",
    "callbackData": "some_callback_data",
    "type": "Video",
    "data": {
      "message": "This is a test",
      "mediaUrl": "MEDIA_URL",
      "fileName": "Test"
    }
  }'
```

## Successful response — `201 Created`

```json
{
  "result": true,
  "message": "Message queued for sending via Splashify Pro. Check webhook for delivery status",
  "id": "cc311ce6-4a31-4b50-b9e9-186357cd6fdf"
}
```

## Error — `400 Bad Request`

```json
{
  "result": false,
  "message": "Please correct the following error - Customer has not messaged within last 24 hours"
}
```

## Encoding tips

WhatsApp is strict about codecs. If a video that looks fine in your browser fails on WhatsApp:

```bash
# Re-encode to H.264 baseline + AAC, faststart for streaming playback
ffmpeg -i input.mov \
  -vcodec libx264 -profile:v baseline -level 3.0 -pix_fmt yuv420p \
  -acodec aac -ac 2 -b:a 128k \
  -movflags +faststart \
  -r 30 -y output.mp4
```

Aspect ratios: prefer 9:16 (vertical) or 16:9 (horizontal) — odd aspect ratios get letterboxed.


========================================================================
## Send with attachments
URL: https://docs.splashifypro.com/public-api/send-with-attachments
========================================================================

# Send with attachments

Both transactional send endpoints accept an `attachments[]` array —
`POST /public/email/send` and `POST /public/email/send-template`. Each
attachment carries the file bytes inline as base64; we build the
`multipart/mixed` MIME structure for you, DKIM-sign it with your
verified sender domain, and ship it to the recipient through the same
self-hosted pipeline as plain-body emails.

## Attachment object

Each entry in `attachments[]` is shaped like this:

```json
{
  "filename":       "invoice-2026-04.pdf",
  "content_type":   "application/pdf",
  "content_base64": "<base64-encoded file bytes>",
  "content_id":     "logo-header",
  "inline":         false
}
```

| Field | Type | Required | Meaning |
|---|---|---|---|
| `filename` | string | yes | Displayed by the recipient's mail client. Directory separators + control chars are stripped automatically. Max 256 chars. |
| `content_type` | string | optional | MIME type (e.g. `application/pdf`). When omitted, we infer from the filename extension and fall back to `application/octet-stream`. Max 256 chars. |
| `content_base64` | string | yes | Standard base64 encoding of the file bytes. **Not** URL-safe base64 — use the standard alphabet. |
| `content_id` | string | optional | Sets `Content-ID` so HTML can reference the attachment as `<img src="cid:logo-header">`. Pair with `inline: true`. |
| `inline` | boolean | optional | When `true`, sets `Content-Disposition: inline` (image renders in the body). When `false` (default), sets `attachment` (file appears in the recipient's attachments list). |

## Limits

| Cap | Value | What happens when exceeded |
|---|---|---|
| Files per message | **20** | Returns `400 INVALID_ATTACHMENT` with `"max 20 attachments per message"` |
| Total decoded bytes | **10 MiB** | Returns `400 INVALID_ATTACHMENT` with the bytes-cap message. Sum runs across all attachments — a single 10.1 MiB PDF is rejected just like 11 × 1 MiB files. |
| Filename length | 256 chars | Rejected at validation. |
| Content-Type length | 256 chars | Rejected at validation. |

## Blocked file types

Executable + script extensions are refused at the API layer because
recipient mail providers (Gmail, Outlook, corporate gateways) block
them outright — sending one would cost a wallet deduction for a
guaranteed bounce. Blocked extensions:

`.exe` `.bat` `.cmd` `.com` `.scr` `.msi` `.vbs` `.vbe` `.js` `.jse`
`.wsf` `.wsh` `.ps1` `.dll` `.jar` `.app` `.sh` `.pl` `.py` `.lnk`

Workaround: bundle them inside a `.zip`. ZIPs are allowed.

## Example — single PDF

```bash
ATT=$(base64 -i invoice.pdf | tr -d '\n')

curl https://apis.splashifypro.com/api/v1/public/email/send \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"to\":         \"customer@example.com\",
    \"subject\":    \"Invoice for March\",
    \"html\":       \"<p>Hi! Your invoice for March is attached.</p>\",
    \"from_name\":  \"Acme Store\",
    \"from_email\": \"billing@your-domain.com\",
    \"attachments\": [
      {
        \"filename\":       \"invoice-march-2026.pdf\",
        \"content_type\":   \"application/pdf\",
        \"content_base64\": \"$ATT\"
      }
    ]
  }"
```

## Example — Node.js (multiple files)

```js

const toAtt = (path, contentType) => ({
  filename:       path.split('/').pop(),
  content_type:   contentType,
  content_base64: readFileSync(path).toString('base64'),
})

const r = await fetch('https://apis.splashifypro.com/api/v1/public/email/send', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${process.env.SPLASHIFY_API_KEY}`,
    'Content-Type':  'application/json',
  },
  body: JSON.stringify({
    to:         'customer@example.com',
    subject:    'Your March documents',
    html:       '<p>Attached: invoice + receipt + signed contract.</p>',
    from_name:  'Acme Store',
    from_email: 'billing@your-domain.com',
    attachments: [
      toAtt('./invoice.pdf',  'application/pdf'),
      toAtt('./receipt.pdf',  'application/pdf'),
      toAtt('./contract.pdf', 'application/pdf'),
    ],
  }),
})
console.log(await r.json())
```

## Example — Python

```python

def att(path, ct):
    with open(path, 'rb') as f:
        return {
            'filename':       os.path.basename(path),
            'content_type':   ct,
            'content_base64': base64.b64encode(f.read()).decode(),
        }

r = requests.post(
    'https://apis.splashifypro.com/api/v1/public/email/send',
    headers={'Authorization': f"Basic {os.environ['SPLASHIFY_API_KEY']}"},
    json={
        'to':         'customer@example.com',
        'subject':    'Attached photo',
        'html':       "<p>Here's the photo from your visit.</p>",
        'from_name':  'Acme Store',
        'from_email': 'support@your-domain.com',
        'attachments': [att('./photo.jpg', 'image/jpeg')],
    },
)
print(r.json())
```

## Example — Inline image (CID reference)

When you want the image to render **inside** the email body instead
of as a separate downloadable file, use `inline: true` + `content_id`,
then reference it from your HTML with `cid:`:

```json
{
  "to":         "customer@example.com",
  "subject":    "Today's newsletter",
  "html":       "<p>Welcome!</p><img src=\"cid:hero-banner\" />",
  "from_name":  "Acme Store",
  "from_email": "newsletter@your-domain.com",
  "attachments": [
    {
      "filename":       "banner.png",
      "content_type":   "image/png",
      "content_base64": "iVBORw0KGgo…",
      "content_id":     "hero-banner",
      "inline":         true
    }
  ]
}
```

Most modern mail clients (Gmail web + mobile, Outlook, Apple Mail)
render inline images correctly. A few hardened corporate gateways
strip them — the file falls back to a regular attachment in those.

## Using attachments with templates

The same `attachments[]` field is accepted on
`POST /public/email/send-template`. The files are attached to the
rendered template output exactly as if you'd inlined the HTML on
`/send`:

```json
{
  "to":          "customer@example.com",
  "template_id": "0190ed42-1234-7c8e-9f0a-abcdef012345",
  "variables":   { "first_name": "Alice", "invoice_no": "INV-1042" },
  "from_email":  "billing@your-domain.com",
  "attachments": [
    {
      "filename":       "invoice-1042.pdf",
      "content_type":   "application/pdf",
      "content_base64": "JVBERi0xLjcKJeLjz9MK…"
    }
  ]
}
```

## Errors

| Status | Code | Reason |
|---|---|---|
| 400 | `INVALID_ATTACHMENT` | Too many files, total size exceeded, blocked extension, invalid base64, or empty content |
| 400 | — | `from_email domain '<x>' is not verified.` (same as plain send) |
| 401 | — | Missing / invalid API key |
| 402 | — | `email_marketing not enabled on your plan` |
| 429 | — | Per-plan rate limit; check `Retry-After` header |

## Pricing

Attachments do **not** incur a per-byte charge. You're billed at the
per-recipient transactional rate (₹0.05/email beyond the daily-100 free
tier + reseller markup if any), regardless of attachment size. The
only practical cost is the 10 MiB total cap which limits how big each
individual message can be.

## Best practices

- **Compress where you can.** A PDF with images compressed to 200 dpi
  vs 600 dpi can be 5× smaller and still look perfect at on-screen
  resolution. Smaller messages deliver faster + use less of your
  10 MiB budget.
- **Use links for files > 5 MiB.** Recipient mail providers throttle
  large messages and some flag them as suspicious. For anything
  bigger, host on object storage and put a download link in the body.
- **Set `content_type` explicitly when you can** — saves us a
  filename-extension guess. The mail client's "open with" picker
  uses this header.
- **Prefer real filenames.** Generic `attachment.pdf` is allowed but
  hurts deliverability slightly (Gmail's spam filter weights
  template-shaped filenames). `invoice-march-2026.pdf` is better.

## See also

- [Send Email](./send-email.mdx) — the base transactional endpoint.
- [Send Template Email](./send-template-email.mdx) — same endpoint with a saved template + variables.
- [Authentication](./authentication.mdx) — how the `sk_live_…` key works.


========================================================================
## SMTP Setup
URL: https://docs.splashifypro.com/public-api/smtp-setup
========================================================================

# SMTP Setup

Send email through Splashify Pro from any app that supports SMTP — WordPress, Django, Magento, Mailchimp Mandrill replacements, n8n, Zapier, Microsoft Power Automate, Apple Mail, Outlook, or any custom backend using a standard SMTP library.

> **When to use SMTP vs the REST API**: SMTP is a drop-in option for legacy apps and most CMS/eCommerce platforms — no code changes, just paste these credentials into your app's email settings. The [Send Email](/public-api/send-email) REST API is faster and gives you per-message status polling. Both go through the same DKIM-signed pipeline and bill identically.

## Server credentials

| Setting | Value |
|---------|-------|
| **SMTP Host** | `smtp.splashifypro.com` |
| **Port (STARTTLS)** | `587` _(recommended)_ |
| **Port (SSL/TLS)** | `465` |
| **Encryption** | `STARTTLS` for port 587, `SSL/TLS` for port 465 |
| **Username** | `emailapikey` _(fixed string — do not change)_ |
| **Password** | Your `sk_live_…` public API key |
| **Auth mechanism** | `PLAIN` or `LOGIN` |

> **Username is literally `emailapikey`** — not your email address, not your account ID. The string `emailapikey` tells our SMTP relay that the password field carries an API key (instead of an email/password pair). The actual identity is encoded in the API key itself.

> **Port 25 is not supported.** Most cloud providers block outbound port 25 to prevent spam relay abuse. Use 587 (STARTTLS) or 465 (SSL).

## Prerequisites

1. **Plan with `email_marketing` enabled** — free during trial; paid plans need the Email Marketing feature flag set on your plan.
2. **A verified sender domain** at [Settings → Email Domain](https://app.splashifypro.com/settings/email-domain). The `From` address you set must be on a domain you've verified (SPF + DKIM CNAME + DMARC). Without verification the relay rejects with `550 5.7.1 sender domain not verified`.
3. **A `sk_live_…` API key** from [Settings → Developer](https://app.splashifypro.com/settings/developer). Treat it like a password — anyone holding it can send mail on your behalf.

## Sender Information

| Field | Value |
|-------|-------|
| **From Email** | Any address on your verified domain (e.g., `info@your-domain.com`) |
| **From Name** | Your business / brand name shown in recipients' inboxes |

## Quick verify with `swaks`

`swaks` (Swiss Army Knife for SMTP) is the fastest way to confirm credentials work before wiring them into your app:

```bash
swaks \
  --to recipient@example.com \
  --from info@your-verified-domain.com \
  --header "Subject: Splashify Pro SMTP test" \
  --body "Hello from SMTP relay" \
  --server smtp.splashifypro.com \
  --port 587 \
  --tls \
  --auth LOGIN \
  --auth-user emailapikey \
  --auth-password sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

A `250 2.0.0 Ok: queued as <message-id>` response confirms the relay accepted your message.

## Platform setup

### WordPress (WP Mail SMTP)

1. Install the **WP Mail SMTP** plugin.
2. Settings → WP Mail SMTP → **Other SMTP**.
3. Fill in:
   - SMTP Host: `smtp.splashifypro.com`
   - Encryption: `TLS`
   - SMTP Port: `587`
   - Auto TLS: ON
   - Authentication: ON
   - SMTP Username: `emailapikey`
   - SMTP Password: your `sk_live_…` key
   - From Email: an address on your verified domain
   - From Name: your store / brand name
4. Save → click **Send a Test Email**.

### PHPMailer

```php
<?php
use PHPMailer\PHPMailer\PHPMailer;
$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->Host       = 'smtp.splashifypro.com';
$mail->SMTPAuth   = true;
$mail->Username   = 'emailapikey';
$mail->Password   = 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->Port       = 587;
$mail->setFrom('info@your-domain.com', 'Your Brand');
$mail->addAddress('recipient@example.com');
$mail->Subject = 'Order #1234 confirmed';
$mail->Body    = 'Thanks for your order!';
$mail->send();
```

### Python (smtplib)

```python

from email.mime.text import MIMEText

msg = MIMEText("Thanks for your order!")
msg["Subject"] = "Order #1234 confirmed"
msg["From"]    = "info@your-domain.com"
msg["To"]      = "recipient@example.com"

with smtplib.SMTP("smtp.splashifypro.com", 587) as server:
    server.starttls()
    server.login("emailapikey", "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx")
    server.send_message(msg)
```

### Node.js (nodemailer)

```javascript
const nodemailer = require("nodemailer");

const transporter = nodemailer.createTransport({
  host: "smtp.splashifypro.com",
  port: 587,
  secure: false, // STARTTLS upgrade — set true only when using port 465
  auth: {
    user: "emailapikey",
    pass: "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  },
});

await transporter.sendMail({
  from: '"Your Brand" <info@your-domain.com>',
  to: "recipient@example.com",
  subject: "Order #1234 confirmed",
  text: "Thanks for your order!",
  html: "<p>Thanks for your order!</p>",
});
```

### Django (`settings.py`)

```python
EMAIL_BACKEND       = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST          = "smtp.splashifypro.com"
EMAIL_PORT          = 587
EMAIL_USE_TLS       = True
EMAIL_HOST_USER     = "emailapikey"
EMAIL_HOST_PASSWORD = "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
DEFAULT_FROM_EMAIL  = "Your Brand <info@your-domain.com>"
```

### Laravel (`.env`)

```bash
MAIL_MAILER=smtp
MAIL_HOST=smtp.splashifypro.com
MAIL_PORT=587
MAIL_USERNAME=emailapikey
MAIL_PASSWORD=sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=info@your-domain.com
MAIL_FROM_NAME="Your Brand"
```

### Magento 2

System → Configuration → Sales → **Sales Emails** + **SMTP On** module:
- Host: `smtp.splashifypro.com`
- Port: `587`
- Auth: `Login`
- Username: `emailapikey`
- Password: your `sk_live_…` key
- TLS: `Yes`
- SSL: `No`

### n8n / Zapier / Power Automate

Pick the **Send Email (SMTP)** node and supply the four credentials above. The same form maps 1:1.

## Pricing

Same per-email pricing as the [REST API](/public-api/send-email) — emails sent over SMTP go through the identical pipeline:

| Tier | Marketing | Transactional |
|------|-----------|---------------|
| 1k–10k emails/mo | ₹0.040 | ₹0.025 |
| 10k–50k emails/mo | ₹0.030 | ₹0.020 |
| 50k+ emails/mo | ₹0.020 | ₹0.015 |

The first **100 emails per day** are free. Above that, your wallet is charged per email.

> **Marketing vs transactional classification**: an SMTP submission is treated as **transactional** by default (₹0.025/email). If you want it counted as marketing (cheaper-tier campaigns or list-based blasts), use the in-app [Campaign builder](https://app.splashifypro.com/email/campaigns) which stamps the right category.

## Deliverability essentials

Email deliverability depends on you setting up DNS correctly on your sending domain. The relay does its part (DKIM signing, IP reputation management, bounce/complaint loops), but recipient inboxes will check yours.

| Record | Required | Purpose |
|--------|----------|---------|
| **SPF** | yes | Authorises Splashify Pro to send on your behalf. Add `include:_spf.splashifypro.com` to your existing SPF record (don't replace). |
| **DKIM** | yes | Cryptographic signature on every message. Splashify Pro publishes the DKIM key on a CNAME we ask you to add. |
| **DMARC** | recommended | Tells inboxes what to do with mail that fails SPF/DKIM. Start with `p=none` to monitor, move to `quarantine` once stable. |
| **MX** | already set | Your inbound mail server. Leave as-is. |

Verify all three at [Settings → Email Domain](https://app.splashifypro.com/settings/email-domain) before going live.

## Limits

| Limit | Value |
|-------|-------|
| Connection rate per API key | 100 concurrent SMTP connections |
| Recipients per message | 50 (split into multiple `RCPT TO`) |
| Message size | 25 MB including attachments |
| Daily volume per account | Unlimited (subject to wallet balance + plan flag) |
| Free daily quota | 100 emails (transactional + marketing combined) |
| Connection timeout | 60 seconds idle |
| Auth attempts before lockout | 5 wrong passwords / 5 minutes per IP |

Hitting any limit returns a standard SMTP failure code your library will surface — `421` for connection limits, `550` for content/policy rejections, `535` for auth failures.

## Status codes

| Code | Meaning | Action |
|------|---------|--------|
| `220` | Server ready | Continue with EHLO |
| `235` | Auth successful | Send messages |
| `250` | Message accepted, queued for delivery | Done — poll [/public/email/status](/public-api/send-email#status) for delivery confirmation |
| `421` | Service unavailable / connection limit hit | Back off, retry with exponential delay |
| `535` | Auth failed | Verify username is literally `emailapikey` and password is a valid `sk_live_…` key |
| `550` | Sender domain not verified, or recipient on suppression list | Verify domain at /settings/email-domain or remove suppression |
| `552` | Message size exceeds 25 MB | Split attachments |
| `554` | Wallet balance insufficient | Top up at [Wallet](https://app.splashifypro.com/wallet) |

## Tracking sent messages

Every SMTP-sent message is visible in [/email](https://app.splashifypro.com/email) under **Send Volume** (Today / 7d / 30d) and rolled into the **Source breakdown → Transactional / API** card alongside REST API sends.

Per-recipient delivery status, opens, clicks, bounces, and complaints are written to your account's audit trail. Pull individual statuses via the [REST status endpoint](/public-api/send-email#status) using the `Message-ID` header that the SMTP server returns in the `250` response.

## Security notes

- **Rotate API keys** if a key has been exposed (committed to git, shared in support channel, etc). Old keys are revocable from [Settings → Developer](https://app.splashifypro.com/settings/developer); SMTP connections using a revoked key get `535 5.7.0 authentication revoked` immediately.
- **Use environment variables** for the password in your code — never hardcode `sk_live_…` keys in source files.
- **Restrict by IP** (Pro plan +): pin a key to a list of allowed source IPs from /settings/developer. Connections from outside the list get `535 5.7.0 IP not authorised`.
- **TLS is enforced** — connections that don't upgrade to TLS via STARTTLS get terminated after the EHLO with `530 5.7.0 must issue STARTTLS first`.

## Troubleshooting

| Symptom | Likely cause |
|---------|--------------|
| `535 5.7.0 authentication failed` | Username isn't `emailapikey`, or password isn't a valid `sk_live_…` key |
| `550 5.7.1 sender domain not verified` | `From:` address is on a domain you haven't verified at /settings/email-domain |
| `554 5.7.0 wallet balance insufficient` | Top up wallet, or sender's plan doesn't have `email_marketing` enabled |
| `421 4.3.2 connection limit reached` | Too many concurrent connections — close idle sessions |
| Connection times out | Firewall blocking 587/465 outbound — many home ISPs and AWS instances block port 25/587 |
| Mail goes to spam | Missing/incomplete SPF or DKIM. Verify at [/settings/email-domain](https://app.splashifypro.com/settings/email-domain). |
| `530 5.7.0 must issue STARTTLS first` | Client connected on 587 without negotiating STARTTLS — enable TLS in your library |

## Need help

- [Email API troubleshooting](/email/troubleshooting)
- [Sender domain setup](/email/sender-domain)
- [Email troubleshooting docs](/email/troubleshooting)
- Or contact support at `support@splashifypro.in`.


========================================================================
## Settings
URL: https://docs.splashifypro.com/settings
========================================================================

# Settings

The **Settings** section covers all account, team, billing, and integration configuration.

Navigate to **Settings** in the sidebar, or click your profile/org name to access specific settings.

## Settings Categories

| Category | What's Inside |
|----------|---------------|
| **Account Details** | Business name, profile, billing address |
| **Team Members** | Invite, manage, and remove team members |
| **Billing & Wallet** | Wallet balance, recharge, billing info |
| **Subscriptions** | View and manage your active plan |
| **Invoices** | Download monthly invoices |
| **Developer** | API keys, webhooks, public API |
| **Integrations** | Connect Razorpay, Shopify, and more |
| **Canned Messages** | Save quick reply shortcuts |
| **Tags** | Manage contact labels |
| **Attributes** | Define custom contact fields |
| **Segments** | Create and manage contact segments |
| **Live Chat** | Welcome message, off-hours, auto-resolve |
| **Calling** | WhatsApp calling configuration |
| **Channels** | Manage connected WABA accounts |
| **CTWA Ads** | Click-to-WhatsApp ad integration |
| **Devices** | View and manage active login sessions |
| **Username** | Set your WhatsApp business username |


========================================================================
## Allowed IPs
URL: https://docs.splashifypro.com/settings/allowed-ips
========================================================================

# Allowed IPs (IP Allowlisting)

Lock down API and web-dashboard access to your account so it only succeeds from IPs you've explicitly trusted. Requests from any other IP are rejected with a clear `ip_blocked` error and the account owner is alerted by email the first time each new IP is blocked.

> **Plan-gated.** This is an enterprise paid-tier feature. Trial users do not get IP allowlisting — by design, so trial accounts can't accidentally lock themselves out. Available on plans where the admin has flipped the `ip_allowlist_enabled` flag.

Navigate to **Settings → Allowed IPs**.

## What gets gated

| Surface | IP-checked? |
|---------|-------------|
| Public API (`sk_live_…` Bearer / SMTP relay / GraphQL) | ✅ Yes |
| Web dashboard (`app.splashifypro.com` JWT) | ✅ Yes |
| Mobile app (iOS / Android) | ❌ No — bypass |
| Webhook receivers (Meta / Razorpay / etc.) | ❌ No — public endpoints |

Mobile is bypassed because cellular networks rotate IPs constantly and would lock users out within a day.

## Add an IP address

Click **Add IP Address** and pick one of two modes:

### Static IP

A single IPv4 address. The form pre-fills your current IP for one-click setup.

```
Office HQ        49.47.154.224
```

### IP range

A start and end IPv4. Useful for office VPNs that hand out an IP from a small pool.

```
Mumbai office VPN     49.47.154.10  to  49.47.154.30
```

Each entry needs a friendly **IP Name** (max 80 chars) so you can identify it later — e.g. `Office HQ`, `Home office`, `Production server`.

## When changes take effect

Allowlist changes propagate within **~60 seconds** (the per-user cache TTL). Add an entry, wait a minute, the next request from that IP succeeds. Removing an entry takes the same window.

The allowlist UI itself is **never gated** by the allowlist — even if you somehow add only a wrong IP and lock yourself out, you can still reach Settings → Allowed IPs from the dashboard to fix it.

## What blocked users see

### API callers

Any `/api/v1/public/*` or `/api/v1/graphql` request from an IP not on the list returns `HTTP 403`:

```json
{
  "success": false,
  "code": "ip_blocked",
  "ip": "203.0.113.45",
  "message": "Access denied — your IP address is not on this account's allowlist."
}
```

Rate-limit budget is **not** consumed by blocked requests, so a misconfigured client retrying in a loop can't burn through your quota.

### Dashboard users

The web app catches the `ip_blocked` response and replaces the page with a dedicated block screen showing the rejected IP and a Refresh / Log out option. No data ever loads on the blocked page.

## Email alerts

The first time a given IP is blocked on a given day (UTC), the **account owner** receives an email:

```
Subject: Blocked login attempt from a new IP

Hi <name>,
We just blocked an access attempt from 203.0.113.45.
If you recognise it, add it from Settings → Allowed IPs.
```

Subsequent blocks from the same IP within 30 days are suppressed — no spam. After 30 days, a fresh block triggers a new alert.

## Empty allowlist = no enforcement

If the feature is enabled on your plan but you haven't added any entries yet, **enforcement is off**. We treat an empty list as "everyone allowed" rather than "nobody allowed" so users don't accidentally lock themselves out by toggling the feature on without configuring it.

The first entry flips on enforcement immediately. Until then, every IP is allowed.

## Limits

- Up to **50 entries** per account (mix of single IPs + ranges).
- IPv4 only today. IPv6 ranges are on the roadmap.

## API errors and how to fix them

| Status | Code | Cause | Fix |
|--------|------|-------|-----|
| 402 | `feature_locked` | Plan doesn't include IP allowlisting | Upgrade your plan |
| 403 | `ip_blocked` | Request IP isn't on the allowlist | Add the IP, wait ~60s, retry |
| 400 | `Invalid IPv4 address` | Form-side validation rejected the input | Fix the IP and resubmit |
| 400 | `Range start must be ≤ range end` | Range endpoints out of order | Swap start and end |

## Mobile bypass

The Splashify Pro mobile apps and any custom client using the Expo SDK identify themselves with an `X-Platform` header (`ios` / `android` / `mobile` / `expo`). The IP gate short-circuits when this header is present so users on cellular networks aren't locked out by a rotating mobile IP.

The bypass is **not** exposed on the public API — `sk_live_…` keys, SMTP credentials, and GraphQL Bearer tokens are all gated regardless of headers.

## Best practices

- **Audit your list quarterly.** Old VPN exit IPs, decommissioned offices, and rotated cloud build agents accumulate quietly.
- **Use ranges sparingly.** A `/24` is fine for a stable office network; a `/16` defeats the purpose.
- **Pair with team-member-level permissions** so even users on the right network only see what they should.
- **Keep the mobile app installed** as a fallback — if you mistype an IP and lock yourself out, you can still reach the dashboard from the mobile app to fix it.


========================================================================
## Billing & Wallet
URL: https://docs.splashifypro.com/settings/billing
========================================================================

# Billing & Wallet

## Wallet

Your Splashify Pro wallet is a prepaid balance used to pay for:
- WhatsApp message costs (per conversation/message based on Meta pricing)
- RCS message costs
- WhatsApp calling (per minute)
- AI credits (for Chat AI Agent usage)

### Check Balance

Your current wallet balance is shown in the **top header bar** of the app.

### View Transactions

1. Go to **Wallet** in the sidebar
2. See all wallet transactions:
   - Recharges
   - Message deductions
   - Failed message refunds
   - AI credit purchases

### Recharge Wallet

1. Go to **Wallet**
2. Click **+ Add Balance**
3. Enter the amount you want to add
4. Complete payment via **Zoho Payments** (UPI, cards, net banking)
5. Balance reflects immediately after payment confirmation

## Billing Information

Set your billing address for invoice generation (required for GST invoices in India):

1. Go to **Settings → Billing**
2. Fill in:
   - Legal business name
   - GSTIN (if GST-registered)
   - Billing address
   - GST certificate upload
3. Click **Save**

## Invoices

Download monthly invoices:

1. Go to **Settings → Invoices**
2. Find the month you need
3. Click **Download PDF**

Invoices include:
- Itemized charges (messages, addons, plan)
- GST breakdown (for Indian businesses)
- Payment reference

## Low Balance Alert

When your wallet falls below a threshold, a **Low Balance Dialog** appears prompting you to recharge. You can also enable email alerts for low balance at **Settings → Notifications**.

## Plan-Based Pricing

Message costs vary based on your subscription plan:
- Higher-tier plans have lower per-message rates
- Check **Settings → Subscriptions** to compare plans

## Track Expenses

For a detailed breakdown of message costs by day:

1. Go to **Track Expenses** in the sidebar (or **Settings → Track Expenses**)
2. View:
   - Daily/weekly/monthly spend
   - Cost per message category (marketing, utility, auth)
   - Trend charts
   - Itemized billing log


========================================================================
## Canned Messages
URL: https://docs.splashifypro.com/settings/canned-messages
========================================================================

# Canned Messages

**Canned Messages** are pre-saved replies that agents can quickly insert during conversations — saving time on repetitive responses.

## Manage Canned Messages

Navigate to **Settings → Canned Messages**.

## Add a Canned Message

1. Click **+ Add Canned Message**
2. Enter:
   - **Shortcut** — The trigger keyword (e.g. `greeting`, `hours`, `refund`)
   - **Message** — The full text to insert
3. Click **Save**

## Use a Canned Message in a Conversation

1. Open a conversation in **Messages**
2. In the message input box, type `/` (forward slash)
3. A dropdown appears with matching canned messages
4. Continue typing to search by shortcut (e.g. `/greet`)
5. Click or press Enter to insert the canned message

The full message text is instantly inserted into the input field. You can edit it before sending.

## Edit or Delete

1. Go to **Settings → Canned Messages**
2. Click **Edit** next to the canned message to update
3. Click **Delete** to remove it

## Examples

| Shortcut | Message |
|----------|---------|
| `greeting` | "Hello! Welcome to Acme Support. How can I help you today? 😊" |
| `hours` | "Our support hours are Monday–Saturday, 9 AM – 6 PM IST." |
| `refund` | "We've initiated your refund. It will reflect in 3–5 business days." |
| `thanks` | "Thank you for contacting us! Is there anything else I can help you with?" |
| `escalate` | "I'm connecting you to our senior support team. Please hold on." |

## Tips

- Keep shortcuts short and memorable
- Use canned messages for FAQs, greetings, and common resolutions
- Update messages periodically to keep them accurate


========================================================================
## Developer Settings
URL: https://docs.splashifypro.com/settings/developer
========================================================================

# Developer Settings

Integrate Splashify Pro with your own applications using the **Public API**.

Navigate to **Settings → Developer**.

## API Key

### Generate an API Key

1. Go to **Settings → Developer**
2. Click **Generate Secret Key**
3. Copy the key immediately — it's only shown once

Your API key looks like:
```
sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

> **Keep your API key secret.** Anyone with this key can send messages and access your data.

### Regenerate a Key

If your key is compromised:
1. Go to **Settings → Developer**
2. Click **Regenerate Key**
3. Your old key is instantly invalidated
4. Copy and update the new key in all your integrations

## Public API

### Base URL

```
https://apis.splashifypro.com/api/v1/public/
```

### Authentication

Send your API key in the `Authorization` header:

```bash
Authorization: Bearer sk_live_YOUR_API_KEY
```

### Send a Message

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "type": "text",
    "text": "Hello from the API!"
  }'
```

### Send a Template Message

```bash
curl -X POST https://apis.splashifypro.com/api/v1/public/message \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "type": "template",
    "template_name": "order_shipped",
    "template_language": "en",
    "variables": ["John Doe", "ORD-12345"]
  }'
```

### Rate Limits

- **100 requests per minute** per API key
- Exceeding limits returns `429 Too Many Requests`

## Outbound Webhooks

Receive real-time events from Splashify Pro to your server.

### Configure a Webhook

1. Go to **Settings → Developer**
2. Click **+ Add Webhook**
3. Enter your webhook URL (must be HTTPS)
4. Select the events to subscribe to

### Webhook Events

| Event | Description |
|-------|-------------|
| `message.received` | New inbound message |
| `message.sent` | Outbound message sent |
| `message.delivered` | Message delivered |
| `message.read` | Message read by recipient |
| `message.failed` | Message delivery failed |
| `conversation.opened` | New conversation started |
| `conversation.resolved` | Conversation resolved |
| `contact.created` | New contact added |

### Webhook Payload

```json
{
  "event": "message.received",
  "timestamp": "2026-04-05T10:30:00Z",
  "data": {
    "message_id": "msg_xxxx",
    "conversation_id": "conv_xxxx",
    "from": "+919876543210",
    "text": "Hello!",
    "type": "text"
  }
}
```

### Opt-Out Error Toggle

Enable **Opt-Out Error Mode** to receive webhook errors for messages sent to opted-out contacts (instead of silently skipping them).

## Test Your Integration

Use the [API Playground](#) (coming soon) or tools like **Postman** or **curl** to test your API integration.


========================================================================
## Active Devices
URL: https://docs.splashifypro.com/settings/devices
========================================================================

# Active Devices

Monitor and control all active login sessions for your account.

Navigate to **Settings → Devices**.

## View Active Sessions

The Devices page shows all current active sessions:

| Column | Description |
|--------|-------------|
| **Device** | Browser and OS information |
| **IP Address** | The IP from which the session was created |
| **Last Seen** | Most recent activity timestamp |
| **Logged In** | When the session started |
| **Expiry** | Session expiration date (3 months from login) |
| **Current** | Badge indicating the current session |

## Remote Logout

To log out a device remotely:

1. Find the session you want to end
2. Click **Logout** next to it
3. Confirm

The session is invalidated immediately. The device will see a "Session expired" error on the next request.

## Device Limit

You can have up to **5 concurrent active sessions** per account. If you try to log in on a 6th device, a dialog appears asking you to revoke one of your existing sessions.

## Security Best Practice

Review your active devices periodically:
- Log out sessions you don't recognize
- Remove sessions from old or lost devices
- If you suspect unauthorized access, log out all other sessions and change your password

## Session Duration

Sessions last **3 months** by default. After 3 months, you'll be prompted to log in again. You can log out early at any time.


========================================================================
## Integrations
URL: https://docs.splashifypro.com/settings/integrations
========================================================================

# Integrations

Connect external tools and services to automate workflows and sync data with Splashify Pro.

Navigate to **Settings → Integrations**.

## Available Integrations

| Integration | Type | Use Case |
|-------------|------|---------|
| **Razorpay** | Payment Gateway | Trigger WhatsApp notifications on payment events |
| **Shopify** | E-Commerce | Send order updates, abandoned cart messages |
| **WooCommerce** | E-Commerce | Order and shipping notifications |
| **Webhook** | Custom | Receive events from any system via webhook |
| **Zoho CRM** | CRM | Sync contacts and trigger messages from Zoho |

## Generic Webhook Integration

The most flexible integration type — receive any webhook and trigger WhatsApp messages.

### How It Works

1. You configure an **inbound webhook URL** in Splashify Pro
2. Your external system sends POST requests to that URL
3. Splashify Pro maps the payload fields to a WhatsApp template
4. A message is sent to the customer

### Setup Steps

1. Go to **Settings → Integrations**
2. Click **+ New Integration**
3. Select **Webhook**
4. Configure:
   - **Integration Name** — e.g. "Shopify Order Updates"
   - **Incoming Webhook URL** — Copy this URL to your external system
   - **Template** — Select the WhatsApp template to send
   - **Variable Mapping** — Map webhook payload fields to template variables

### Variable Mapping Example

If your webhook payload is:
```json
{
  "customer_name": "John Doe",
  "order_id": "ORD-12345",
  "status": "Shipped"
}
```

Map:
- `{{1}}` → `customer_name`
- `{{2}}` → `order_id`
- `{{3}}` → `status`

### Testing

Use the **Test** button to send a sample payload and preview the message.

## E-Commerce Integrations

E-commerce integrations (Shopify, WooCommerce) automatically trigger messages for:

| Event | Message |
|-------|---------|
| Order confirmed | "Your order #\{order_id\} is confirmed!" |
| Order shipped | "Your order is on the way!" |
| Delivery complete | "Your order has been delivered." |
| Abandoned cart | "You left something in your cart..." |

### Connect Shopify

1. Select **Shopify** from the integrations list
2. Enter your **Shopify store URL**
3. Authorize the connection
4. Configure which events trigger messages
5. Map order data to your templates

## Webhook Connection Editor

For advanced integrations, the **Webhook Connection Editor** lets you:

- Map dynamic variables from any JSON payload
- Add conditional logic (only send if `status == "shipped"`)
- Preview the message before going live
- Test with sample payloads

Access via **Settings → Integrations → [Integration] → Configure Mapping**


========================================================================
## Invoices
URL: https://docs.splashifypro.com/settings/invoices
========================================================================

# Invoices

View and download your monthly invoices from **Settings → Invoices**.

## Invoice Contents

Each invoice includes:
- Invoice number and date
- Billing period
- Itemized charges:
  - Platform subscription fee
  - Message costs (marketing, utility, authentication)
  - Add-on charges (AI credits, calling minutes)
- GST breakdown (for Indian businesses)
- Total amount paid

## Download an Invoice

1. Go to **Settings → Invoices**
2. Find the month you need
3. Click **Download PDF**

## Sync Invoices

If invoices are not appearing:
1. Click **Sync Invoices**
2. Invoices are fetched from the billing system

## GST Invoices

For GST-compliant invoices:
1. Ensure your **GSTIN** is saved in **Settings → Billing**
2. Your GST number will appear on all future invoices
3. Past invoices can be regenerated after adding GSTIN — contact support

## Invoice Not Found?

Invoices are generated on the **1st of each month** for the previous month's usage. If you don't see an invoice:
- Check that billing info is complete
- Click **Sync Invoices**
- Contact support@splashifypro.in


========================================================================
## Opt-Out Management
URL: https://docs.splashifypro.com/settings/opt-management
========================================================================

# Opt-Out Management

Splashify Pro automatically handles opt-outs to keep you compliant with WhatsApp's messaging policies.

Navigate to **Settings → Opt Management**.

## How Opt-Outs Work

When a contact replies with an opt-out keyword:

| Keyword | Action |
|---------|--------|
| `STOP` | Contact is marked as opted-out |
| `Unsubscribe` | Contact is marked as opted-out |
| `No more` | Contact is marked as opted-out (if configured) |

Opted-out contacts are:
- **Excluded from all broadcast campaigns** automatically
- **Still able to initiate conversations** with you
- **Flagged** in their contact profile

## View Opted-Out Contacts

1. Go to **Settings → Opt Management**
2. See a list of all contacts who have opted out
3. Filter by date or search by name/phone

## Re-Opt-In

A contact can opt back in by messaging keywords like `START` or `Subscribe`. Once re-opted in, they can receive broadcast messages again.

You can also manually remove a contact from the opt-out list:
1. Find the contact
2. Click **Remove from Opt-Out**
3. Confirm

> Only re-add contacts who have explicitly requested to receive messages again. Adding contacts who haven't consented violates WhatsApp policy.

## Opt-Out in Broadcasts

All broadcasts automatically skip opted-out contacts — no manual filtering needed.

## Custom Opt-Out Keywords

Add custom keywords that trigger opt-out:

1. Go to **Settings → Opt Management**
2. Click **+ Add Keyword**
3. Enter the keyword (case-insensitive)

## Compliance Note

> Always include opt-out instructions in your marketing templates (e.g. "Reply STOP to unsubscribe"). This is required by WhatsApp's policy for marketing messages.


========================================================================
## Subscriptions
URL: https://docs.splashifypro.com/settings/subscriptions
========================================================================

# Subscriptions

Manage your active subscription plan and add-ons.

Navigate to **Settings → Subscriptions**.

## Your Current Plan

The Subscriptions page shows:
- **Plan name** and billing cycle (monthly / quarterly / yearly)
- **Plan expiry date**
- **Included features** (contacts limit, team members, templates)
- **Add-ons** currently active

## Upgrade or Change Plan

1. Go to **Plans** in the sidebar (or navigate to `/plans/whatsapp`)
2. Browse available plans
3. Click **Upgrade** or **Switch Plan**
4. Complete payment via Zoho Payments

## Plan Features

| Feature | Starter | Pro | Business | Enterprise |
|---------|---------|-----|---------|-----------|
| Contacts | 1,000 | 10,000 | 50,000 | Unlimited |
| Team Members | 2 | 5 | 15 | Unlimited |
| Broadcasts/month | 5 | 25 | Unlimited | Unlimited |
| AI Credits/month | 1,000 | 5,000 | 25,000 | Custom |
| WhatsApp Calling | ❌ | ✅ | ✅ | ✅ |
| API Access | ❌ | ✅ | ✅ | ✅ |

*Actual plan details depend on current pricing. Check the Plans page for up-to-date information.*

## Add-Ons

Purchase add-ons to extend your plan:

| Add-On | Description |
|--------|-------------|
| **Extra AI Credits** | Purchase additional AI agent credits |
| **Extra Contacts** | Increase your contact storage limit |
| **Extra Team Members** | Add more agents beyond plan limit |
| **WhatsApp Calling** | Enable voice calling capability |
| **RCS Messaging** | Enable RCS broadcast capability |

Add-ons auto-renew aligned to your plan's billing cycle.

## Cancel or Pause

To cancel your subscription, contact support@splashifypro.in. There is no self-service cancellation — this ensures your data and configuration are preserved.


========================================================================
## Team Members
URL: https://docs.splashifypro.com/settings/team
========================================================================

# Team Members

Add team members to collaborate on conversations, broadcasts, and account management.

Navigate to **Settings → Agents** (Team Members).

## Roles

| Role | Permissions |
|------|-------------|
| **Owner** | Full access — billing, settings, team management |
| **Admin** | All features except billing and plan changes |
| **Agent** | Conversations, contacts, broadcasts — no settings access |

## Invite a Team Member

1. Go to **Settings → Agents**
2. Click **+ Add Team Member**
3. Enter their **email address**
4. Select their **role**
5. Click **Send Invite**

The invited team member receives an email with a link to set their password and join the account.

## Team Member Login

After receiving the invite:
1. Click the invite link in the email
2. Go to `/auth/set-team-password`
3. Set a password
4. Log in at the standard login page

## Edit a Team Member

1. Find the team member in the list
2. Click **Edit**
3. Update their name or role
4. Click **Save**

## Remove a Team Member

1. Find the team member
2. Click **Remove**
3. Confirm

Removed team members lose access immediately. Their conversations remain in the inbox.

## Team Member Limits

The number of team members you can add depends on your subscription plan. Check **Settings → Subscriptions** for your current plan's team member limit.

## Conversation Assignment

Team members can be assigned to conversations from the Messages page. Only assigned agents see the conversation highlighted in their "Assigned to Me" filter.

## Organizations

If you manage multiple WhatsApp accounts (multiple WABAs), you can invite team members to specific organizations.

Go to **Settings → Organizations** to manage cross-account access.


========================================================================
## Business Username
URL: https://docs.splashifypro.com/settings/username
========================================================================

# Business Username

A **WhatsApp Business Username** is a unique handle that customers can use to find your business on WhatsApp (similar to a social media handle).

## What Is a Business Username?

Instead of sharing a phone number, you can share your username link:
```
https://wa.me/m/YourUsername
```

Customers can tap this link to start a WhatsApp conversation with your business directly.

## Set Your Username

1. Go to **Settings → Username**
2. Enter your desired username:
   - Lowercase letters, numbers, and dots/underscores only
   - 5–32 characters
   - Must be unique on WhatsApp
3. Click **Save**

Username changes go through Meta's approval process via the Graph API.

## Username Availability

If the username is taken, try:
- Adding your city: `acmemumbai`
- Adding your industry: `acmefashion`
- Using a variation: `shopwithacme`

## Update Username

You can change your username, but frequent changes may cause a review delay.

1. Go to **Settings → Username**
2. Edit the current username
3. Click **Update**

> Username changes require Meta approval and may take up to **24 hours**.


========================================================================
## Analytics
URL: https://docs.splashifypro.com/analytics
========================================================================

# Analytics

The **Analytics** section gives you visibility into your messaging volume, conversation trends, and team performance.

Navigate to **Analytics** in the sidebar, or go to:

```
https://app.splashifypro.com/analytics
```

## Analytics Dashboard

The main analytics page shows:

### Message Summary

| Metric | Description |
|--------|-------------|
| **Total Messages** | All messages sent and received |
| **Inbound Messages** | Messages received from contacts |
| **Outbound Messages** | Messages sent by your team/bots |
| **Broadcast Messages** | Messages sent via broadcast campaigns |
| **Template Messages** | Template-based messages sent |

### Conversation Stats

| Metric | Description |
|--------|-------------|
| **Total Conversations** | All conversation threads |
| **New Conversations** | First-time contacts |
| **Resolved** | Conversations closed |
| **Average Response Time** | Average time for first reply |

### Time Range Filters

Filter analytics by:
- Today
- Last 7 days
- Last 30 days
- Last 90 days
- Custom date range

### Trend Charts

View message volume trends as line charts:
- Daily message volume
- Conversation open/close rate
- Broadcast reach over time

## Activity Logs

View a detailed log of all actions taken by your team:

1. Go to **Activity Logs** in the sidebar
2. Filter by:
   - Date range
   - Action type
   - Team member
3. See who did what and when


========================================================================
## CTWA Ads
URL: https://docs.splashifypro.com/analytics/ctwa
========================================================================

# CTWA Ads (Click-to-WhatsApp)

**Click-to-WhatsApp (CTWA)** ads let customers start a WhatsApp conversation with your business directly from a Facebook or Instagram ad.

## Navigate to CTWA Settings

Go to **Settings → CTWA Ads** or:

```
https://app.splashifypro.com/settings/ctwa
```

## How CTWA Works

1. Customer sees your Facebook/Instagram ad
2. They click the **"Send Message"** or **"WhatsApp"** button
3. WhatsApp opens a conversation with your business
4. A message is automatically sent identifying the ad source
5. Splashify Pro logs the ad source and can trigger a dedicated chatbot flow

## Connect Meta Ads

1. Go to **Settings → CTWA Ads**
2. Click **Connect Meta Account**
3. Complete the Facebook OAuth flow
4. Select your **Ad Account**
5. Your ads are synced and listed

## CTWA Ads Dashboard

After connecting, the CTWA dashboard shows:

| Metric | Description |
|--------|-------------|
| **Ad Name** | The Facebook/Instagram ad name |
| **Impressions** | How many times the ad was shown |
| **Clicks** | How many people clicked the WhatsApp button |
| **Conversations Started** | How many actually messaged you |
| **Conversion Rate** | Clicks → Conversations percentage |

## CAPI Integration (Conversion API)

Connect Meta's **Conversions API (CAPI)** to track conversion events back to Meta for better ad optimization:

1. Go to **Settings → CTWA Ads**
2. Click **Configure CAPI**
3. Enter your **Meta Pixel ID** and **CAPI Access Token**
4. Enable the events to track:
   - `ViewContent` — Customer viewed a product
   - `Lead` — Contact added a tag like "lead"
   - `Purchase` — Customer made a payment

CAPI events are sent to Meta automatically when the configured conditions are met.

## CTWA + Chatbot Flow

Combine CTWA with Workflow Bots for automatic lead handling:

1. Create a Workflow Bot with the **On Message** trigger
2. Select **For Specific Ads** and enter the ad's Source ID
3. When a customer clicks your ad and messages you, the bot automatically engages them with a personalized flow

This lets you:
- Greet customers with context about which ad they clicked
- Qualify leads automatically
- Route to the right team member based on ad campaign

See [Workflow Bots](/ai-agents/workflow-bot) for setup instructions.


========================================================================
## Track Expenses
URL: https://docs.splashifypro.com/analytics/expenses
========================================================================

# Track Expenses

The **Track Expenses** page gives you a detailed breakdown of your messaging spend.

Navigate to **Track Expenses** in the sidebar, or go to **Settings → Track Expenses**.

## Expense Summary

The top of the page shows summary cards:

| Card | Description |
|------|-------------|
| **Total Spent** | Total wallet deductions in the period |
| **Marketing** | Costs for marketing template messages |
| **Utility** | Costs for utility template messages |
| **Authentication** | Costs for auth/OTP messages |
| **Service** | Costs for free-form messages within 24h window |

## Expense Trends

A line chart shows your daily spend over the selected period. Use this to:
- Identify high-cost days (e.g. after a large broadcast)
- Monitor cost trends month-over-month
- Forecast upcoming spend

## Billing Log

The detailed billing log table shows every individual deduction:

| Column | Description |
|--------|-------------|
| Date | When the deduction occurred |
| Type | Message category (marketing, utility, service, auth) |
| Contact | The contact the message was sent to |
| Template | Template used (for template messages) |
| Amount | Cost deducted from wallet (in INR) |
| Status | Charged / Refunded |

## Filters

Filter the expense log by:
- **Date range** — From/To dates
- **Message type** — Marketing / Utility / Auth / Service
- **Status** — Charged / Refunded

## Failed Message Refunds

When a message fails to deliver, the cost is automatically refunded. Refunds appear in the billing log with status **Refunded**.

> Refunds typically process within **24 hours** of the failure.

## Export

Use the billing log data for accounting and reconciliation. CSV export is available via the download button above the table.

## Cost Optimization Tips

| Tip | Impact |
|-----|--------|
| Use Utility templates instead of Marketing when possible | Lower per-message cost |
| Segment broadcasts to active contacts only | Reduce wasted sends |
| Reply within 24h to customer messages | Free-form messages are cheaper |
| Monitor delivery rates and fix issues | Fewer failures = fewer refunds needed |


========================================================================
## Support Tickets
URL: https://docs.splashifypro.com/support
========================================================================

# Support Tickets

Get help from the Splashify Pro team by raising a support ticket directly from your dashboard.

## Navigate to Support

Click **Support** in the left sidebar, or go to:

```
https://app.splashifypro.com/support
```

## Create a Ticket

1. Go to **Support**
2. Click **+ New Ticket**
3. Fill in the form:
   - **Subject** — Brief description of the issue
   - **Category** — Billing / Technical / Feature Request / Other
   - **Priority** — Low / Medium / High / Urgent
   - **Description** — Detailed explanation of the issue
   - **Attachments** — Screenshots or files (optional)
4. Click **Submit Ticket**

## Ticket Statuses

| Status | Meaning |
|--------|---------|
| **Open** | Ticket submitted, awaiting response |
| **In Progress** | Support team is working on it |
| **Waiting for Reply** | Team has responded, awaiting your reply |
| **Resolved** | Issue has been addressed |
| **Closed** | Ticket closed (after resolution or inactivity) |

## View and Reply to a Ticket

1. Click on any ticket in the list to open it
2. View the full conversation thread
3. Click **Reply** to add your response
4. Attach files if needed
5. Submit the reply

## Ticket List

The support list shows all your tickets with:
- Ticket ID
- Subject
- Status
- Priority
- Created date
- Last update

## SLA (Response Time)

| Priority | First Response Target |
|----------|-----------------------|
| Urgent | Within 2 hours |
| High | Within 4 hours |
| Medium | Within 8 hours |
| Low | Within 24 hours |

*Response times are during business hours (Monday–Saturday, 9 AM – 6 PM IST)*

## Self-Help Resources

Before raising a ticket, check:
- This documentation — search for your issue
- The FAQ at [help.splashifypro.com](#) (coming soon)
- Known issues / status page at [status.splashifypro.com](#) (coming soon)

## Direct Contact

For urgent issues:
- **Email:** support@splashifypro.in
- **WhatsApp:** Message us at the number displayed in your dashboard footer


========================================================================
## Reseller Panel
URL: https://docs.splashifypro.com/reseller-panel
========================================================================

# Reseller Panel

The Reseller Panel is your command center for running a white-label WhatsApp Business platform. As a reseller, you purchase plans at wholesale prices, set your own markup, and offer a fully branded experience to your clients.

## What You Can Do

- **Manage Clients** — View, search, and manage all clients registered under your reseller account
- **Set Pricing** — Customize plan prices, add-ons, and conversation markup above wholesale rates
- **Create Coupons** — Offer discounts to your clients with flexible coupon rules
- **White-Label Branding** — Upload your logo, set brand colors, and customize the entire app experience
- **Custom Domain** — Connect your own domain with automatic SSL certificate management
- **Payment Gateways** — Configure Razorpay, PhonePe, or PayU to collect payments directly
- **Support Tickets** — Handle client support tickets from a unified dashboard
- **Track Revenue** — Monitor subscription profit, message markup earnings, and wallet balance

## Panel URL

| Portal | URL |
|--------|-----|
| Reseller Panel | `https://panel.splashifypro.com` |
| Your Clients' App | `https://app.splashifypro.com` or your custom domain |

## Sections

1. **[Getting Started](/reseller-panel/getting-started)** — Log in, navigate the panel, and understand the basics
2. **[Dashboard](/reseller-panel/dashboard)** — Overview of your business metrics and KPIs
3. **[Clients](/reseller-panel/clients)** — Manage your client accounts
4. **[Plans & Pricing](/reseller-panel/plans)** — Set selling prices for platform plans
5. **[Add-Ons](/reseller-panel/addons)** — Create and manage add-on products
6. **[Coupons](/reseller-panel/coupons)** — Create discount codes for your clients
7. **[Markup Settings](/reseller-panel/markup)** — Configure conversation and billing markup
8. **[Wallet](/reseller-panel/wallet)** — Monitor your reseller wallet balance and transactions
9. **[Settlements](/reseller-panel/settlements)** — Track message markup profit payouts
10. **[Support Tickets](/reseller-panel/tickets)** — Respond to client support requests
11. **[Branding](/reseller-panel/branding)** — Customize the look and feel for your clients
12. **[Custom Domain & SSL](/reseller-panel/domain)** — Connect your own domain
13. **[Integrations](/reseller-panel/integrations)** — Set up payment gateways, email, and Google login
14. **[Profile & Security](/reseller-panel/profile)** — Manage your account and enable 2FA

> **How Reseller Pricing Works:** You pay the **wholesale price** for each plan. You set a **selling price** that your clients pay. The difference is your profit. Message markup works similarly — you set a percentage above the platform's base conversation cost.


========================================================================
## Add-Ons
URL: https://docs.splashifypro.com/reseller-panel/addons
========================================================================

# Add-Ons

Add-ons are optional products your clients can purchase on top of their subscription plan. You create add-ons based on platform base add-ons and set your own pricing.

## Viewing Add-Ons

The add-ons table displays:

| Column | Description |
|--------|-------------|
| **Name** | Add-on display name |
| **Type** | Product type (e.g., agent, credits) |
| **Billing Cycle** | Monthly, Quarterly, or Yearly |
| **Wholesale Price** | Your cost |
| **Selling Price** | What your clients pay |
| **Status** | Active or Inactive |
| **Actions** | Edit and Delete buttons |

## Creating an Add-On

1. Click **Create Add-On**
2. Select a **base add-on** from the platform catalog
3. Set your **selling price** (must be >= wholesale price)
4. Configure optional fields:
   - **Custom name** — Override the default add-on name
   - **Description** — Help text shown to clients
   - **Tax name and percentage** — Applied during checkout
5. Toggle **Active** to make it available to clients
6. Click **Save**

## Editing an Add-On

Click the **edit icon** to modify:
- Name and description
- Selling price
- Tax settings
- Active/Inactive status

## Deleting an Add-On

Click the **delete icon** to remove an add-on. This does not affect clients who already purchased it — their existing add-on subscriptions remain active until expiry.

## Pricing

Add-on pricing follows the same model as plans:

```
Client pays:    Your Selling Price
You pay:        Wholesale Price
Your profit:    Selling Price - Wholesale Price
```

The wholesale cost is deducted from your reseller wallet when a client purchases the add-on.

> **Note:** Add-on billing cycles automatically match the client's plan billing cycle. If a client is on a quarterly plan, the add-on price is multiplied by 3 months.


========================================================================
## Branding
URL: https://docs.splashifypro.com/reseller-panel/branding
========================================================================

# Branding

The Branding page lets you fully customize what your clients see when they use the app. Every visual element — logo, colors, favicon, and links — can be tailored to your brand.

## Brand Customization

### Visual Identity

| Setting | Description | Requirements |
|---------|-------------|-------------|
| **Logo** | Displayed in the sidebar and login pages | PNG, JPG, or SVG. Max 2MB. Recommended: square, 200x200px |
| **Favicon** | Browser tab icon | PNG or ICO. Max 2MB. Recommended: 32x32px |
| **App QR Code** | QR code image shown to clients | PNG or JPG. Max 2MB |
| **Brand Name** | Your company name (replaces "Splashify Pro" everywhere) | Text |
| **Brand Color** | Primary color used throughout the app | Hex code (e.g., `#1B70FF`) |

### Contact Information

| Setting | Description |
|---------|-------------|
| **Support Email** | Shown in the app header and support pages |
| **Support Phone** | Contact number for your clients |

## Dashboard Quick Links

These links appear as cards on your clients' dashboard:

| Link | Purpose |
|------|---------|
| **Schedule Live Demo** | URL to your demo booking page (e.g., Calendly) |
| **Setup Guide** | URL to your onboarding documentation |
| **Watch Tutorials** | URL to your video tutorial playlist |
| **Postman Collection** | URL to your API documentation |

Leave any link empty to hide that card from the dashboard.

## Legal Links

Shown on the signup page and footer:

| Link | Purpose |
|------|---------|
| **Terms of Service** | URL to your terms and conditions |
| **Privacy Policy** | URL to your privacy policy |

## How Branding Appears

When branding is configured, your clients see:

- **Login/Signup pages** — Your logo and brand name instead of Splashify Pro
- **Sidebar** — Your logo and brand name
- **Browser tab** — Your favicon and brand name as the page title
- **App header** — Your support email
- **All blue UI elements** — Automatically recolored to your brand color
- **Dashboard** — Your quick links as action cards

## Uploading Assets

1. Click the upload area or drag and drop your file
2. Supported formats: PNG, JPG, SVG (logo), PNG/ICO (favicon)
3. Maximum file size: 2MB per file
4. Images are stored securely and served via CDN

## Saving Changes

Click **Save Branding** to apply all changes. Branding updates are cached for 1 hour, so clients may need to hard-refresh their browser to see changes immediately.

> **Tip:** Test your branding by opening your app URL in an incognito window. This ensures you see the experience exactly as your clients do, without any cached data.


========================================================================
## Clients
URL: https://docs.splashifypro.com/reseller-panel/clients
========================================================================

# Clients

The Clients page shows every user who signed up through your white-label app. You can search, view details, and manage their accounts.

## Client List

The main table displays:

| Column | Description |
|--------|-------------|
| **Name** | Client's first and last name |
| **Email** | Registered email address |
| **Company** | Business or company name |
| **Plan** | Current subscription plan name and status |
| **WABA** | Whether they have a WhatsApp Business Account connected |
| **Joined** | Date the client registered |
| **Status** | Account status (Active, Inactive, or Pending) |

### Searching Clients

Use the search bar at the top to find clients by:
- Name
- Email
- Company name
- Phone number
- WABA ID

## Client Detail Page

Click **View** on any client to open their full profile. The detail page shows:

### Profile Information
- Full name, email, mobile number
- Company name and industry
- Country and timezone
- Email and mobile verification status

### Subscription Details
- Current plan name and billing cycle
- Plan status (Active, Expired, Trial, None)
- Plan purchase and expiry dates
- Trial end date (if applicable)

### WABA Information
- Connected WABA ID and phone number
- WABA status and provider type
- Phone number ID

### Wallet
- Current wallet balance
- Recent billing transactions

## How Clients Join

Clients register through your branded app:

1. If you have a **custom domain** (e.g., `app.yourbrand.com`), clients sign up there
2. If not, clients sign up at `app.splashifypro.com` and are automatically linked to your reseller account based on the domain or referral

When a client signs up on your custom domain:
- They see your branding (logo, colors, brand name)
- They can only see plans you've configured
- Payments go through your payment gateway
- Support tickets are routed to you

> **Note:** You cannot create client accounts manually. Clients must self-register through the app. You can, however, manage their subscriptions and account status after they sign up.


========================================================================
## Coupons
URL: https://docs.splashifypro.com/reseller-panel/coupons
========================================================================

# Coupons

Create discount coupon codes that your clients can apply during plan checkout. Coupons support percentage or fixed-amount discounts with flexible targeting rules.

## Viewing Coupons

The coupons table shows:

| Column | Description |
|--------|-------------|
| **Code** | The coupon code clients enter at checkout |
| **Discount** | Amount or percentage off |
| **Plans** | Which plans the coupon applies to (or "All Plans") |
| **Billing Cycles** | Applicable cycles (or "All Cycles") |
| **Usage** | Current uses / maximum uses |
| **Expires** | Expiration date |
| **Status** | Active or Inactive |

## Creating a Coupon

Click **Create Coupon** and fill in:

### Required Fields

| Field | Description |
|-------|-------------|
| **Coupon Code** | Unique code (auto-uppercased, e.g., `WELCOME50`) |
| **Discount Type** | `Percentage` or `Fixed Amount` |
| **Discount Value** | Percentage (1-100) or fixed amount in ₹ |

### Optional Fields

| Field | Description |
|-------|-------------|
| **Description** | Internal note about the coupon's purpose |
| **Applicable Plans** | Restrict to specific plans (leave empty for all plans) |
| **Billing Cycles** | Restrict to Monthly, Quarterly, or Yearly (leave empty for all) |
| **Max Uses** | Maximum number of times the coupon can be used (0 = unlimited) |
| **Expiration Date** | Coupon expires after this date |
| **Active** | Toggle to enable or disable the coupon |

## How Coupons Work at Checkout

1. Client selects a plan on the pricing page
2. Client enters the coupon code in the discount field
3. System validates the coupon:
   - Is the code valid and active?
   - Does it apply to this plan and billing cycle?
   - Has the usage limit been reached?
   - Has the coupon expired?
4. If valid, the discount is applied to the plan's selling price (before tax)
5. Tax is recalculated on the discounted amount

### Discount Calculation

**Percentage discount:**
```
Discounted Price = Selling Price - (Selling Price x Discount% / 100)
Tax = Discounted Price x Tax% / 100
Total = Discounted Price + Tax
```

**Fixed amount discount:**
```
Discounted Price = Selling Price - Fixed Amount
Tax = Discounted Price x Tax% / 100
Total = Discounted Price + Tax
```

If the discount exceeds the selling price, the total is capped at ₹0 (free plan).

## Editing and Deleting Coupons

- Click the **edit icon** to modify any coupon field
- Click the **delete icon** to permanently remove a coupon
- Toggle **Active/Inactive** to temporarily disable a coupon without deleting it

## Global Coupons

If the platform admin has created global coupons, those also work for your clients as a fallback. Your reseller-specific coupons are checked first.

> **Tip:** Use coupons strategically — offer first-month discounts to new clients, or create loyalty codes for renewals. Track usage in the coupons table to measure effectiveness.


========================================================================
## Dashboard
URL: https://docs.splashifypro.com/reseller-panel/dashboard
========================================================================

# Dashboard

The dashboard provides a real-time overview of your reseller business performance.

## Key Metrics

The top row shows four headline numbers:

| Metric | Description |
|--------|-------------|
| **Total Clients** | Number of users registered under your reseller account |
| **Active Subscriptions** | Clients currently on a paid plan |
| **Wallet Balance** | Your available reseller wallet balance |
| **Open Tickets** | Support tickets awaiting your response |

Below the client count, you'll see how many new clients joined this month.

## Revenue Breakdown

The second row breaks down your earnings:

| Metric | How It's Calculated |
|--------|-------------------|
| **Messages Sent** | Total charged messages across all clients in the last 30 days |
| **Subscription Profit** | (Your selling price - wholesale price) x number of active clients per plan |
| **Message Profit** | Sum of your markup on every message billed in the last 30 days |
| **Total Profit** | Subscription profit + message profit |

### Example

If you sell a plan at ₹500/month with a wholesale cost of ₹200, and you have 10 active clients on that plan:

- Subscription Profit = (₹500 - ₹200) x 10 = **₹3,000/month**

If your WhatsApp marketing markup is 20% and the base cost is ₹0.80 per conversation, clients pay ₹0.96. For 5,000 messages:

- Message Profit = (₹0.96 - ₹0.80) x 5,000 = **₹800**

## Trend Charts (Last 30 Days)

Four interactive charts show daily trends:

1. **Messages Sent** — Bar chart of daily message volume across all clients
2. **Message Profit** — Area chart showing daily markup earnings
3. **New Clients** — Bar chart of daily client signups
4. **Wallet Recharges** — Area chart of your wallet top-ups

Hover over any data point to see the exact value for that day.

## Quick Links

If you've configured dashboard links in [Branding](/reseller-panel/branding), they appear as clickable cards:

- **Schedule Live Demo** — Link to your demo booking page
- **Setup Guide** — Link to your onboarding documentation
- **Watch Tutorials** — Link to your video tutorials

## Refreshing Data

Click the **Refresh** button in the top-right corner to reload all dashboard data.


========================================================================
## Custom Domain & SSL
URL: https://docs.splashifypro.com/reseller-panel/domain
========================================================================

# Custom Domain & SSL

Connect your own domain (e.g., `app.yourbrand.com`) so your clients access the platform under your brand. The system automatically handles SSL certificate generation and renewal.

## Connecting a Domain

### Step 1: Enter Your Domain

1. Go to **Domain** in the sidebar
2. Enter your custom domain (e.g., `app.yourbrand.com`)
3. Click **Connect Domain**

### Step 2: Configure DNS Records

You'll need to add two DNS records at your domain registrar (GoDaddy, Cloudflare, Namecheap, etc.):

**CNAME Record** — Routes traffic to the platform:

| Type | Name | Value |
|------|------|-------|
| CNAME | `app` (or your subdomain) | `app.splashifypro.com` |

**TXT Record** — Verifies domain ownership:

| Type | Name | Value |
|------|------|-------|
| TXT | `_splashify-verify` | (shown on the domain page) |

### Step 3: Verify DNS

After adding the DNS records:
1. Wait for DNS propagation (usually 5-30 minutes, up to 48 hours)
2. Click **Verify DNS** on the domain page
3. The system checks both CNAME and TXT records

Once verified, the domain status changes to **Verified**.

## SSL Certificate

After domain verification, SSL is managed automatically:

### SSL Status

| Status | Meaning |
|--------|---------|
| **None** | No SSL certificate yet |
| **Generating** | Certificate is being issued |
| **Active** | Certificate is valid and serving HTTPS |
| **Failed** | Generation failed — check DNS records |

### SSL Details

- **Issued Date** — When the certificate was generated
- **Expiry Date** — Certificates are valid for 90 days
- **Auto-Renew** — Toggle automatic renewal (recommended: keep on)

### Manual Regeneration

If SSL generation fails or you need to regenerate:
1. Ensure DNS records are correct
2. Click **Regenerate SSL**
3. Wait for the certificate to be issued (typically 1-2 minutes)

## Disconnecting a Domain

1. Click **Disconnect Domain**
2. Type `DELETE` in the confirmation field
3. Click **Confirm**

This removes the domain association and SSL certificate. Your clients will need to use the default platform URL.

## What Changes with a Custom Domain

| Feature | Without Custom Domain | With Custom Domain |
|---------|----------------------|-------------------|
| App URL | `app.splashifypro.com` | `app.yourbrand.com` |
| Login restriction | Clients can log in from any domain | Clients registered on your domain can only log in there |
| Google OAuth | Uses platform Google client ID | Uses your Google OAuth client ID (if configured) |
| SSL | Managed by platform | Auto-generated for your domain |

## Troubleshooting

### DNS Not Propagated
- Wait up to 48 hours for full propagation
- Use [dnschecker.org](https://dnschecker.org) to check if your records are visible globally

### SSL Generation Failed
- Verify your CNAME record points to the correct target
- Ensure no CAA records on your domain block Let's Encrypt
- Try regenerating after confirming DNS is correct

### Clients Can't Access Custom Domain
- Check that the CNAME record is correctly configured
- Ensure SSL status is "Active"
- Clear browser cache and try in incognito mode

> **Tip:** Use a subdomain like `app.yourbrand.com` rather than your root domain. Root domains cannot have CNAME records in most DNS providers.


========================================================================
## Getting Started
URL: https://docs.splashifypro.com/reseller-panel/getting-started
========================================================================

# Getting Started

This guide walks you through logging into the reseller panel and understanding the interface.

## Logging In

1. Go to [panel.splashifypro.com](https://panel.splashifypro.com)
2. Enter your **email** and **password** provided during reseller onboarding
3. If you have 2FA enabled, enter your authenticator code when prompted
4. Click **Sign In**

You can also sign in with **Google** if your account is linked.

### Forgot Password

1. Click **Forgot password?** on the login page
2. Enter your registered email
3. Check your inbox for a reset link
4. Set a new password (minimum 8 characters)

## Panel Navigation

The sidebar on the left gives you access to every feature:

| Menu Item | What It Does |
|-----------|-------------|
| **Dashboard** | Business overview with stats and charts |
| **Clients** | View and manage all your client accounts |
| **Plans** | Customize plan pricing for your clients |
| **Add-Ons** | Create and manage add-on products |
| **Coupons** | Create discount codes |
| **Tickets** | Handle client support requests |
| **Wallet** | View balance and transaction history |
| **Markup** | Set conversation and billing markup |
| **Integrations** | Payment gateways, email, Google OAuth |
| **Settlements** | Track message profit payouts |
| **Branding** | Customize logo, colors, and links |
| **Domain** | Connect your custom domain |
| **Profile** | Account settings and 2FA |

## First Steps After Login

1. **Set up branding** — Upload your logo and set your brand color so clients see your brand, not Splashify Pro
2. **Configure a payment gateway** — Set up Razorpay, PhonePe, or PayU so clients can pay you directly
3. **Customize plan pricing** — Review the wholesale prices and set your selling prices
4. **Connect a custom domain** (optional) — Point your domain to the platform for a fully white-labeled experience
5. **Recharge your wallet** — Ensure you have enough balance to cover wholesale costs when clients subscribe

> **Important:** Your reseller wallet must have sufficient balance to cover the wholesale cost whenever a client purchases a plan. If your wallet is empty, client purchases will fail.


========================================================================
## Integrations
URL: https://docs.splashifypro.com/reseller-panel/integrations
========================================================================

# Integrations

The Integrations page lets you connect external services that power your white-label platform. These include payment processing, email delivery, and authentication providers.

## Payment Gateways

You need at least one active payment gateway so your clients can pay for plans and wallet recharges. Three providers are supported:

### Razorpay

| Field | Description |
|-------|-------------|
| **Key ID** | Your Razorpay API Key ID (starts with `rzp_`) |
| **Key Secret** | Your Razorpay API Key Secret |
| **Webhook Secret** | Secret for verifying Razorpay webhook signatures |

### PhonePe

| Field | Description |
|-------|-------------|
| **Merchant ID** | Your PhonePe Merchant ID |
| **Salt Key** | Your PhonePe Salt Key |
| **Webhook Secret** | Secret for verifying PhonePe callbacks |

### PayU

| Field | Description |
|-------|-------------|
| **Merchant Key** | Your PayU Merchant Key |
| **Salt** | Your PayU Salt value |

### Managing Gateways

- Click **Add** to configure a new gateway
- Click **Update** to modify existing credentials
- Click the **delete icon** to remove a gateway
- Set one gateway as **Default** — this is used when clients make payments

> **Important:** You must have at least one active payment gateway for clients to purchase plans. Without it, the checkout process will fail.

## Google OAuth 2.0

Let your clients sign up and log in with their Google account on your white-labeled app.

### Setup

| Field | Description |
|-------|-------------|
| **Google Client ID** | Your Google OAuth 2.0 Client ID |

### How to Get a Google Client ID

1. Go to [Google Cloud Console](https://console.cloud.google.com)
2. Create a new project or select an existing one
3. Navigate to **APIs & Services > Credentials**
4. Click **Create Credentials > OAuth 2.0 Client ID**
5. Set application type to **Web application**
6. Add your domain to **Authorized JavaScript origins**:
   - `https://app.yourdomain.com` (your custom domain)
   - `https://app.splashifypro.com` (platform domain)
7. Add to **Authorized redirect URIs**:
   - `https://app.yourdomain.com`
   - `https://app.splashifypro.com`
8. Copy the Client ID and paste it in the integration settings

Once configured, your clients see a **Continue with Google** button on login/signup pages that uses your Google project, showing your brand name in the Google consent screen.

## SMTP Email

Configure a custom SMTP server to send transactional emails (OTP verification, ticket notifications, password resets) from your own email address.

### Settings

| Field | Description |
|-------|-------------|
| **SMTP Host** | Email server hostname (e.g., `smtp.gmail.com`) |
| **SMTP Port** | Server port (587 for TLS, 465 for SSL) |
| **Username** | SMTP login username (usually your email) |
| **Password** | SMTP login password or app-specific password |
| **From Name** | Sender name shown in emails (e.g., "WppBot Support") |
| **From Email** | Sender email address |
| **Enabled** | Toggle to activate SMTP |

### Testing

After saving SMTP settings, click **Send Test Email** to verify the configuration. A test email is sent to your registered email address.

### Common SMTP Providers

| Provider | Host | Port |
|----------|------|------|
| Gmail | `smtp.gmail.com` | 587 |
| Outlook | `smtp-mail.outlook.com` | 587 |
| Zoho | `smtp.zoho.com` | 587 |
| SendGrid | `smtp.sendgrid.net` | 587 |

> **Gmail Note:** If using Gmail, you need to create an [App Password](https://myaccount.google.com/apppasswords) — your regular Gmail password won't work.

## WhatsApp OTP

Send OTP verification codes to clients via WhatsApp during signup and login.

### Settings

| Field | Description |
|-------|-------------|
| **Phone Number ID** | Your WhatsApp Business phone number ID |
| **Access Token** | Permanent access token from Meta Developer Portal |
| **Template Name** | Name of the approved OTP template |
| **Language Code** | Template language (e.g., `en_US`) |

### Testing

Click **Send Test OTP** to verify the configuration works. An OTP message is sent to a test number.

> **Note:** WhatsApp OTP requires an approved message template on your WABA. Contact the platform admin if you need help setting this up.


========================================================================
## Markup Settings
URL: https://docs.splashifypro.com/reseller-panel/markup
========================================================================

# Markup Settings

Markup settings control how much extra your clients pay for WhatsApp and RCS conversations on top of the platform's base cost, and the default tax applied to transactions.

## WhatsApp Conversation Markup

Every WhatsApp conversation has a cost based on the category (Marketing, Utility, or Authentication). You can add a markup percentage so your clients pay more, and the difference is your profit.

### How It Works

```
Base Cost (set by Meta/platform):     ₹0.80 per marketing conversation
Your Markup:                          +20%
Client Pays:                          ₹0.96 per marketing conversation
Your Profit:                          ₹0.16 per conversation
```

### Settings

| Field | Description |
|-------|-------------|
| **Enable WhatsApp Markup** | Toggle to activate conversation markup |
| **Marketing Markup %** | Extra percentage on marketing conversations |
| **Utility Markup %** | Extra percentage on utility conversations |
| **Auth Markup %** | Extra percentage on authentication conversations |

These are **global defaults**. You can override markup percentages on a per-plan basis in [Plans & Pricing](/reseller-panel/plans).

## RCS Markup

If your clients use RCS messaging, you can set a separate markup:

| Field | Description |
|-------|-------------|
| **Enable RCS Markup** | Toggle to activate RCS markup |
| **RCS Markup %** | Percentage added to RCS message costs |

The page shows the current **wholesale cost** and the **calculated client charge** based on your markup percentage.

## Customer Billing Tax (GST)

Set a default tax that applies to client transactions:

| Field | Description |
|-------|-------------|
| **Tax Name** | Label shown on invoices (e.g., "IGST", "GST") |
| **Tax Percentage** | Tax rate (e.g., 18 for 18% GST) |

This tax is applied as the default for:
- Plan subscriptions (if the plan doesn't have its own tax setting)
- Add-on purchases
- Wallet recharges

Individual plans and add-ons can override this with their own tax settings.

## Saving Changes

Click **Save Settings** to apply your changes. The new markup takes effect immediately for all future conversations and transactions.

> **Note:** Markup changes only affect future messages. Messages already billed retain their original cost.


========================================================================
## Plans & Pricing
URL: https://docs.splashifypro.com/reseller-panel/plans
========================================================================

# Plans & Pricing

The Plans page lets you set your own selling prices for platform plans. Each plan has a **wholesale price** (what you pay) and a **selling price** (what your clients pay). The difference is your profit.

## How Plan Pricing Works

```
Client pays:    Selling Price (set by you)
You pay:        Wholesale Price (set by platform admin)
Your profit:    Selling Price - Wholesale Price
```

For example:
- Wholesale Price: ₹200/month
- Your Selling Price: ₹500/month
- **Your Profit: ₹300/month per client**

## Viewing Plans

The plans table shows:

| Column | Description |
|--------|-------------|
| **Plan Name** | Name displayed to your clients |
| **Billing Cycle** | Monthly, Quarterly, or Yearly |
| **Wholesale Price** | Your cost (set by the platform) |
| **Your Price** | What your clients will pay |
| **Actions** | Edit button to customize |

Plans with a **Customized** badge have been modified from the platform defaults.

## Customizing a Plan

Click the **edit icon** on any plan to open the customization modal:

### Editable Fields

| Field | Description |
|-------|-------------|
| **Plan Name** | Rename the plan for your clients |
| **Selling Price** | Must be equal to or greater than the wholesale price |
| **Tax Name** | Tax label shown on invoices (e.g., "GST", "IGST") |
| **Tax Percentage** | Tax rate applied on top of selling price |
| **Marketing Markup %** | Per-plan override for WhatsApp marketing conversation markup |
| **Utility Markup %** | Per-plan override for WhatsApp utility conversation markup |
| **Auth Markup %** | Per-plan override for WhatsApp authentication conversation markup |

### Conversation Markup

Per-plan markup overrides let you charge different conversation rates for different plans. If set to 0, the global markup from [Markup Settings](/reseller-panel/markup) is used.

For example, you might offer lower conversation rates on premium plans to incentivize upgrades.

## Pricing Rules

- Selling price **must be >= wholesale price** — the system prevents selling below cost
- If the platform admin changes the wholesale price, your existing selling price remains unchanged, but you cannot set it below the new wholesale
- Tax is calculated on the selling price and added during checkout
- Plans are inherited from the platform — you cannot create entirely new plans, only customize existing ones

## What Clients See

On the plan selection page, your clients see:
- Your custom plan name
- Your selling price (with tax if configured)
- Plan features inherited from the platform
- Any applicable [coupons](/reseller-panel/coupons) they can apply

> **Tip:** If you want to hide a plan from clients, you can disable it. Only active, customized plans with a selling price are shown to your clients.


========================================================================
## Profile & Security
URL: https://docs.splashifypro.com/reseller-panel/profile
========================================================================

# Profile & Security

The Profile page lets you update your account information and secure your account with two-factor authentication.

## Profile Information

Edit your basic account details:

| Field | Description |
|-------|-------------|
| **First Name** | Your first name |
| **Last Name** | Your last name |
| **Company Name** | Your business or company name |
| **Mobile Number** | Your contact phone number |
| **Country Code** | Phone number country code |

Click **Save Changes** to update your profile.

## Change Password

Update your account password:

1. Enter your **Current Password**
2. Enter a **New Password** (minimum 8 characters)
3. **Confirm New Password**
4. Click **Update Password**

Password requirements:
- Minimum 8 characters
- Recommended: mix of uppercase, lowercase, numbers, and symbols

## Two-Factor Authentication (2FA)

Add an extra layer of security to your account using a TOTP authenticator app.

### Enabling 2FA

1. Click **Enable 2FA** in the security section
2. A QR code is displayed
3. Scan the QR code with your authenticator app:
   - Google Authenticator
   - Microsoft Authenticator
   - Authy
   - 1Password
4. Enter the 6-digit code from your authenticator app
5. Click **Verify and Enable**

Once enabled, you'll need to enter a code from your authenticator app every time you log in.

### Disabling 2FA

1. Click **Disable 2FA**
2. Enter your account password to confirm
3. Click **Confirm Disable**

### Lost Your Authenticator?

If you lose access to your authenticator app, contact the platform admin to reset your 2FA. You'll need to verify your identity.

## Account Information

The profile page also displays read-only account details:

| Field | Description |
|-------|-------------|
| **Email** | Your registered email (cannot be changed) |
| **Account Status** | Active or Suspended |
| **Created** | When your reseller account was created |
| **GST Number** | Your tax registration number (if applicable) |

> **Tip:** Always enable 2FA on your reseller account. As a reseller, your account controls billing, client data, and payment gateway credentials — protecting it is critical.


========================================================================
## Settlements
URL: https://docs.splashifypro.com/reseller-panel/settlements
========================================================================

# Settlements

Settlements represent the profit you earn from message conversation markup. When your clients send WhatsApp or RCS messages, the markup you configured in [Markup Settings](/reseller-panel/markup) generates profit that is periodically settled.

## Settlement Overview

The top of the page shows three key metrics:

| Metric | Description |
|--------|-------------|
| **Pending Settlement** | Markup profit accumulated but not yet settled |
| **Next Settlement** | Expected amount in the next settlement cycle |
| **Previous Settlement** | Amount from the last completed settlement |

## How Settlements Work

1. Your client sends a WhatsApp marketing message
2. The base cost is ₹0.80 and your markup is 20%, so the client is charged ₹0.96
3. The ₹0.16 markup profit is accumulated
4. Periodically, accumulated profits are settled and added to your reseller wallet

### Settlement Calculation

```
For each billed message:
  Client Charged:    base_cost x (1 + markup_pct / 100)
  Your Profit:       client_charged - base_cost

Settlement Amount = Sum of all message profits in the period
```

## Settlement History

The table shows completed settlements:

| Column | Description |
|--------|-------------|
| **Settlement ID** | Unique identifier |
| **Amount** | Total settlement amount in ₹ |
| **Messages** | Number of messages included in this settlement |
| **Date** | When the settlement was processed |

## Timing

Settlements are processed automatically by the platform. The frequency depends on your agreement with the platform admin (typically weekly or monthly).

> **Tip:** Cross-reference your settlement amounts with the Message Profit shown on the [Dashboard](/reseller-panel/dashboard) to verify your earnings are correct.


========================================================================
## Support Tickets
URL: https://docs.splashifypro.com/reseller-panel/tickets
========================================================================

# Support Tickets

When your clients submit support tickets through the app, they appear in your reseller panel. You can view, reply to, and manage ticket status.

## Ticket List

The tickets page shows all client tickets:

| Column | Description |
|--------|-------------|
| **Client** | Client name and email |
| **Title** | Ticket subject |
| **Status** | Open, In Progress, Pending, or Closed |
| **Created** | When the ticket was submitted |

### Status Indicators

| Status | Meaning |
|--------|---------|
| **Open** | New ticket, awaiting your response |
| **In Progress** | You've started working on it |
| **Pending** | Waiting for client's response |
| **Closed** | Issue resolved |

## Viewing a Ticket

Click on any ticket to see:
- Full ticket details and description
- Complete conversation thread between you and the client
- Timestamps for each message

## Replying to a Ticket

1. Open the ticket
2. Type your response in the reply box
3. Click **Send Reply**

Your reply is immediately visible to the client in their app under Support.

## Managing Ticket Status

Use the status controls to update ticket progress. Closing a ticket marks it as resolved.

## How Client Tickets Work

1. Client opens the app and goes to **Support**
2. Client creates a new ticket with a title and description
3. The ticket appears in your reseller panel under **Tickets**
4. You reply — the client sees your response in their app
5. Once resolved, close the ticket

> **Note:** The **Open Tickets** count on your dashboard reflects tickets with "open" status that need your attention.


========================================================================
## Wallet
URL: https://docs.splashifypro.com/reseller-panel/wallet
========================================================================

# Wallet

Your reseller wallet is the central balance that covers wholesale costs when clients purchase plans and add-ons. Keep it funded to ensure uninterrupted service.

## Wallet Overview

The top of the page shows:

| Metric | Description |
|--------|-------------|
| **Available Balance** | Current funds available in your wallet |
| **Total Recharged** | Total amount added to your wallet over time |

## How the Wallet Works

1. You **recharge** your wallet by contacting the platform admin
2. When a client **purchases a plan**, the wholesale cost is deducted from your wallet
3. When a client **purchases an add-on**, the wholesale cost is deducted
4. If your wallet balance is **insufficient**, the client's purchase will fail

### Example Flow

```
Your Wallet Balance:        ₹5,000
Client buys Growth Plan:    -₹200 (wholesale cost)
Remaining Balance:          ₹4,800
Client pays you:            ₹500 (your selling price)
Your Profit:                ₹300
```

The ₹500 client payment goes through your payment gateway directly to you. Only the ₹200 wholesale cost is deducted from your reseller wallet.

## Transaction History

The table shows all wallet transactions:

| Column | Description |
|--------|-------------|
| **Date** | Transaction date and time |
| **Type** | Transaction category (see below) |
| **Amount** | Credit (+) or Debit (-) amount |
| **Note** | Description of the transaction |

### Transaction Types

| Type | Description |
|------|-------------|
| **recharge** | Wallet top-up by platform admin |
| **debit** | Wholesale cost deducted for client plan/add-on purchase |
| **credit** | Refund or adjustment credited back |
| **profit_settlement** | Message markup profit settled to your wallet |

## Keeping Your Wallet Funded

- Monitor your balance regularly on the dashboard
- Plan for upcoming client renewals — if 10 clients renew a ₹200 plan, you need ₹2,000 available
- Contact the platform admin to recharge your wallet before it runs low

> **Important:** If your wallet balance reaches zero, new client purchases and renewals will fail. Existing client subscriptions remain active, but no new activations can occur until you recharge.


========================================================================
## Voice AI
URL: https://docs.splashifypro.com/voice-ai
========================================================================

# Voice AI

Splashify Pro Voice AI is a 24/7 AI receptionist for your WhatsApp Business
number. When a customer calls, the AI picks up, has a real conversation,
and acts on what they ask:

- **Captures leads** — saves the caller's name + phone to your Contacts
- **Schedules callbacks** — adds reminders to your dashboard
- **Books appointments** — for booking-template agents
- **Creates support tickets** — for support-template agents
- **Tags contacts** — segment leads for follow-up
- **Sends WhatsApp follow-ups** — auto-message after the call ends
- **Transfers to a human** — when the call needs personal attention
- **Answers from your knowledge base** — uploaded PDFs / docs / images

The agent speaks Hindi, English, Tamil, Telugu, Bengali, Marathi, and
more — switching languages naturally when the caller does.

## How it works

1. **You configure an agent** — voice, greeting, system prompt,
   knowledge base, which tools it's allowed to use.
2. **Caller dials your WhatsApp Business number** — anyone with your
   phone in their contacts can WhatsApp-call you.
3. **The AI answers** — within 2-3 seconds of pickup.
4. **Real conversation happens** — caller asks questions, the AI
   answers grounded in your uploaded knowledge base. When the caller
   asks for something the AI can do (callback, booking, transfer),
   the agent fires the right tool.
5. **Call ends** — you see a summary, transcript, and every tool the
   agent used in the Activity tab. Optional follow-up WhatsApp
   message goes out automatically.

## What you'll need

- An active WhatsApp Business Account on Splashify Pro
- AI Credits in your wallet (₹5/min direct, lower if your provider
  resells through us — see [Pricing](/voice-ai/pricing))
- A plan that includes Voice AI — the feature is enabled per plan

## Quick start

1. Go to **AI Agents** → **+ Create agent** → pick **Voice AI Agent**
2. Set name, voice, languages, and a brief greeting
3. (Optional) Upload PDFs / TXT / images to the **Knowledge Base** tab
4. Toggle the tools you want the agent to use on the **Tools** tab
5. Click **Test Call** in the top-right to talk to the agent in your
   browser
6. Set a fallback phone on the **Routing** tab for transfers
7. Mark the agent as **Default voice agent** — incoming WhatsApp
   calls now route to it

The next sections walk through each piece in detail.

## Quick reference

- **Test Call** uses your microphone in the browser. No AI Credits
  charged. 5-minute hard cap.
- **Real calls** are billed per second from your AI Credits balance
  the moment the agent picks up.
- **Transcripts + summaries** are written automatically after each
  call ends. Find them on the agent's **Activity** tab.
- **Tools** are off by default. Toggle each one explicitly so the
  agent only does what you've authorised.
- **Languages** auto-detect during the call. Set the primary language
  to match your typical caller for best results.


========================================================================
## Create a Voice Agent
URL: https://docs.splashifypro.com/voice-ai/create-voice-agent
========================================================================

# Create a Voice Agent

Voice agents share the **AI Agents** section with chat agents and
workflow bots. Each agent is independent — you can run multiple voice
agents and pick a different default for inbound calls at any time.

## Step 1 — Open the create dialog

From the sidebar, go to **AI Agents** → **+ Create agent**.

In the dialog, pick **Voice AI Agent** as the channel. Voice agents
have their own configuration shape (voice + languages + greeting)
distinct from chat / workflow bots.

## Step 2 — Pick a purpose template

Each template seeds the agent with a sensible default system prompt
+ pre-selected tool set. You can override everything afterwards on the
Persona / Tools tabs.

| Template | Use it for | Default tools |
|---|---|---|
| **Sales** | First-line lead qualification | capture_lead, assign_tag, schedule_callback, transfer_to_human |
| **Support** | Customer support intake | create_ticket, lookup_kb, transfer_to_human |
| **Booking** | Appointment booking (clinic, salon, etc.) | list_available_slots, create_booking, capture_lead |
| **Custom** | Build your own | None — toggle each tool individually |

## Step 3 — Configure the persona

Six tabs run across the top of the agent edit page:

- **Overview** — name, status, default-agent toggle
- **Persona** — voice, languages, greeting, system prompt
- **Knowledge Base** — upload docs the agent answers from
- **Tools** — which actions the agent can take during a call
- **Routing** — fallback phone, working hours, follow-up template
- **Activity** — call history + tool fires per call

### Voice

Pick a voice provider:

- **Edge TTS** (free, Microsoft) — broad language coverage, neutral
  accent. Default for new agents.
- **Sarvam Bulbul v2 / v3** (paid) — Indian-language tuned, more
  natural for Hindi / regional languages. Used in Premium quality
  mode + as fallback.

Then pick a specific voice from the catalog (e.g. `en-IN-NeerjaNeural`,
`hi-IN-MadhurNeural`, `meera`, `arvind`). Click any voice's preview
button to hear a 5-second sample before saving.

### Languages

Tag every language the agent should accept. The first language is
used for the greeting. Mid-call language switches happen
automatically — when a Hindi-speaking caller switches to English,
the agent follows.

Common picks:
- **English + Hindi** — broadest reach across India
- **English + Hindi + Tamil/Telugu/Bengali/Marathi** — region-specific

### Greeting

The first line the caller hears. Keep it short (under 15 words):

> "Hi, this is the AI assistant for Acme Dental. How can I help you today?"

Avoid:
- Greetings longer than 5 seconds — callers tend to start talking
  before you finish
- Multi-language greetings — pick one. Mid-call switching happens
  automatically.

### System prompt

The voice agent's "instructions" — what its job is, what tone it
takes, what it should refuse. Example for a dental clinic:

```
You are the AI receptionist for Acme Dental in Bandra, Mumbai.
Your job is to:
1. Greet callers warmly + ask how you can help.
2. Answer questions about services + opening hours from the
   knowledge base. Quote exact prices verbatim — never round.
3. Capture the caller's name + phone when they want a callback or
   to book an appointment.
4. Use the capture_lead tool when the caller wants to be followed
   up with. Use schedule_callback when they specify a time.
5. Transfer to a human when the caller asks for the doctor or
   sounds upset.

Keep responses to 1-2 short sentences. This is a phone call, not
a chat. Match the caller's language naturally.
```

A handful of platform-supplied "ground rules" (no inventing prices,
say "let me check that and call back" when unsure, etc.) are
prepended to your system prompt automatically.

## Step 4 — Save + test

Click **Save** and then **Test Call** in the top-right. Talk to the
agent in your browser to verify the voice + greeting + behaviour
before pointing real callers at it. Test calls don't charge AI Credits
and have a 5-minute hard cap.

## Next steps

- [Upload your knowledge base](/voice-ai/knowledge-base)
- [Configure tools](/voice-ai/tools)
- [Set fallback phone + working hours](/voice-ai/inbound-calls)
- [Pricing + Wallet](/voice-ai/pricing)


========================================================================
## Custom tools (call your own APIs)
URL: https://docs.splashifypro.com/voice-ai/custom-tools
========================================================================

# Custom tools — call your own APIs

The built-in tools (capture lead, schedule callback, transfer to human,
etc.) cover the common cases. Custom tools cover everything else —
**any HTTP API you can describe with a URL and a few fields, the agent
can call mid-conversation.**

A few real examples customers ship:

- "How many credits do I have left?" → agent calls
  `GET https://api.yourapp.com/v1/users/{{user_id}}/balance` and
  reads the number back.
- "Where's my order?" → agent calls
  `GET https://api.yourapp.com/v1/orders/{{order_id}}` and reads off
  the status, ETA, and tracking link.
- "Book me an appointment for tomorrow" → agent calls
  `POST https://api.yourapp.com/v1/appointments` with date + service.
- "Update my mobile number to ..." → agent calls
  `PATCH https://api.yourapp.com/v1/profile`.

You configure each tool once on the agent's **Tools** tab → **Custom
tools** section. The agent decides when to fire each one based on the
description you write — same as the built-in tools.

## How it works (end-to-end)

1. **You define the tool** — name, description, HTTP method, URL,
   headers, request fields, response mapping.
2. **The agent connects** at call time and the platform passes your
   tool definitions into the call session as part of the room
   metadata.
3. **The agent registers your tools as functions** the LLM can call.
   The LLM sees the tool's name + description + parameters — that's
   how it decides when to fire it.
4. **During the call**, when the LLM decides to call your tool, the
   platform substitutes any `{{placeholders}}` in the URL/headers/body
   with the values the LLM filled in, then makes the HTTP request
   on your behalf. 10-second timeout.
5. **The response comes back** to the LLM — either the mapped
   attributes (when you've configured response mapping) or the raw
   JSON body, trimmed.
6. **The LLM speaks the result** to the caller in natural language.

You can hear the tool fire on your dashboard's **Activity** tab, and
the call recording will reflect the agent reading back whatever your
API returned.

## Setup walkthrough

### 1. Open the Tools tab

Go to **AI Agents → \[your voice agent\] → Tools**.

Scroll past the built-in tool list to **Custom tools**. Click
**+ Add tool**.

### 2. Name the tool

Give it a `snake_case` name like `check_balance`, `get_order_status`,
or `book_appointment`. This is what the LLM uses internally to call
it; **not** what the caller hears.

Names must be unique across the agent's custom tools.

### 3. Describe what it does

The description is the most important field — the LLM reads it to
decide whether to fire your tool. Write it like a one-line spec:

> "Looks up the caller's current credit balance. Use when the caller
> asks how many credits / how much balance they have left."

Be specific about **when** to use it. Vague descriptions lead to the
LLM either never firing it or firing it too eagerly.

### 4. Set the API endpoint

Pick the HTTP method — **GET, POST, PUT, PATCH, DELETE** — and paste
the URL. Use `{{field_name}}` anywhere you want the LLM to fill in a
value at call time:

```
https://api.yourapp.com/v1/orders/{{order_id}}
https://api.yourapp.com/v1/users/{{user_id}}/balance
```

You can also use these always-available context placeholders without
declaring them as fields:

| Placeholder | Value |
|---|---|
| `{{call_id}}` | The current voice call's ID |
| `{{user_id}}` | The Splashify Pro user ID |
| `{{agent_id}}` | The voice agent's ID |
| `{{contact_phone}}` | The caller's phone number |
| `{{contact_name}}` | The caller's saved contact name (if any) |

### 5. Add headers

Click **+ Add header** for each. Common cases:

| Key | Value |
|---|---|
| `Authorization` | `Bearer sk_live_...` |
| `X-API-Key` | `your-api-key-here` |
| `Content-Type` | `application/json` (added by default) |

Secrets paste in here and never leave the platform.

### 6. Define request fields

For each piece of data the agent should fill in, click **+ Add field**:

| Column | What it controls |
|---|---|
| **Name** | Field name. Match the placeholder in the URL/body (e.g. `order_id`). |
| **Location** | Where the value goes: `body`, `query`, `path`, or `header`. |
| **Type** | `string`, `number`, or `boolean`. |
| **Required** | Forces the LLM to fill it before firing. |
| **Description** | What this field is for. The LLM uses this to fill it correctly — be specific. |

Or click **Auto-detect** — the platform parses your URL and pulls
out `{{field}}` placeholders + `?key=value` query params + `:param`
path segments and seeds the field list automatically. You then refine
each row.

### 7. Map the response

When your API returns JSON, you usually only care about a few fields.
**Response attribute mapping** lets you pick which keys the agent
reads back:

| Attribute (what the agent sees) | Response key (JSON path into the API response) |
|---|---|
| `balance_inr` | `data.balance` |
| `currency` | `data.currency` |
| `expires_at` | `meta.subscription.expires_at` |

The mapping uses dot-separated paths, including `data.items.0.name`
for arrays. Unmapped keys are dropped — the LLM won't see them.

If you leave mappings empty, the LLM gets the raw JSON body trimmed
to 500 characters. That works for simple responses but the LLM has
to figure out which key matters.

### 8. Test it

Click **▶ Test** on the tool card. The platform makes the HTTP
request **with no parameters filled in** — just the literal URL +
headers as configured. Use this to confirm authentication is working
and the endpoint is reachable.

For a full end-to-end test (with the LLM filling in parameters), use
**Test Call** at the top of the page and ask the agent the question
that should fire your tool.

### 9. Toggle it on + Save

The right-most switch on the tool card enables / disables it. Saved
tools that aren't enabled stay in your config but the LLM doesn't see
them — useful for keeping work-in-progress tools around without
exposing them.

Click **Save tools** at the bottom of the page.

## Worked example: "How many credits do I have?"

You ship a service at `https://api.yourapp.com` that exposes
`GET /v1/users/{user_id}/credits` returning:

```json
{
  "data": {
    "balance": 247,
    "currency": "INR",
    "expires_at": "2026-12-31"
  }
}
```

Configure the tool like this:

| Field | Value |
|---|---|
| Name | `check_user_credits` |
| Description | "Looks up the caller's credit balance. Use when the caller asks how many credits / what's their balance / when their credits expire." |
| Method | `GET` |
| URL | `https://api.yourapp.com/v1/users/{{user_phone}}/credits` |
| Headers | `Authorization: Bearer sk_live_yourkey` |
| Fields | `user_phone` (path, string, required, "The caller's phone number") |
| Mappings | `balance ← data.balance`, `currency ← data.currency`, `expires_at ← data.expires_at` |

During a call:

> Caller: "Hey, do I have any credits left?"
>
> Agent (decides to fire `check_user_credits` with `user_phone=
> {{contact_phone}}`):
>
> Backend (you): replies with the JSON above.
>
> Agent (reads mapped attributes back): "You have 247 INR in
> credits — they're valid until December 31, 2026."

## Built-in security

- HTTPS-only URLs (HTTP allowed during dev, but logged as a warning).
- Request timeout: 10 seconds. Slow APIs return a polite "I couldn't
  reach that service right now" so the call doesn't stall.
- Tool firing is rate-limited per call — the LLM can't loop on a
  single tool indefinitely.
- All tool fires are logged to your **Activity** tab with the request
  body and response body for replay / debugging.
- The LLM never sees your raw API keys — they live in the headers
  config, are sent server-side from the platform, and never leak into
  the call transcript.

## Limits

| Limit | Value |
|---|---|
| Custom tools per agent | 20 |
| Headers per tool | No hard cap (keep it sane — 10 is plenty) |
| Request fields per tool | No hard cap |
| Response mappings per tool | No hard cap |
| Request timeout | 10 seconds |
| Response body considered | First 500 characters of trimmed JSON, OR all mapped values |

## Common errors

| Symptom | Likely cause | Fix |
|---|---|---|
| Test returns "Network error" | URL unreachable from the platform | Confirm DNS resolves, firewall allows our egress IPs, endpoint is public-facing |
| Test returns HTTP 401 | Wrong auth header | Check the `Authorization` header value, refresh your API key if needed |
| Test returns HTTP 200 but the agent says "I couldn't reach that service" | Firewall is blocking the platform's egress | Whitelist `203.174.23.244` in your API gateway |
| Agent never fires the tool during a call | Description is too vague, OR the tool isn't enabled | Rewrite the description to spell out **when** to fire it; confirm the toggle is on |
| Agent fires the tool with wrong values | LLM misunderstood the parameter description | Make field descriptions explicit ("Order ID — typically a 10-digit number starting with 'ORD-'") |
| Save fails with "duplicate tool name" | Two tools share a name | Rename one — names must be unique per agent |

## What's next

- **Built-in tools** — see [Tools the agent can use](/voice-ai/tools)
  for the platform-managed actions (capture lead, schedule callback,
  transfer to human, etc.).
- **Knowledge base** — for **read-only** lookups against your own
  documents, [Knowledge base](/voice-ai/knowledge-base) is faster
  than a custom tool because the data is pre-indexed.
- **Test calls** — run an end-to-end test before deploying. See
  [Test call](/voice-ai/test-call).


========================================================================
## Real WhatsApp Calls
URL: https://docs.splashifypro.com/voice-ai/inbound-calls
========================================================================

# Real WhatsApp Calls

Once you've tested your agent in the browser and it behaves the way
you want, point real WhatsApp Business inbound calls at it.

## Prerequisites

- An active WhatsApp Business Account on Splashify Pro
- WhatsApp Calling enabled on your WABA (it's enabled by default for
  most accounts; check **Settings → Calling** in the app)
- A voice agent with `status = active`
- AI Credits in your wallet (₹5/min direct rate by default — see
  [Pricing](/voice-ai/pricing))

## Make an agent your default

On the agent edit page, **Overview** tab → click the **★ Set as
default voice agent** button. Only one agent can be the default
at a time; setting a new one unstars the previous.

When the star is filled, every WhatsApp inbound call to your business
number routes to this agent automatically.

## Set a fallback phone

On the **Routing** tab, set a **Fallback phone** in E.164 format
(e.g. `+919876543210`). The agent uses this when:

- The caller asks to be transferred to a human
- The agent can't help and the call needs personal attention
- Working hours are configured + the call lands outside them

Without a fallback phone configured, the agent apologises and offers
a callback instead — the call still ends gracefully.

## Working hours (optional)

On the **Routing** tab, set timezone + per-day open / close hours.
Calls outside those hours route directly to your fallback phone
without engaging the AI. Useful when you have a part-time AI setup
+ a full-time human team.

## What happens on a real call

1. **Caller dials** your WhatsApp Business number
2. **Caller hears** ringing for 1-2 seconds while the agent connects
3. **Agent picks up + plays your greeting** within 2-3 seconds
4. **Real conversation** — the agent listens, thinks, speaks. You can
   watch this live on the agent's **Activity** tab (rows refresh
   every few seconds)
5. **Tools fire** as the conversation requires
6. **Call ends** when:
   - Caller hangs up (most common)
   - Agent transfers to your fallback phone
   - Working hours boundary crossed (rare — usually the call ends
     before this matters)
   - Wallet balance hits zero (agent says "I need to drop the call —
     please call back" and ends gracefully)
   - 10-minute hard cap reached (rare — most calls are 1-3 minutes)

## What you see afterwards

The **Activity** tab shows every call as a row:

- Date + time
- Duration
- Outcome (lead captured / callback scheduled / transferred / etc.)
- Click to expand → see every tool fire that happened during the call

The agent's post-call summary (3 sentences) lands within 30 seconds
of hangup. If you've configured a follow-up template on the Routing
tab, it sends to the caller within ~60 seconds.

## Multiple voice agents

You can have multiple voice agents (e.g. one for sales, one for
support) — only one is the **default** at any time. Future enhancement
will let you route by caller phone or time of day; today the default
agent answers every inbound call.

## Disabling

Three options:

1. **Pause the agent** — Overview tab → set status to `paused`. Calls
   route to your fallback phone instead of the AI.
2. **Unset default** — click the filled star to remove default
   status. Calls fall through to whichever in-app pickup flow you
   have configured.
3. **Delete the agent** — permanently removes it. You can recreate
   later but the knowledge base + history are gone.

## Troubleshooting

| Symptom | Fix |
|---|---|
| Caller hears ringing forever | Check agent status is `active` on Overview tab. Check AI Credits balance — under ₹50 is risky. |
| Agent picks up but says "I need to drop the call" | Wallet balance hit zero mid-call. Recharge AI Credits. |
| Caller says agent transferred but no human picked up | Verify fallback phone is correct E.164 format on Routing tab. Verify the line is staffed. |
| Call connects but caller can't hear agent | Network / Meta-side issue. Caller can hang up + redial. |
| Agent answers in English, caller is on Hindi | Add Hindi to the **Languages** list on Persona tab |


========================================================================
## Knowledge Base
URL: https://docs.splashifypro.com/voice-ai/knowledge-base
========================================================================

# Knowledge Base

The voice agent answers from your uploaded content. When a caller
asks a question, the agent searches the knowledge base for matching
chunks and quotes the exact wording. If nothing matches, the agent
says "let me check that and have someone call you back" — and never
invents an answer.

## Supported file types

| Type | Notes |
|---|---|
| **PDF** | Text + scanned PDFs both work. Multi-page supported. |
| **TXT / MD** | Plain text. Best for FAQ pages, policy docs. |
| **CSV** | First row is treated as headers. Each row becomes a "key: value" line per column. |
| **DOCX** | Word documents. |
| **XLSX** | Excel spreadsheets. |
| **PNG / JPG** | Vision model reads the image content (e.g. menu boards, price lists). |

Max file size: **50 MB**.

## Upload a file

On the agent edit page, go to the **Knowledge Base** tab → **Upload**.
Drop a file or click to pick.

Status flow: `processing` → `indexed` (or `failed` with a reason).
Refresh the page or click the row to see the latest status.
Processing usually takes 5-30 seconds for typical files; large PDFs
or image-only files take longer.

## Test a query

Use the **Test query** input to ask a question and see what chunks
the agent would retrieve. Examples:

- "What are your opening hours?"
- "How much does a root canal cost?"
- "What's the cancellation policy?"

You see the matching chunks + their similarity score. If a question
returns no hits, the agent will say "let me check that and call back"
on a real call — fix that gap by uploading a doc that covers it.

## Best practices

- **Split big docs into focused files.** A single 200-page PDF works,
  but separate "menu.pdf" + "policies.pdf" + "team.pdf" gives sharper
  retrieval.
- **Update + reupload when prices/hours change.** The agent quotes
  what's in the KB. Stale prices = unhappy callers.
- **Use plain language.** Marketing copy ("our award-winning
  experience") is harder for the agent to ground from than direct
  facts ("we open at 9 AM Monday to Saturday").
- **Image content gets OCR'd** — handwritten notes, faded scans, and
  busy backgrounds reduce extraction quality. Prefer clean digital
  PDFs when possible.

## Removing files

Click **Delete** on any row. The agent stops referencing the file
within seconds. Re-uploading isn't supported in-place — delete the
old, upload the new.

## What the agent does NOT do

- **Doesn't read your CRM / sheets / Notion** — only the files
  uploaded to this agent.
- **Doesn't browse the web** — facts must be in the KB.
- **Doesn't share private content** — every agent's KB is scoped to
  that agent + that customer account.

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| Agent says "let me check that" on every question | KB is empty or failed | Check status on Knowledge Base tab. Re-upload failed files. |
| Wrong information surfaces | Stale doc still in KB | Delete the stale doc, upload the corrected version |
| PDF status = `failed: extraction failed` | Image-only PDF too dark / busy | Convert to PNG and re-upload, or improve scan quality |
| "Vision model failed" on image upload | Image is corrupt or too large | Resize to under 5 MB, save as fresh PNG/JPG |


========================================================================
## Monitoring & Activity
URL: https://docs.splashifypro.com/voice-ai/monitoring
========================================================================

# Monitoring & Activity

Each voice agent has an **Activity** tab that shows real-call
history. Use it to verify the agent is doing the right thing, debug
unexpected behaviour, and follow up on captured leads.

## Activity tab

On the agent edit page → **Activity** tab. You see a list of recent
calls (most recent first):

- Date + time
- Duration
- Outcome label (lead captured / callback scheduled / transferred /
  ticket created / etc.)
- End reason (caller_hangup / wallet_empty / agent_error / etc.)

Click any row to expand:

- Every tool the agent fired during the call, in chronological order
- Result message for each tool (e.g. "Saved Sayan as a lead")
- Error indicator (red dot) for any tool that failed
- Per-tool duration in milliseconds

## Post-call summary

Within ~30 seconds of hangup, the agent generates a 3-sentence
summary of the call:

1. Why the caller called
2. What the agent did (which tools it used)
3. Outcome / next step

The summary appears on the call row in the Activity tab. Useful for
quickly catching up on calls without reading the full transcript.

## Where captured leads land

The **capture_lead** tool writes the caller's name + phone + intent
straight to your **Contacts** with the `voice-ai-lead` tag. Open the
**Contacts** page → filter by tag `voice-ai-lead` to see every lead
the AI captured.

## Where scheduled callbacks land

The **schedule_callback** tool writes to a callback queue. A
background worker fires a WhatsApp reminder to the caller at the
scheduled time. You'll see callbacks in your dashboard's Activity
feed and on the agent's Activity tab.

## Where bookings land

The **create_booking** tool (booking-template agents only) writes
appointment slots that the agent then offers via
**list_available_slots**. Future agent calls won't double-book the
same slot — already-booked windows get filtered out.

## Where tickets land

The **create_ticket** tool writes a row to your **Support** inbox
with category `voice_ai`. Open Support → filter by category to see
voice-AI-created tickets.

## Spend tracking

Per-call cost rows land in **Settings → Track Expenses** alongside
WhatsApp / email / RCS expenses. Each voice call shows up as one
row labeled `Voice AI call - <duration>`.

## Live dashboard

Coming soon: a per-agent live dashboard showing:

- Calls today / week / month
- Avg duration trend
- Top tool fires
- Captured leads count
- Cost-to-revenue chart

For now, the Activity tab + Track Expenses cover the day-to-day
visibility most customers need.

## Common workflows

### Following up on captured leads

1. **Contacts** → filter by tag `voice-ai-lead`
2. Sort by created date desc — newest leads first
3. Open each contact → see the call's tool fires + the original
   transcript timestamp on Activity

### Auditing an agent's behaviour

1. Agent edit page → **Activity** tab
2. Pick a call where the outcome looks wrong
3. Expand the row → review every tool fire + the result message
4. If the agent mishandled something, tweak the system prompt on the
   Persona tab so future calls behave differently

### Reviewing wallet drain

1. **Settings → Track Expenses**
2. Filter category to "Voice AI"
3. See every call's cost + duration. Anomalies (very long calls,
   very high spend) point at agents talking too much — tighten the
   system prompt to keep responses 1-2 sentences.


========================================================================
## Pricing & Wallet
URL: https://docs.splashifypro.com/voice-ai/pricing
========================================================================

# Pricing & Wallet

Voice AI is **pay-as-you-go**. You recharge AI Credits, the agent
deducts in tiny per-second slices the moment a call starts.

## Rates

| Customer | Rate per minute |
|---|---|
| Direct customer | **₹5.00** |
| Reseller client | Set by your provider (typically ₹3.50 + their markup) |
| Test calls (in-browser) | **Free** |

A 3-minute call at the direct rate costs **₹15**.

GST applies on AI Credit purchases per the standard rate; the per-
second deduction itself doesn't add tax (GST is captured at the
recharge invoice level).

## Free trial

When your account has Voice AI enabled, the platform credits **₹50
of free Voice AI minutes** on first activation — about 10 minutes
at the direct rate. Use it to take real test calls before committing.

## How per-second billing works

The moment your agent picks up a real WhatsApp inbound call, a
1-second-tick deduction starts:

```
deducted per second = (₹5.00 / 60) ≈ ₹0.0833
```

Each second is logged so you can see exactly where the time went on
the call's Activity entry.

## When the wallet runs out

If your AI Credits balance drops below the per-second cost mid-call,
the agent gracefully ends the call:

> "I need to drop the call now — please give us a call back later."

You see this on the Activity tab as `end_reason = wallet_empty`.

## Recharge

Top up AI Credits anytime:

- **Sidebar** → **AI Credits** (or visit
  `app.splashifypro.com/ai-credits`)
- Pick an amount or enter a custom value
- Pay via UPI / cards / netbanking
- Balance reflects within seconds of payment success

The same AI Credits balance is shared across Voice AI + chat AI
agent usage — there's one wallet, two consumers.

## Where to see what you've spent

- **AI Credits page** — running balance + recharge history
- **Track Expenses** (Settings → Track Expenses) — every per-call
  summary row showing duration + cost in INR
- **Agent Activity tab** — per-call cost breakdown including
  any per-second snapshots

## Reseller pricing

If your account was provisioned through a reseller (e.g. you signed
up at `app.<reseller-brand>.com`), your rate is set by the reseller,
not the platform default. Your rate appears on the agent's price
calculator card on the Overview tab.

## Free vs paid call paths

| Path | Cost |
|---|---|
| Test Call (browser, mic-only) | Free |
| Real WhatsApp inbound call | Per-second from AI Credits |

## Best practices

- **Recharge to ~30 minutes' worth at minimum** — at ₹5/min
  direct, that's ₹150. Less than this and a busy hour can run you
  out mid-call.
- **Set up auto-recharge alerts** — coming soon. For now, check
  AI Credits balance once a week if you take regular voice calls.
- **Test calls don't count** — explore freely in the Test Call modal
  before going live.
- **Agent transfers to fallback** are billed up to the moment of
  transfer. Once the call routes to your human line, no further
  AI Credits deduct.


========================================================================
## Test Call
URL: https://docs.splashifypro.com/voice-ai/test-call
========================================================================

# Test Call

Test Call is a free in-browser audio call to your voice agent. Use it
to verify voice + greeting + behaviour + tool fires before any real
customer dials in.

## Open a test call

On the agent edit page, click **Test Call** in the top-right.

Allow microphone access when the browser prompts. The call connects
within 2-3 seconds; you'll hear the greeting, then start talking.

## What you see

- **Animated waveform** — pulses while the agent is speaking
- **Status pill** — Listening / Thinking / Speaking
- **Live transcript** — both your turns and the agent's, time-ordered
- **Tool-fire counter** — pill in the header showing how many tools
  the agent used so far
- **Tool-fire toasts** — pop-up notifications the moment a tool fires
  (e.g. "✓ Captured lead — Sayan / +91 9876543210")
- **5-minute countdown** — Test calls auto-end at 5 minutes
- **End call button** — hang up anytime

## After you hang up

The modal pivots to a summary screen with:

- **Duration** — exact mm:ss
- **Turns** — total user + agent utterances
- **Tools fired** — count + per-tool breakdown
- **Tool list** — every fire with the result message + timestamp
- **Download transcript** — saves a `.txt` file with the full
  transcript + tool history
- **Start new call** button — instant retry

## What's free + what's not

- Test calls are **free**. No AI Credits charged.
- Real WhatsApp calls (after you set the agent as default voice
  agent) **are billed per second** from your AI Credits balance —
  see [Pricing](/voice-ai/pricing).
- Tool fires during test calls **do** make real changes — leads
  captured during a test land in your real Contacts list, callbacks
  scheduled show up in your dashboard, etc. Test with care, or use
  a non-production agent for exploration.

## Limits

- **5 minutes** max per test call (hard cap)
- **1 test call at a time** per agent
- Microphone-only — no incoming audio from anything but your
  microphone

## Common things to test

- Say your name + phone + what you want — verify the lead lands in
  Contacts with the right tag
- Ask "please call me back tomorrow at 3 PM" — verify a callback
  row appears
- Ask a question that's in your KB — verify the agent quotes your
  uploaded doc accurately
- Ask a question that's NOT in your KB — verify the agent says
  "let me check that and call back" instead of inventing
- Say "I want to speak to a person" — verify transfer fires (and
  if you've configured a fallback phone, you should see the agent
  apologize politely if it can't reach the line)
- Switch language mid-call (English → Hindi) — verify the agent
  follows

## Troubleshooting

| Symptom | Fix |
|---|---|
| "Microphone access denied" | Allow mic permission in your browser address bar |
| No greeting after 5+ seconds | Refresh the page + try again. Check that the agent's status is `active` on the Overview tab. |
| Agent answers in wrong language | Add the missing language to the **Languages** list on the Persona tab |
| Tool toast doesn't appear when expected | Check the tool is toggled ON for this agent on the Tools tab |
| Audio choppy | Network issue — try a different network or click End Call + retry |


========================================================================
## Tools the agent can use
URL: https://docs.splashifypro.com/voice-ai/tools
========================================================================

# Tools the agent can use

Tools are the things your voice agent does **for** the caller during
a call — separate from just answering questions. The agent decides
when to fire each tool based on the conversation; you decide which
tools the agent is allowed to use at all.

Toggle each tool on the agent's **Tools** tab. Off by default.

## Available tools

| Tool | When the agent fires it | What happens |
|---|---|---|
| **Knowledge base lookup** | When the auto-RAG missed something | The agent searches your KB on demand and uses the result in its next reply |
| **Capture lead** | When the caller shares name + phone + interest | Saves contact to your **Contacts** with `voice-ai-lead` tag |
| **Assign tag** | When the caller fits a segment | Adds tags to the caller's contact (e.g. "hot-lead", "ac-shopper") |
| **Schedule callback** | When the caller asks to be called back at a specific time | Adds a reminder; you'll see it on your dashboard. Optional WA reminder fires automatically. |
| **Send follow-up message** | When the caller asks for info to be sent to them | Queues a WhatsApp message that goes out after the call ends |
| **Transfer to human** | When the caller is upset or asks for a person | Drops the AI and dials your fallback phone number |
| **List available slots** | Booking-template only | Shows open appointment slots for a given date / service |
| **Create booking** | Booking-template only | Confirms an appointment after the caller picks a slot |
| **Create support ticket** | Support-template only | Creates a ticket in your Support inbox with the caller's issue |

## Per-tool config

A few tools have extra settings on the **Routing** tab:

### Transfer to human

Requires a **Fallback phone** — the number the call routes to when
the agent transfers. Set this on the Routing tab as an E.164 phone
(`+919876543210`). Without it set, the agent apologises and offers a
callback instead.

### Send follow-up message

Optionally pick a **Follow-up template** on the Routing tab. The
template's variables are auto-filled from the call (caller name,
captured interest, etc.). Without a template configured, the agent
sends a free-form text message with whatever copy it generates.

### List available slots / Create booking

The agent reads available slots from your booking calendar config
(the one bundled with the booking template). Slots are filtered to
exclude already-booked times automatically.

### Create support ticket

Tickets land in your **Support** inbox with category `voice_ai`.
Priority defaults to `medium`; the agent can pick `high` when the
caller signals urgency.

## How the agent decides which tool to fire

The agent reads your system prompt + the conversation context, then
picks the most appropriate tool for the moment. Rules of thumb:

- **Capture lead** fires when the caller shares both name + phone +
  some signal of interest.
- **Schedule callback** fires when the caller specifies a time
  ("call me back at 3 PM tomorrow").
- **Transfer to human** is a last resort — the agent first tries to
  answer or capture details, and only transfers when the caller
  explicitly asks for a person or sounds upset.
- **Send follow-up message** is for "send me the price list" / "send
  me your address" type asks — anything the caller wants in writing.

## Watching tools fire

Two places:

- **During a Test Call** — the right side of the modal shows a
  toast for every tool fire as it happens, plus a counter pill in
  the header. After the call ends, the summary screen lists every
  tool the agent used + a transcript download.
- **On real calls** — the agent's **Activity** tab shows every call
  with an expandable accordion. Click a call row to see the tool
  fires that happened during that call.

## Best practices

- **Start with 2-3 tools.** Capture lead + schedule callback + transfer
  cover the common cases. Add booking / ticket / KB lookup as your
  use case demands.
- **Always pair `transfer_to_human` with a working fallback phone.**
  Otherwise the agent has nowhere to transfer.
- **Test tool fires** in the Test Call modal before pointing real
  callers at the agent. Say things like "please call me back at
  3 PM, my name is Sayan, my number is +91 9876543210" and verify
  the row lands in your Contacts.


========================================================================
## Troubleshooting
URL: https://docs.splashifypro.com/voice-ai/troubleshooting
========================================================================

# Troubleshooting

## Setup issues

### "Voice AI not available on your plan"

Your current plan doesn't include Voice AI. Either:
- Upgrade your plan from **Settings → Plans** to one that includes
  Voice AI
- Use the free trial credit (₹50 ≈ 10 minutes) on activation if
  you're new

### Agent creation fails

Check:
- **Status** isn't `paused` on the Overview tab after save
- **Voice provider + Voice ID** are both selected on Persona tab
- **Greeting** isn't empty
- **At least one language** is in the Languages list

## Test call issues

### "Microphone access denied"

Browser blocked mic permission. Click the lock/info icon in the
address bar → **Allow microphone**. Reload the page.

### Connecting forever / no audio

- Check the agent's `status` is `active` on the Overview tab
- Check the AI Credits balance — under ₹5 may fail to start (test
  calls don't bill, but the platform reserves a small amount as a
  safety check)
- Try a different network (corporate firewalls sometimes block WebRTC)
- Try a different browser — Chrome / Edge / Firefox all work; older
  Safari versions can be flaky

### Choppy audio

Network jitter. Hang up + retry, ideally on a more stable connection
(wired Ethernet or a strong WiFi signal).

### Agent doesn't pick up my language

Add the language to the **Languages** list on the Persona tab + save.
The change applies to your next call (test calls don't reload the
agent mid-call).

## Real-call issues

### Caller hears ringing but agent never picks up

- Verify the agent is set as **Default voice agent** (filled star on
  Overview tab)
- Verify status is `active`
- Check AI Credits balance — under ₹5 will refuse the call

### Caller says agent ended the call abruptly

Common causes:
- **Wallet ran out** — Activity tab shows `end_reason = wallet_empty`.
  Recharge AI Credits.
- **10-minute hard cap reached** — rare but real. Most calls end well
  under this.
- **Agent error** — Activity tab shows `end_reason = agent_error`.
  Open a support ticket from the help menu so we can investigate.

### Transfer doesn't work

- Check **Fallback phone** is set on the Routing tab in **E.164**
  format (e.g. `+919876543210`, not `9876543210` or `0091...`)
- Check the line is staffed during the call's time window
- The agent waits ~5 seconds for the line to pick up — if it rings
  unanswered, the agent apologises and offers a callback

## Knowledge base issues

### Agent says "let me check that and call back" on every question

- KB is empty — go to Knowledge Base tab + upload at least one file
- All uploaded files are in `failed` status — check the failure
  reason on each row + re-upload corrected versions

### Agent quotes wrong / outdated info

You uploaded a doc with old prices/policies. Delete the stale file +
upload the updated version. The agent uses the latest indexed content.

### Image PDF status: failed

- File is image-only (scanned PDF) and OCR couldn't extract text
- Try converting to clearer scans or extracting text manually + saving
  as TXT
- Very large image PDFs (>50 MB) get rejected at upload

## Tool issues

### Tool didn't fire when I expected

Most common cause: the tool isn't toggled on for this agent. Tools
tab → toggle the right tool → Save. Test in the Test Call modal.

Second cause: the agent decided the moment didn't warrant the tool.
Tighten the system prompt on the Persona tab — example:

> "When the caller shares their name AND phone number, ALWAYS fire
> capture_lead immediately."

### "Transfer to human" said no fallback configured

Set **Fallback phone** on the Routing tab in E.164 format. Save.
Test in a fresh test call.

### Captured lead didn't appear in Contacts

Check Contacts → filter by tag `voice-ai-lead`. If still empty, the
agent's tool fire may have errored. Activity tab → expand the
relevant call row → look for a red status dot on the
`Captured lead` line. Common causes:
- Phone number was malformed — agent extracted "nine zero zero..."
  but the validation rejected it
- No name extracted — fix by tightening the system prompt to ask for
  name first

## Wallet / billing issues

### Wallet drains faster than expected

- Check the rate on the Overview tab → **Rate** card. Reseller-priced
  customers see their reseller's rate, not the ₹5 default.
- Long-winded agents talk past necessary length — tighten the system
  prompt to enforce "1-2 sentence responses".
- Test calls are free, so accidental over-testing isn't the cause —
  it's real calls that bill.

### Mid-call wallet-empty

Recharge AI Credits → set up enough buffer for typical call
duration × volume. At ₹5/min, ₹500 = 100 minutes ≈ 30-40 typical
3-minute calls.

## Still stuck?

- Open a support ticket: **Sidebar → Help → Raise a ticket**
- Or message the in-app AI assistant (the chat bubble bottom-right) —
  it can route you to the right docs page or open a ticket on your
  behalf

Don't share OTPs, passwords, or sensitive customer data in tickets.