SquareBox External API Documentation

Welcome to the SquareBox External API! This documentation covers how to generate API keys and send WhatsApp messages using our external messaging API.

Overview

The SquareBox External API allows external platforms to send WhatsApp messages using secure API keys. This API is perfect for:

CRM integrations (Salesforce, HubSpot, etc.)
E-commerce platforms
Customer support tools
Marketing automation platforms

Getting Started

1. Generate API Key

Log into your SquareBox account
Go to Settings → API Keys
Click "Create New API Key"
Provide a name and description (e.g., "LeadSquared Integration")
Important: Copy the API key immediately - it won't be shown again!

2. Get Your Line ID

Go to Lines in your SquareBox dashboard
Note the Line ID you want to send messages from
Ensure the line is active and has sufficient credits

Authentication

Use this header:

X-API-Key: sb_your_api_key_here

Example:

X-API-Key: sb_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

Notes:

Usage is tracked per key (timestamp and IP) for audit/analytics.
Credit checks run before send calls; responses include estimated_cost. Actual deductions occur via webhook on status update.

Base URL

Production: https://app.squarebox.ai

API Endpoints

Send Text Message

Send a plain text WhatsApp message to a customer.

POST /api/external/messaging/send_text_message

Headers:

X-API-Key: sb_your_api_key_here
Content-Type: application/json

Request Body:

{
  "phone_number": "919876543210",
  "line_id": 123,
  "message": "Hello! Your order has been confirmed.",
  "customer_name": "John Doe",
  "customer_email": "john@example.com"
}

Parameters:

phone_number (required): Customer's phone number with country code (e.g., "919876543210")
line_id (required): Your Line ID from SquareBox dashboard
message (required): The text message to send
customer_name (optional): Customer's name (creates new customer if not exists)
customer_email (optional): Customer's email (creates new customer if not exists)

Success Response (200):

{
  "success": true,
  "message": "Message sent successfully",
  "data": {
    "message_id": 456,
    "external_id": "wamid.abc123",
    "status": "sent",
    "customer_id": 789,
    "conversation_id": 101,
    "estimated_cost": 0.50
  }
}

Send Template Message

Send a WhatsApp template message with dynamic variables.

POST /api/external/messaging/send_template_message

Headers:

X-API-Key: sb_your_api_key_here
Content-Type: application/json

Request Body:

{
  "phone_number": "919876543210",
  "line_id": 123,
  "template_id": "welcome_template",
  "template_variables": {
    "customer_name": "John Doe",
    "company_name": "SquareBox"
  },
  "customer_name": "John Doe",
  "customer_email": "john@example.com"
}

Parameters:

phone_number (required): Customer's phone number with country code
line_id (required): Your Line ID from SquareBox dashboard
template_id (required): WhatsApp template ID (get from your templates)
placeholder_values (required): Dynamic values to replace in template
customer_name (optional): Customer's name
customer_email (optional): Customer's email

Success Response (200):

{
  "success": true,
  "message": "Template message sent successfully",
  "data": {
    "message_id": 456,
    "external_id": "wamid.abc123",
    "status": "sent",
    "customer_id": 789,
    "conversation_id": 101,
    "template_name": "Welcome Template",
    "estimated_cost": 0.50
  }
}

Send Media Message

Send a media message (image, video, audio, or document).

POST /api/external/messaging/send_media_message

Headers (any one):

Authorization: Bearer sb_your_api_key_here
X-API-Key: sb_your_api_key_here
API-Key: sb_your_api_key_here
Content-Type: multipart/form-data

Form Data:

phone_number: "919876543210"
line_id: "123"
media_type: "image" (options: image, video, audio, document)
media_url: "https://example.com/image.jpg"
caption: "Check out our latest product!" (optional)
customer_name: "John Doe" (optional)
customer_email: "john@example.com" (optional)

Success Response (200):

{
  "success": true,
  "message": "Media message sent successfully",
  "data": {
    "message_id": 456,
    "external_id": "wamid.abc123",
    "status": "sent",
    "customer_id": 789,
    "conversation_id": 101,
    "media_type": "image",
    "estimated_cost": 0.50
  }
}

Get Customer Info

Retrieve customer information and conversation status.

GET /api/external/messaging/get_customer_info?phone_number=919876543210&line_id=123

Headers:

X-API-Key: sb_your_api_key_here

Query Parameters:

phone_number (required): Customer's phone number with country code
line_id (required): Your Line ID from SquareBox dashboard

Success Response (200):

{
  "success": true,
  "data": {
    "customer": {
      "id": 789,
      "name": "John Doe",
      "phone_number": "919876543210",
      "email": "john@example.com",
      "active": true,
      "created_at": "2024-01-15T10:30:00Z"
    },
    "conversation": {
      "id": 101,
      "resolved": false,
      "last_message_at": "2024-01-15T10:30:00Z",
      "message_count": 5
    }
  }
}

Get Credit Balance

Check your current credit balance.

GET /api/external/messaging/credit_balance?line_id=123

Headers:

Authorization: Bearer sb_your_api_key_here

Query Parameters:

line_id (required): Your Line ID from SquareBox dashboard

Success Response (200):

{
  "success": true,
  "data": {
    "balance": 150.75,
    "currency": "INR",
    "business_name": "My Business",
    "last_updated": "2024-01-15T10:30:00Z"
  }
}

Estimate Message Cost

Get cost estimation for sending messages to specific countries.

GET /api/external/messaging/estimate_cost?line_id=123&country_code=91&message_type=text

Headers:

Authorization: Bearer sb_your_api_key_here

Query Parameters:

line_id (required): Your Line ID from SquareBox dashboard
country_code (optional): Country code (e.g., "91" for India, "1" for US)
message_type (optional): Type of message (text, template, media)

Success Response (200):

{
  "success": true,
  "data": {
    "estimated_cost": 0.50,
    "currency": "INR",
    "country": "India",
    "country_code": "91",
    "message_type": "text"
  }
}

Get Available Templates

Retrieve all available WhatsApp templates for your line.

GET /api/external/messaging/templates?line_id=123

Headers:

Authorization: Bearer sb_your_api_key_here

Query Parameters:

line_id (required): Your Line ID from SquareBox dashboard

Success Response (200):

{
  "success": true,
  "data": {
    "templates": [
      {
        "id": 1,
        "name": "Welcome Template",
        "category": "marketing",
        "language": "en",
        "status": "approved",
        "variables": ["customer_name", "company_name"]
      }
    ],
    "count": 1
  }
}

Bulk Send Messages

Send multiple messages in a single API call (up to 50 messages).

POST /api/external/messaging/bulk_send

Headers:

X-API-Key: sb_your_api_key_here
Content-Type: application/json

Request Body:

{
  "line_id": 123,
  "messages": [
    {
      "phone_number": "919876543210",
      "type": "text",
      "message": "Hello John!",
      "customer_name": "John Doe",
      "customer_email": "john@example.com"
    },
    {
      "phone_number": "919876543211",
      "type": "template",
      "template_id": 1,
      "template_variables": {
        "customer_name": "Jane Doe",
        "company_name": "SquareBox"
      },
      "customer_name": "Jane Doe"
    }
  ]
}

Success Response (200):

{
  "success": true,
  "message": "Bulk send completed: 2 successful, 0 failed",
  "data": {
    "total_messages": 2,
    "successful": 2,
    "failed": 0,
    "results": [
      {
        "phone_number": "919876543210",
        "success": true,
        "message_id": 456,
        "error": null
      },
      {
        "phone_number": "919876543211",
        "success": true,
        "message_id": 457,
        "error": null
      }
    ]
  }
}

Webhooks

Configure Webhook URL

Set up a webhook URL to receive real-time updates about message status and cost deductions.

POST /api/external/messaging/configure_webhook

Headers:

X-API-Key: sb_your_api_key_here
Content-Type: application/json

Request Body:

{
  "webhook_url": "https://your-domain.com/webhook/squarebox"
}

Success Response (200):

{
  "success": true,
  "message": "Webhook URL configured successfully",
  "data": {
    "webhook_url": "https://your-domain.com/webhook/squarebox",
    "configured_at": "2024-01-15T10:30:00Z"
  }
}

Get Webhook Configuration

Retrieve your current webhook configuration.

GET /api/external/messaging/webhook_config

Headers (any one):

Authorization: Bearer sb_your_api_key_here
X-API-Key: sb_your_api_key_here
API-Key: sb_your_api_key_here

Success Response (200):

{
  "success": true,
  "data": {
    "webhook_url": "https://your-domain.com/webhook/squarebox",
    "configured_at": "2024-01-15T10:30:00Z",
    "webhook_secret": "abc123def456..."
  }
}

Test Webhook Configuration

Test your webhook configuration by sending a test payload.

POST /api/external/messaging/test_webhook

Headers (any one):

Authorization: Bearer sb_your_api_key_here
X-API-Key: sb_your_api_key_here
API-Key: sb_your_api_key_here

Success Response (200):

{
  "success": true,
  "message": "Webhook test successful",
  "data": {
    "status_code": 200,
    "response_body": "OK"
  }
}

Webhook Events

Your webhook endpoint will receive the following events:

Message Status Updated

{
  "event": "message_status_updated",
  "timestamp": "2024-01-15T10:30:00Z",
  "business_id": 123,
  "data": {
    "message_id": 456,
    "external_id": "wamid.abc123",
    "status": "delivered",
    "customer": {
      "id": 789,
      "phone_number": "919876543210",
      "name": "John Doe"
    },
    "conversation_id": 101,
    "line_id": 123,
    "message_type": "text",
    "created_at": "2024-01-15T10:25:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Cost Deducted

{
  "event": "cost_deducted",
  "timestamp": "2024-01-15T10:30:00Z",
  "business_id": 123,
  "data": {
    "message_id": 456,
    "external_id": "wamid.abc123",
    "cost_amount": 0.50,
    "currency": "INR",
    "category": "marketing",
    "customer_country": "India",
    "remaining_balance": 149.25,
    "description": "Charged for marketing message sent to 919876543210"
  }
}

Webhook Security

All webhook payloads include a signature header for verification:

X-SquareBox-Signature: abc123def456...

To verify the signature:

const crypto = require('crypto');
const secret = 'your_webhook_secret';
const signature = req.headers['x-squarebox-signature'];
const payload = JSON.stringify(req.body);
const expectedSignature = crypto.createHmac('sha256', secret).update(payload).digest('hex');

if (signature === expectedSignature) {
  // Webhook is authentic
} else {
  // Reject webhook
}

Cost Management

How Costs Work

Cost Estimation: Use the estimate_cost endpoint to check message costs before sending
Credit Check: The API checks if you have sufficient credits before sending messages
Cost Deduction: Credits are deducted via webhook when message status becomes 'sent'
Real-time Updates: Receive webhook notifications when costs are deducted

Cost Structure

Country-based pricing: Different costs for different countries
Message type pricing: Templates may have different costs than text messages
Real-time deduction: Only charged when message is successfully sent
Transparent billing: Full cost breakdown in webhook notifications

Rate Limiting

100 requests per hour per API key
10 requests per minute for all endpoints
When limits are exceeded, you will receive HTTP 429 with an error message

Examples

cURL Examples

Send Text Message

curl -X POST https://app.squarebox.ai/api/external/messaging/send_text_message \
  -H "X-API-Key: sb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "919876543210",
    "line_id": 123,
    "message": "Hello! Your order has been confirmed.",
    "customer_name": "John Doe",
    "customer_email": "john@example.com"
  }'

Check Credit Balance

curl -X GET "https://app.squarebox.ai/api/external/messaging/credit_balance?line_id=123" \
  -H "X-API-Key: sb_your_api_key_here"

Estimate Cost

curl -X GET "https://app.squarebox.ai/api/external/messaging/estimate_cost?line_id=123&country_code=91" \
  -H "X-API-Key: sb_your_api_key_here"

Bulk Send Messages

curl -X POST https://app.squarebox.ai/api/external/messaging/bulk_send \
  -H "X-API-Key: sb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "line_id": 123,
    "messages": [
      {
        "phone_number": "919876543210",
        "type": "text",
        "message": "Hello John!",
        "customer_name": "John Doe"
      },
      {
        "phone_number": "919876543211",
        "type": "text",
        "message": "Hello Jane!",
        "customer_name": "Jane Doe"
      }
    ]
  }'

Configure Webhook

curl -X POST https://app.squarebox.ai/api/external/messaging/configure_webhook \
  -H "X-API-Key: sb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-domain.com/webhook/squarebox"
  }'

JavaScript Example

// Send text message with cost estimation
const sendTextMessage = async () => {
  const response = await fetch('https://app.squarebox.ai/api/external/messaging/send_text_message', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sb_your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      phone_number: '919876543210',
      line_id: 123,
      message: 'Hello! Your order has been confirmed.',
      customer_name: 'John Doe',
      customer_email: 'john@example.com'
    })
  });
  
  const result = await response.json();
  console.log('Estimated cost:', result.data.estimated_cost);
  console.log('Message ID:', result.data.message_id);
};

// Check credit balance
const checkBalance = async () => {
  const response = await fetch('https://app.squarebox.ai/api/external/messaging/credit_balance?line_id=123', {
    headers: {
      'Authorization': 'Bearer sb_your_api_key_here'
    }
  });
  
  const result = await response.json();
  console.log('Current balance:', result.data.balance);
};

Python Example

import requests

# Send text message
def send_text_message():
    url = 'https://app.squarebox.ai/api/external/messaging/send_text_message'
    headers = {
        'Authorization': 'Bearer sb_your_api_key_here',
        'Content-Type': 'application/json'
    }
    data = {
        'phone_number': '919876543210',
        'line_id': 123,
        'message': 'Hello! Your order has been confirmed.',
        'customer_name': 'John Doe',
        'customer_email': 'john@example.com'
    }
    
    response = requests.post(url, headers=headers, json=data)
    result = response.json()
    print(f"Estimated cost: {result['data']['estimated_cost']}")

# Bulk send messages
def bulk_send_messages():
    url = 'https://app.squarebox.ai/api/external/messaging/bulk_send'
    headers = {
        'Authorization': 'Bearer sb_your_api_key_here',
        'Content-Type': 'application/json'
    }
    data = {
        'line_id': 123,
        'messages': [
            {
                'phone_number': '919876543210',
                'type': 'text',
                'message': 'Hello John!',
                'customer_name': 'John Doe'
            },
            {
                'phone_number': '919876543211',
                'type': 'text',
                'message': 'Hello Jane!',
                'customer_name': 'Jane Doe'
            }
        ]
    }
    
    response = requests.post(url, headers=headers, json=data)
    result = response.json()
    print(f"Successfully sent: {result['data']['successful']} messages")

Error Handling

Error Response Format

{
  "success": false,
  "error": "Error message description",
  "timestamp": "2024-01-15T10:30:00Z"
}

Common Error Codes

Code

Description

Solution

400

Bad Request

Check request parameters

401

Unauthorized

Verify API key is correct

402

Payment Required

Add credits to your account

403

Forbidden

Check if API key has permissions

404

Not Found

Verify line_id or template_id exists

422

Unprocessable Entity

Check phone number format

429

Too Many Requests

Wait before making more requests

500

Internal Server Error

Contact support

Common Errors

Insufficient Credits

{
  "success": false,
  "error": "Insufficient credits to send message",
  "timestamp": "2024-01-15T10:30:00Z"
}

Rate Limit Exceeded

{
  "success": false,
  "error": "Hourly rate limit exceeded",
  "timestamp": "2024-01-15T10:30:00Z"
}

Invalid Phone Number

{
  "success": false,
  "error": "Invalid phone number format",
  "timestamp": "2024-01-15T10:30:00Z"
}

Support

For API support and questions:

Email: api-support@squarebox.ai
Documentation: https://docs.squarebox.ai
Status Page: https://status.squarebox.ai

Last updated: January 15, 2024

PreviousAPI-docs

Table of Contents

Overview

Getting Started

1. Generate API Key

2. Get Your Line ID

Authentication

Base URL

API Endpoints

Send Text Message

Send Template Message

Send Media Message

Get Customer Info

Get Credit Balance

Estimate Message Cost

Get Available Templates

Bulk Send Messages

Webhooks

Configure Webhook URL

Get Webhook Configuration

Test Webhook Configuration

Webhook Events

Message Status Updated

Cost Deducted

Webhook Security

Cost Management

How Costs Work

Cost Structure

Rate Limiting

Examples

cURL Examples

Send Text Message

Check Credit Balance

Estimate Cost

Bulk Send Messages

Configure Webhook

JavaScript Example

Python Example

Error Handling

Error Response Format

Common Error Codes

Common Errors

Insufficient Credits

Rate Limit Exceeded

Invalid Phone Number

Support