# Integrax — AI Integration Context
# Last updated: 2026-04-12
# URL: https://integrax.lat
# Dashboard: https://integrax.app
# This file is designed to be pasted into AI assistants (ChatGPT, Claude, Gemini, etc.)
# so they can integrate Integrax messaging APIs into your project automatically.

## What is Integrax?

Integrax is a CPaaS (Communications Platform as a Service) that provides SMS, RCS, OTP verification, number validation, and messaging automation APIs. It offers direct carrier connections in 70+ countries with sub-100ms latency.

## Authentication

All API calls use a **token** passed in the URL path. You get your token at https://integrax.app after creating a free account.

Base URL: `https://sms.aresfun.com`

Pattern: `POST /v1/integration/{TOKEN}/endpoint`

No header-based auth needed — the token is part of the URL.

---

## API Endpoints

### 1. Send SMS

**POST** `/v1/integration/{TOKEN}/send-sms`

Send SMS to one or multiple phone numbers.

Request:
```json
{
  "to": ["5511999999999"],
  "from": "29094",
  "message": "Your message here"
}
```

- `to` (required): Array of phone numbers in E.164 format (country code + number, no "+")
- `from` (optional): Shortcode or sender ID. Default is Integrax's shared shortcode.
- `message` (required): SMS text content (up to 160 chars for 1 segment, or multi-part)

Response:
```json
{
  "error": 0,
  "code": "SMS_SENT",
  "message": "SMS sent successfully",
  "data": {
    "messageId": "abc123",
    "status": "SENT_TO_OPERATOR"
  }
}
```

### 2. Send OTP (One-Time Password)

**POST** `/v1/integration/{TOKEN}/send-otp`

Generate and send a verification code via SMS.

Request:
```json
{
  "to": "5511999999999",
  "message_default": "Your verification code is: [code]",
  "from": "29094",
  "qtd_digits": 6,
  "with_text": false,
  "expires_in": 5
}
```

- `to` (required): Phone number (E.164, no "+")
- `message_default` (optional): Custom message. Use `[code]` as placeholder for the generated code.
- `from` (optional): Shortcode or sender ID
- `qtd_digits` (optional): Number of digits in the code. Default: 6
- `with_text` (optional): If `true`, code includes letters (e.g., "1MP5L"). Default: `false` (numeric only)
- `expires_in` (optional): Expiration time in minutes. Default: 5

Response:
```json
{
  "error": 0,
  "code": "OTP_SENT",
  "message": "OTP sent successfully"
}
```

### 3. Verify OTP

**POST** `/v1/integration/{TOKEN}/verify-otp`

Validate the OTP code entered by the user.

Request:
```json
{
  "code": "176258",
  "phone": "5511999999999"
}
```

- `code` (required): The code the user entered
- `phone` (required): The phone number that received the OTP

Response:
```json
{
  "error": 0,
  "code": "176258",
  "phone": "5511999999999",
  "valid": true
}
```

`valid`: `true` if the code is correct and not expired, `false` otherwise.

### 4. Consult Phone (Number Validation / HLR Lookup)

**POST** `/v1/integration/{TOKEN}/consult-phone`

Validate phone numbers, check carrier info, and detect WhatsApp availability.

Request:
```json
{
  "phones": ["5511999999999", "5511998888888"]
}
```

- `phones` (required): Array of phone numbers to validate (max 20 per request on free tier)

Response:
```json
{
  "error": 0,
  "code": "CONSULT_OK",
  "message": "Consult OK successfully",
  "cost_phone": 0.005,
  "cost_total": 0.005,
  "data": [
    {
      "numero_requisitado": "11999999999",
      "whatsapp": "Sim",
      "operadora": "Claro"
    }
  ]
}
```

- `numero_requisitado`: The phone number queried
- `whatsapp`: "Sim" (has WhatsApp) or "Não" (no WhatsApp)
- `operadora`: Mobile carrier name

### 5. Send RCS (Rich Communication Services)

**POST** `/v1/integration/{TOKEN}/send-rcs`

Send rich messages with media, carousels, and action buttons. Automatic fallback to SMS if the device doesn't support RCS.

Request (simple text):
```json
{
  "to": ["5511999999999"],
  "message": "Hello via RCS!"
}
```

Request (rich card):
```json
{
  "to": ["5511999999999"],
  "rich": {
    "title": "Order Confirmed",
    "description": "Your order #1234 has been confirmed.",
    "media_url": "https://example.com/image.jpg",
    "suggestions": [
      { "text": "Track Order", "postback": "track_1234" },
      { "text": "Contact Support", "postback": "support" }
    ]
  }
}
```

Features:
- Cards and carousels with images
- Suggested actions and quick replies
- Read receipts and typing indicators
- Automatic SMS fallback for non-RCS devices (including iPhone)

---

## SDKs

Install the official SDK for your language:

### Node.js / TypeScript
```bash
npm install integrax-sdk
```
```typescript
import { Integrax } from "integrax-sdk";

const ix = new Integrax("YOUR_TOKEN");

// Send SMS
await ix.sms.send(["5511999999999"], "Hello from Integrax!");

// Send OTP
await ix.otp.send("5511999999999", {
  message_default: "Your code: [code]",
  qtd_digits: 6,
  expires_in: 5,
});

// Verify OTP
const result = await ix.otp.verify("176258", "5511999999999");
// result.valid === true
```

### Python
```bash
pip install integrax
```
```python
from integrax import Integrax

ix = Integrax("YOUR_TOKEN")

# Send SMS
ix.sms.send(["5511999999999"], "Hello from Integrax!")

# Send OTP
ix.otp.send("5511999999999", message_default="Your code: [code]")

# Verify OTP
result = ix.otp.verify("176258", "5511999999999")
# result.valid == True
```

### PHP
```bash
composer require integrax/integrax-php
```
```php
use Integrax\Integrax;

$ix = new Integrax("YOUR_TOKEN");

// Send SMS
$ix->sms->send(["5511999999999"], "Hello from Integrax!");

// Send OTP
$ix->otp->send("5511999999999", [
    "message_default" => "Your code: [code]",
    "qtd_digits" => 6,
]);

// Verify OTP
$result = $ix->otp->verify("176258", "5511999999999");
// $result->valid === true
```

### Go
```bash
go get github.com/IntegraX-lat/integrax-go
```
```go
import "github.com/IntegraX-lat/integrax-go"

ix := integrax.New("YOUR_TOKEN")

// Send SMS
ix.SMS.Send([]string{"5511999999999"}, "Hello from Integrax!")
```

### C# / .NET
```bash
dotnet add package Integrax
```
```csharp
using Integrax;

var ix = new IntegraClient("YOUR_TOKEN");

// Send SMS
await ix.Sms.SendAsync(new[] { "5511999999999" }, "Hello from Integrax!");
```

---

## REST API (No SDK / cURL)

If you prefer direct HTTP calls without an SDK:

### Send SMS via cURL
```bash
curl -X POST "https://sms.aresfun.com/v1/integration/YOUR_TOKEN/send-sms" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["5511999999999"],
    "message": "Hello from Integrax!"
  }'
```

### Send OTP via cURL
```bash
curl -X POST "https://sms.aresfun.com/v1/integration/YOUR_TOKEN/send-otp" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "message_default": "Your verification code is: [code]",
    "qtd_digits": 6,
    "expires_in": 5
  }'
```

### Verify OTP via cURL
```bash
curl -X POST "https://sms.aresfun.com/v1/integration/YOUR_TOKEN/verify-otp" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "176258",
    "phone": "5511999999999"
  }'
```

---

## Webhooks (DLR - Delivery Reports)

Configure a webhook URL in your Integrax dashboard to receive delivery status updates.

Webhook payload:
```json
{
  "messageId": "abc123",
  "status": "DELIVRD",
  "phone": "5511999999999",
  "timestamp": "2026-04-12T10:30:00Z"
}
```

Possible statuses: `DELIVRD` (delivered), `EXPIRED`, `REJECTD`, `UNDELIV` (undeliverable)

Integrax retries webhook delivery with exponential backoff if your endpoint doesn't respond with 2xx.

---

## Quick Integration Checklist

1. Create a free account at https://integrax.app
2. Generate your API token in the dashboard (Settings > API Tokens)
3. Install the SDK for your language OR use direct REST calls
4. Replace `YOUR_TOKEN` with your actual token
5. Use E.164 phone format: country code + number, no "+" prefix (e.g., "5511999999999" for Brazil)
6. (Optional) Set up a webhook URL for delivery reports

## Phone Number Format

Always use E.164 format WITHOUT the "+" prefix:
- Brazil: `5511999999999` (55 = country code)
- Mexico: `5215551234567`
- USA: `12125551234`
- Argentina: `5491123456789`
- Portugal: `351912345678`

## Error Codes

- `error: 0` — Success
- `error: 1` — Invalid parameters
- `error: 2` — Insufficient balance
- `error: 3` — Invalid token
- `error: 4` — Rate limited

## Rate Limits

- Free tier: 1000+ SMS/sec throughput
- No hard rate limit on API calls — throughput scales with your plan
- OTP: codes expire based on `expires_in` parameter (default 5 minutes)

## Support

- Dashboard: https://integrax.app
- Website: https://integrax.lat
- Playground (test for free): https://integrax.lat/playground