API Documentation - InfiniReach

Quick Start

The InfiniReach API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Base URL

https://api.infinireach.io

Authentication

All API requests require authentication using an API key. Include your API key in the request headers:

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

⚠️ Security: Keep your API keys secure. Don't share them in publicly accessible code or repositories.

Send Message

Send an SMS or WhatsApp message through your registered devices.

POST /api/v1/messages

Request Body

{
  "to": "+1234567890",
  "message": "Hello from InfiniReach!",
  "from": "+15559876543",  // required: sender phone number
  "channel": "sms",  // required: "sms" or "whatsapp"
  "externalId": "optional-unique-id"  // optional: for idempotency
}

Parameters

✅ Required. Destination. For SMS use E.164 (+1234567890). For WhatsApp use E.164 (1:1) or the real group JID (<group-id>@g.us). You may paste the contact key from the app: group:<instanceId>:<group-id>@g.us or <instanceId>:<group-id>@g.us — both are normalized to <group-id>@g.us before send (the instance id is only for matching the contact row, not sent to WhatsApp).

message

✅ Required. Message text (max 1600 characters)

from

✅ Required. Sender phone number from your registered devices/WhatsApp instances. Must match exactly.

channel

✅ Required. Message channel: "sms" or "whatsapp"

externalId

Optional. Your unique ID for idempotency (prevents duplicate sends)

⚠️ Multi-Tenant Security: The from and channel fields are required for security in our multi-tenant system. You must specify exactly which device/WhatsApp instance to use. The system will verify that the specified device belongs to your account.

Response

{
  "success": true,
  "queued": true,
  "messageId": "6741234567890abcdef12345",
  "jobId": "job-6741234567890abcdef12345"
}

Example Requests (cURL)

Send SMS

curl -X POST https://api.infinireach.io/api/v1/messages \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890",
    "message": "Hello from InfiniReach!",
    "from": "+15559876543",
    "channel": "sms"
  }'

Send WhatsApp

curl -X POST https://api.infinireach.io/api/v1/messages \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890",
    "message": "Hello via WhatsApp!",
    "from": "+15559876543",
    "channel": "whatsapp"
  }'

curl -X POST https://api.infinireach.io/api/v1/messages \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "120363043049692322@g.us",
    "message": "Hello group via WhatsApp!",
    "from": "+15559876543",
    "channel": "whatsapp"
  }'

curl -X POST https://api.infinireach.io/api/v1/messages \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "group:69b605fdd822e2a741b3bd95:120363423156426110@g.us",
    "message": "Hello group using contact key",
    "from": "+15559876543",
    "channel": "whatsapp"
  }'

Read Messages

Read message history with flexible filters. Results include all messages for your account (agency); API keys created under a workspace still list agency-wide history. By default, messages are returned newest first.

GET /api/v1/messages

Query Parameters

limit

Optional. Number of results per request (default 100, max 500)

offset

Optional. Skip this many rows for pagination (default 0)

order

Optional. Sort by created date: desc (default, newest first) or asc

direction

Optional. Filter by message direction (for example inbound or outbound)

from

Optional. Sender phone in E.164. Alias: e164From

Optional. Recipient phone in E.164. Alias: e164To

conversation

When both from and to are set, matching both directions (SMS thread) is the default. Pass conversation=false or conversation=strict to require that exact from→to direction only. Alias: pair

channel

Optional. Filter by channel: sms or whatsapp

status

Optional. Filter by delivery status (for example queued, sent, delivered, failed)

Optional. Case-insensitive text search in message body

since

Optional. Lower time bound (ISO timestamp or epoch milliseconds)

until

Optional. Upper time bound (ISO timestamp or epoch milliseconds)

Response

{
  "messages": [
    {
      "_id": "6741234567890abcdef12345",
      "direction": "inbound",
      "e164From": "+1234567890",
      "e164To": "+15559876543",
      "body": "Hello, checking in",
      "status": "delivered",
      "createdAt": "2026-03-31T05:20:14.123Z"
    }
  ],
  "total": 240,
  "returned": 1,
  "limit": 1,
  "offset": 0,
  "order": "desc",
  "filters": {
    "direction": "inbound",
    "from": null,
    "to": "+15559876543",
    "channel": "sms",
    "status": null,
    "q": null,
    "since": "2026-03-01T00:00:00.000Z",
    "until": null
  }
}

Example Requests (cURL)

Get latest 20 messages (newest first)

curl "https://api.infinireach.io/api/v1/messages?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Filter by sender and direction

curl "https://api.infinireach.io/api/v1/messages?from=%2B1234567890&direction=inbound&limit=50" \
  -H "X-API-Key: YOUR_API_KEY"

Time window query

curl "https://api.infinireach.io/api/v1/messages?since=2026-03-01T00:00:00Z&until=2026-03-31T23:59:59Z&order=asc" \
  -H "X-API-Key: YOUR_API_KEY"

Text search in body

curl "https://api.infinireach.io/api/v1/messages?q=invoice&channel=sms&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

Webhooks

Receive real-time notifications about message events, device status changes, and more.

Configure Webhook URL

Set your webhook URL in the dashboard under Integrations → Webhooks. InfiniReach will send POST requests to your URL for configured events.

Webhook Events

message.inbound

Triggered when an inbound message is received

message.delivered

Triggered when a message is successfully delivered

message.failed

Triggered when a message fails to send

ℹ️ Note: Message delivery status is available via webhooks. Configure webhook events to receive real-time status updates for your sent messages.

Webhook Payload Example

{
  "event": "message.inbound",
  "timestamp": "2024-10-25T10:30:00Z",
  "data": {
    "messageId": "6741234567890abcdef12345",
    "direction": "inbound",
    "from": "+1234567890",
    "to": "+0987654321",
    "body": "Hello! I need support",
    "deviceId": "device-123",
    "timestamp": "2024-10-25T10:30:00Z",
    "status": "delivered"
  }
}

🔒 Webhook Security: All webhook requests include a signature headerX-Webhook-Signature (when a secret is set) that you can verify.

HTTP Status Codes

200

Request succeeded

201

Created

Resource successfully created

400

Bad Request

Invalid request parameters

401

Unauthorized

Invalid or missing API key

404

Not Found

Resource not found

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Something went wrong on our end

Rate Limits

The API has the following rate limits per API key:

Message Sending100 requests/minute

ℹ️ Note: Rate limits may vary based on your subscription plan. Contact us if you need higher limits.