API Documentation - CoreMessage

Overview

The CoreMessage API allows you to send SMS messages through our relay server. All requests must be authenticated using an API key.

Base URL

http://localhost:8000/relay/

Authentication

All API requests require authentication via the X-Proxy-Auth header.

X-Proxy-Auth: your_api_key_here

Important

Keep your API keys secure. Never expose them in client-side code or public repositories.

Send SMS

POST /relay/sms

Send an SMS message through the relay server.

Request Headers

Header	Type	Description
`X-Proxy-Auth`	string	Your API key
`Content-Type`	string	application/json

Request Body

Parameter	Type	Required	Description
`To`	string	Yes	Recipient phone number (E.164 format)
`From`	string	No	Sender phone number
`Body`	string	Yes	Message content

Example Request

curl -X POST http://localhost:8000/relay/sms \
  -H "X-Proxy-Auth: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "To": "+1234567890",
    "From": "+0987654321",
    "Body": "Hello from CoreMessage!"
  }'

Success Response (200 OK)

                            {
  "sid": "SM1234567890abcdef",
  "status": "queued",
  "cost": "0.0075",
  "remaining_balance": "99.9925"
}
                        

Telegram Bot Integration Guide

1. Connecting a BotFather token

Create a bot with @BotFather on Telegram (/newbot) and copy the token. Store it in CoreMessage via the secure portal: Secure Portal → Telegram Bots → Add Telegram Bot. The token is encrypted at rest (Fernet) and only ever displayed in masked form, e.g. 12345...abcd.

2. Sending Telegram messages

POST /api/telegram — channel: telegram

Field	Type	Required	Description
`to`	string	Yes	Telegram chat_id (user, group, or channel id)
`message`	string	Yes	Message text (HTML parse mode)

curl -X POST https://coremessage.uzhavoorlive.com/api/telegram \
  -H "X-Proxy-Auth: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "123456789",
    "message": "Hello from CoreMessage!"
  }'

import requests

response = requests.post(
    "https://coremessage.uzhavoorlive.com/api/telegram",
    headers={"X-Proxy-Auth": "your_api_key", "Content-Type": "application/json"},
    json={"to": "123456789", "message": "Hello from CoreMessage!"},
    timeout=20,
)
print(response.status_code, response.json())

3. Receiving Telegram messages (webhook + relay polling)

Point your bot's webhook at CoreMessage (BotFather /setwebhook or the Bot API directly), then poll the relay for inbound messages, or simply poll /api/telegram/updates:

# Register the webhook (do this once)
curl "https://api.telegram.org/botYOUR_BOTFAATHER_TOKEN/setWebhook" \
  -d "url=https://coremessage.uzhavoorlive.com/api/webhooks/telegram/1/"

# Poll inbound Telegram messages (relay API, channel=telegram)
curl "https://coremessage.uzhavoorlive.com/api/relay/messages/poll/?channel=telegram" \
  -H "X-Proxy-Auth: your_api_key"

import time
import requests

BASE = "https://coremessage.uzhavoorlive.com"
HEADERS = {"X-Proxy-Auth": "your_api_key"}
since_id = 0

while True:
    resp = requests.get(
        f"{BASE}/api/relay/messages/poll/",
        params={"channel": "telegram", "since_id": since_id, "limit": 50},
        headers=HEADERS,
        timeout=20,
    )
    resp.raise_for_status()
    data = resp.json()
    for msg in data["results"]:
        if msg["communication_type"] == "telegram":
            print(f"[{msg['from_number']}] {msg['body']}")
    since_id = data["next_since_id"]
    if not data["results"]:
        time.sleep(2)

Acknowledge processed messages with POST /api/relay/messages/ack/.

Webhooks

POST

Receives status callbacks for message delivery updates.

Webhook Events

queued - Message queued for delivery
sent - Message sent to carrier
delivered - Message delivered to recipient
failed - Message delivery failed

Error Codes

Code	Status	Description
`400`	Bad Request	Missing required parameters (To or Body)
`401`	Unauthorized	Invalid or missing API key
`402`	Payment Required	Insufficient account balance
`500`	Internal Server Error	No routing rule found or gateway error

Code Examples

Python

import requests

url = "http://localhost:8000/relay/sms"
headers = {
    "X-Proxy-Auth": "your_api_key",
    "Content-Type": "application/json"
}
data = {
    "To": "+1234567890",
    "Body": "Hello World"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');

const response = await axios.post(
  'http://localhost:8000/relay/sms',
  {
    To: '+1234567890',
    Body: 'Hello World'
  },
  {
    headers: {
      'X-Proxy-Auth': 'your_api_key',
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);