MsgHub REST API

Programmatic access to MsgHub through one REST API. Auth with a Bearer API key, send template messages on any channel, manage contacts, track events, and trigger campaigns. JSON over HTTPS. One unified POST /messages/send endpoint — the template's channel determines whether the message is dispatched as SMS, WhatsApp, Email or RCS.

Quick start

Send your first message in 60 seconds. Two steps: create the contact, then send a message referencing one of your approved templates. Replace YOUR_API_KEY with a key generated from the API Keys page in the sidebar, and TEMPLATE_UUID with a template ID from Templates.

# 1. Upsert the contact
curl https://app.msghub.info/api/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+919876543210", "name": "Riya" }'

# 2. Send a message using an approved template
curl https://app.msghub.info/api/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to":         { "phone": "+919876543210" },
    "templateId": "TEMPLATE_UUID"
  }'

# Response (201 Created)
{
  "success": true,
  "data": {
    "messageId": "",
    "status": "queued"
  }
}

Authentication

Every request must include a Bearer API key in the Authorization header:

Authorization: Bearer mh_live_xxxxxxxxxxxxxxxxxxxxxxxx

API keys are scoped to a single tenant. To create one: sidebar → API Keys → "+ New API Key". Pick a name and tick the scopes you need. Keys are shown once at creation — copy and store securely.

Scopes

Pick the minimum set when creating a key:

Base URL & versioning

https://app.msghub.info/api/v1

The dashboard and API share the same domain. All public endpoints live under the /api/v1 prefix. Future breaking changes ship as /api/v2.

Request format

• Method: standard REST verbs — GET, POST.
• Body: JSON. Content-Type: application/json required on POST.
• Phone numbers: include country code with leading + — e.g. +919876543210. Stored as-is per tenant.
• IDs: UUIDs (templates, campaigns, messages). Treat as opaque strings.
• CORS: all /api/v1/* responses include Access-Control-Allow-Origin: * so the API can be called cross-origin from browser SDKs and widget integrations.

Response format

Every response uses a consistent envelope: { success: true, data: … } on the happy path, { success: false, error: { code, message } } on failure.

// Successful POST → 201 Created
{
  "success": true,
  "data": {
    "id": "",
    "created": true
  }
}

// List GET → 200 OK
{
  "success": true,
  "data": [ /* rows */ ]
}

// Failure
{
  "success": false,
  "error": { "code": "VALIDATION_ERROR", "message": "…" }
}

Error codes

All errors return the failure envelope above. Common codes you'll encounter:

Rate limits

• Global cap: 300 requests/minute per source IP across all endpoints.
• Researcher-tier tenants (vulnerability-disclosure participants): 60 req/minute per API key, enforced via Redis counter.
• Webhook receivers: 1000/minute (handled by a separate webhook scope).

Exceeding the cap returns:

HTTP 429 Too Many Requests
{
  "success": false,
  "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please slow down." }
}

Honour the response and back off. Higher limits available on request for enterprise plans.

Pagination

List endpoints (e.g. GET /contacts) use simple page + limit query parameters:

GET /api/v1/contacts?page=1&limit=50

# Response
{
  "success": true,
  "data": [ /* up to `limit` rows */ ]
}

page is 1-indexed. limit defaults to 50, capped at 100. Increment page until you receive an empty array.

Endpoints

Six public endpoints under /api/v1. There is no per-channel send endpoint — one unified /messages/send with a templateId handles every channel. Conversation listing and template submission are dashboard-only for now.

Send a message

POST /api/v1/messages/send
Authorization: Bearer mh_live_...
Content-Type: application/json

{
  "to":         { "phone": "+919876543210" },
  "templateId": "e2f8b1a0-…-uuid"
}

{
  "success": true,
  "data": {
    "messageId": "",
    "status": "queued"
  }
}

Contacts

// 201 Created (new) or 200 OK (updated)
{
  "success": true,
  "data": { "id": "", "created": true }
}

Events

Trigger a campaign

Templates

{
  "success": true,
  "data": [
    { "id": "", "name": "order_shipped", "channel": "whatsapp", "smsBody": null }
  ]
}

Webhooks

MsgHub can push real-time events to your server — delivery receipts, contact unsubscribes, campaign completion. Add endpoints from the Webhooks page in the sidebar (top-level item, not nested under Settings).

Webhooks are signed with HMAC-SHA256. The signature header uses a Stripe-style t={timestamp},v1={signature} format. Verify on every incoming request.

SDKs & examples

A JavaScript SDK is available at https://app.msghub.info/api/v1/sdk.js — drop one script tag and call MsgHub.identify(), track(), send(). For server-side, use any HTTP client.

Browser SDK (no install)

<!-- in your HTML -->
<script>
  window.MsgHub = {
    apiUrl: 'https://app.msghub.info',
    apiKey: 'mh_live_…'  // public-scope only — never an admin key
  };
</script>
<script src="https://app.msghub.info/api/v1/sdk.js" async></script>

<script>
  // Identify the visitor (creates / updates the contact)
  MsgHub.identify({ phone: '+919876543210', email: '[email protected]', name: 'Ravi' });

  // Track a custom event
  MsgHub.track('cart.abandoned', { phone: '+919876543210' });
</script>

Node.js (vanilla)

const base = 'https://app.msghub.info/api/v1';
const headers = {
  'Authorization': `Bearer ${process.env.MSGHUB_KEY}`,
  'Content-Type': 'application/json',
};

// 1. Upsert the contact
await fetch(`${base}/contacts`, {
  method: 'POST', headers,
  body: JSON.stringify({ phone: customer.phone, name: customer.name }),
});

// 2. Send an approved template
const res = await fetch(`${base}/messages/send`, {
  method: 'POST', headers,
  body: JSON.stringify({
    to:         { phone: customer.phone },
    templateId: 'e2f8b1a0-…-uuid',
  }),
});
const data = await res.json();
if (!data.success) throw new Error(data.error.message);

Python (requests)

import requests, os

base    = "https://app.msghub.info/api/v1"
headers = { "Authorization": f"Bearer {os.environ['MSGHUB_KEY']}" }

# Upsert contact
requests.post(f"{base}/contacts", headers=headers,
              json={"phone": customer.phone, "name": customer.name})

# Send approved template
resp = requests.post(f"{base}/messages/send", headers=headers,
                     json={ "to": {"phone": customer.phone}, "templateId": template_id })
resp.raise_for_status()
data = resp.json()
if not data["success"]:
    raise Exception(data["error"]["message"])

PHP (cURL)

$base    = 'https://app.msghub.info/api/v1';
$headers = [
    'Authorization: Bearer ' . getenv('MSGHUB_KEY'),
    'Content-Type: application/json',
];

// Send approved template
$ch = curl_init($base . '/messages/send');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => $headers,
    CURLOPT_POSTFIELDS     => json_encode([
        'to'         => ['phone' => $customer->phone],
        'templateId' => $templateId,
    ]),
]);
$data = json_decode(curl_exec($ch), true);

Other integrations

For point-and-click integration without writing code:

• Zapier — sidebar → Integrations → Zapier tab. Triggers (new message, new contact, message status) and Actions (send SMS, send WhatsApp, add contact, trigger flow).
• Shopify — sidebar → Integrations → Shopify. Embedded signup, then per-event automations.
• Zoho CRM / HubSpot — sidebar → Integrations → CRM tab. OAuth2 flow + contact sync.
• Odoo — sidebar → Integrations → Odoo ERP. Provides a webhook URL + Python snippet for the Odoo side.

FAQ

What's next