# Deep Prominence Messaging API Walkthrough Tutorial

Welcome to the client-facing integration walkthrough for the **Deep Prominence Platform**. This guide provides a step-by-step tutorial to help you integrate WhatsApp cloud messaging, OTP verification, transactional/promotional email delivery, campaigns, and wallet management.

* **API Base URL:** `https://whatsapp.infybusiness.com/api`

---

## 1. Getting Started & Authentication

The platform supports two types of authentication depending on the endpoint you access.

### Authentication Headers

1. **Bearer Token Auth (`Authorization: Bearer <token>`)**
   * Used for Client Portal actions and account management.
   * Obtain this token by logging in.
   * Example: `Authorization: Bearer 2|clienttoken123456...`

2. **API Key Auth (`X-API-Key: <your_api_key>`)**
   * Used for sending messages, dispatches, campaign creation, and wallet queries.
   * Generated through the Client Portal or programmatically.
   * Format: Starts with `dpk_sec_` for secret keys.
   * Example: `X-API-Key: dpk_sec_your_secret_key_here`

---

### Step 1: Create an Account
Register your client account to get started.

```bash
curl -X POST "https://whatsapp.infybusiness.com/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Corp",
    "email": "integration@acme.com",
    "password": "securepassword123",
    "password_confirmation": "securepassword123",
    "phone": "919876543210"
  }'
```

**JSON Response (201 Created):**
```json
{
  "success": true,
  "message": "Registration successful. Please log in.",
  "data": {
    "client": {
      "id": 10,
      "company_name": "Acme Corp",
      "email": "integration@acme.com",
      "phone": "919876543210"
    }
  }
}
```

### Step 2: Log In to Get a Bearer Token
Retrieve your Personal Access Token (Bearer token).

```bash
curl -X POST "https://whatsapp.infybusiness.com/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "integration@acme.com",
    "password": "securepassword123"
  }'
```

**JSON Response (200 OK):**
```json
{
  "success": true,
  "token": "2|clienttoken1234567890abcdef123456",
  "client": {
    "id": 10,
    "company_name": "Acme Corp",
    "email": "integration@acme.com"
  }
}
```

### Step 3: Generate an API Key (Requires Bearer Token)
Provision a secret API key for core messaging services.

```bash
curl -X POST "https://whatsapp.infybusiness.com/api/auth/api-keys" \
  -H "Authorization: Bearer 2|clienttoken1234567890abcdef123456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Integration Key",
    "key_type": "secret",
    "scopes": ["whatsapp:send", "email:send"]
  }'
```

**JSON Response (201 Created):**
```json
{
  "success": true,
  "message": "API key generated successfully.",
  "data": {
    "id": 15,
    "name": "Integration Key",
    "key_type": "secret",
    "api_key": "dpk_sec_integration_key_987654321",
    "scopes": [
      "whatsapp:send",
      "email:send"
    ]
  }
}
```

---

## 2. Step-by-Step Walkthrough

All messaging and wallet query endpoints below require the `X-API-Key` header.

### 2.1 Send a WhatsApp Text Message
Use `/api/messages/send` with `type: "text"` to dispatch a standard WhatsApp text.

```bash
curl -X POST "https://whatsapp.infybusiness.com/api/messages/send" \
  -H "X-API-Key: dpk_sec_integration_key_987654321" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "919876543210",
    "type": "text",
    "text": "Hello! Your package is arriving today."
  }'
```

**JSON Response (200 OK):**
```json
{
  "success": true,
  "message": "Message sent successfully.",
  "data": {
    "id": 201,
    "wa_message_id": "wamid.HBgLOTE5ODc2NTQzMjEwFQIAERg5MUFEQ0ExODQ0M0ZBRjM2QkUAAg==",
    "status": "sent",
    "recipient": "919876543210",
    "type": "text"
  }
}
```

### 2.2 Send a WhatsApp Template Message
Approved Meta/WABA templates can be dispatched using components.

```bash
curl -X POST "https://whatsapp.infybusiness.com/api/messages/send" \
  -H "X-API-Key: dpk_sec_integration_key_987654321" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "919876543210",
    "type": "template",
    "template_name": "order_delivery_update",
    "language": "en_US",
    "template_params": ["John Doe", "Order #98765"]
  }'
```

**JSON Response (200 OK):**
```json
{
  "success": true,
  "message": "Message sent successfully.",
  "data": {
    "id": 202,
    "wa_message_id": "wamid.HBgLOTE5ODc2NTQzMjEwFQIAERg5MUFEQ0ExODQ0M0ZBRjM2QkUAAg==",
    "status": "sent",
    "recipient": "919876543210",
    "type": "template"
  }
}
```

### 2.3 Send + Verify an OTP
The OTP service automatically constructs a 6-digit verification code and routes it via WhatsApp.

#### A. Dispatch OTP to Phone

```bash
curl -X POST "https://whatsapp.infybusiness.com/api/otp/send" \
  -H "X-API-Key: dpk_sec_integration_key_987654321" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "9876543210"
  }'
```

**JSON Response (200 OK):**
```json
{
  "success": true,
  "message": "OTP sent via WhatsApp.",
  "data": {
    "otp_id": 85,
    "expires_in": 300
  }
}
```

#### B. Verify OTP from User

```bash
curl -X POST "https://whatsapp.infybusiness.com/api/otp/verify" \
  -H "X-API-Key: dpk_sec_integration_key_987654321" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "9876543210",
    "otp_code": "123456"
  }'
```

**JSON Response (200 OK):**
```json
{
  "success": true,
  "message": "OTP verified successfully."
}
```

### 2.4 Send an Email
Send HTML/Text emails using the `/api/email/messages/send` endpoint.

```bash
curl -X POST "https://whatsapp.infybusiness.com/api/email/messages/send" \
  -H "X-API-Key: dpk_sec_integration_key_987654321" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "client@example.com",
    "name": "Jane Client",
    "subject": "Onboarding Complete",
    "html": "<h1>Welcome @{{name}}!</h1><p>Your workspace is active.</p>",
    "text": "Welcome Jane Client! Your workspace is active."
  }'
```

**JSON Response (200 OK):**
```json
{
  "success": true,
  "message": "Email sent securely.",
  "data": {
    "message_id": 95,
    "to": "client@example.com",
    "status": "sent"
  }
}
```

### 2.5 Create a Campaign
Launch bulk broadcasts with unique list targets.

```bash
curl -X POST "https://whatsapp.infybusiness.com/api/campaigns" \
  -H "X-API-Key: dpk_sec_integration_key_987654321" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mid-Summer Clearance",
    "type": "template",
    "whatsapp_number_id": 1,
    "recipients": ["919876543210", "919876543211"],
    "template_name": "clearance_offer",
    "template_params": ["30% OFF"]
  }'
```

**JSON Response (201 Created):**
```json
{
  "success": true,
  "message": "Campaign created and queued for processing.",
  "data": {
    "id": 12,
    "name": "Mid-Summer Clearance",
    "type": "template",
    "total_recipients": 2,
    "status": "pending"
  }
}
```

### 2.6 Check Wallet Balance
Inquire about your available prepaid balances and rates.

```bash
curl -X GET "https://whatsapp.infybusiness.com/api/wallet/balance" \
  -H "X-API-Key: dpk_sec_integration_key_987654321"
```

**JSON Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "balance": 2500.00,
    "currency": "INR",
    "pricing": {
      "per_message": 0.80,
      "per_otp": 0.20,
      "per_promo": 0.90
    }
  }
}
```

---

## 3. Wallet Recharge Walkthrough (Client Portal)

Prepaid wallet balance top-ups must be initiated using your **Bearer token** inside Client Portal sessions. Cashfree is the primary gateway, with Razorpay available as an alternative.

### Step 1: Initiate Top-up (Generate Session)
Call `/api/client/wallet/topup` specifying your desired gateway.

```bash
curl -X POST "https://whatsapp.infybusiness.com/api/client/wallet/topup" \
  -H "Authorization: Bearer 2|clienttoken1234567890abcdef123456" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000.00,
    "gateway": "cashfree"
  }'
```

**JSON Response (200 OK):**
```json
{
  "success": true,
  "gateway": "cashfree",
  "order_id": "order_client_10_cf9876",
  "payment_session_id": "session_cf_xyz789abcedef1234567890",
  "cf_order_id": "9876543",
  "mode": "TEST",
  "amount": 1000.00,
  "currency": "INR"
}
```

### Step 2: Payment Execution & Verification
Once the client completes checkout via the payment gateway interface:

#### For Cashfree:
Request server-to-server verification post-payment:

```bash
curl -X POST "https://whatsapp.infybusiness.com/api/client/wallet/cashfree/verify" \
  -H "Authorization: Bearer 2|clienttoken1234567890abcdef123456" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "order_client_10_cf9876"
  }'
```

**JSON Response (200 OK):**
```json
{
  "success": true,
  "message": "Payment verified and wallet credited.",
  "balance": 3500.00
}
```

#### For Razorpay:
Verify your payment signature callback:

```bash
curl -X POST "https://whatsapp.infybusiness.com/api/client/wallet/razorpay/callback" \
  -H "Authorization: Bearer 2|clienttoken1234567890abcdef123456" \
  -H "Content-Type: application/json" \
  -d '{
    "razorpay_order_id": "order_rzp_98765",
    "razorpay_payment_id": "pay_rzp_abc123",
    "razorpay_signature": "sha256_signature_here"
  }'
```

**JSON Response (200 OK):**
```json
{
  "success": true,
  "message": "Wallet credited successfully.",
  "balance": 3500.00
}
```

### Webhook Fallback
Asynchronous public webhooks verify transaction completions even if a client closes their portal.
* **Cashfree Webhook Endpoint:** `POST /api/wallet/cashfree/webhook`
* **Razorpay Webhook Endpoint:** `POST /api/wallet/razorpay/webhook`

---

## 4. Billing Model

* **Delivered-Only Charging:** WhatsApp messages consume wallet funds **only upon successful delivery** to the user (confirmed via Meta `delivered` webhook events). Failed dispatches are auto-voided.
* **OTP Charging:** Charged immediately upon transmission.
* **Insufficient Funds (HTTP 402):** Requests fail with `402 Payment Required` when your wallet limit is hit:
  ```json
  {
    "success": false,
    "error": "Insufficient wallet balance. Please top up to continue.",
    "data": {
      "balance": 5.20,
      "required": 150.00,
      "credit_line": 100.00,
      "available": 105.20
    }
  }
  ```
* **Credit Line:** Accounts have a `100-message` negative credit buffer.
* **Alert Thresholds:** Automatic low-balance alert notification triggered when balance drops below default thresholds (e.g. ₹50).

---

## 5. Webhooks Note

Integrate public routes to receive Cloud API status callbacks directly to your server:
* `GET /webhook` — Handshake verification.
* `POST /webhook` — Delivery status events (`sent`, `delivered`, `read`, `failed`). Keep these online to sync wallet debits.