# 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.

## Table of Contents

* [Overview](#overview)
* [Getting Started](#getting-started)
* [Authentication](#authentication)
* [API Endpoints](#api-endpoints)
* [Webhooks](#webhooks)
* [Cost Management](#cost-management)
* [Rate Limiting](#rate-limiting)
* [Examples](#examples)
* [Error Handling](#error-handling)

## 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

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

### 2. Get Your Line ID

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

## Authentication

Use this header:

* X-API-Key: sb\_your\_api\_key\_here

Example:

```http
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.

```http
POST /api/external/messaging/send_text_message
```

**Headers:**

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

**Request Body:**

```json
{
  "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):**

```json
{
  "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.

```http
POST /api/external/messaging/send_template_message
```

**Headers:**

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

**Request Body:**

```json
{
  "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):**

```json
{
  "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).

```http
POST /api/external/messaging/send_media_message
```

**Headers (any one):**

```http
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):**

```json
{
  "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.

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

**Headers:**

```http
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):**

```json
{
  "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.

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

**Headers:**

```http
Authorization: Bearer sb_your_api_key_here
```

**Query Parameters:**

* `line_id` (required): Your Line ID from SquareBox dashboard

**Success Response (200):**

```json
{
  "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.

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

**Headers:**

```http
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):**

```json
{
  "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.

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

**Headers:**

```http
Authorization: Bearer sb_your_api_key_here
```

**Query Parameters:**

* `line_id` (required): Your Line ID from SquareBox dashboard

**Success Response (200):**

```json
{
  "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).

```http
POST /api/external/messaging/bulk_send
```

**Headers:**

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

**Request Body:**

```json
{
  "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):**

```json
{
  "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.

```http
POST /api/external/messaging/configure_webhook
```

**Headers:**

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

**Request Body:**

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

**Success Response (200):**

```json
{
  "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.

```http
GET /api/external/messaging/webhook_config
```

**Headers (any one):**

```http
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):**

```json
{
  "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.

```http
POST /api/external/messaging/test_webhook
```

**Headers (any one):**

```http
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):**

```json
{
  "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

```json
{
  "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

```json
{
  "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:

```http
X-SquareBox-Signature: abc123def456...
```

To verify the signature:

```javascript
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

1. **Cost Estimation**: Use the `estimate_cost` endpoint to check message costs before sending
2. **Credit Check**: The API checks if you have sufficient credits before sending messages
3. **Cost Deduction**: Credits are deducted via webhook when message status becomes 'sent'
4. **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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```javascript
// 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

```python
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

```json
{
  "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

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

#### Rate Limit Exceeded

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

#### Invalid Phone Number

```json
{
  "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*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://squarebox-ai.gitbook.io/squarebox/untitled/api-docs/squarebox-external-api-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.