Phone & SMS Quickstart

npm install commune-ai

pip install commune-mail

import { CommuneClient } from 'commune-ai';

const commune = new CommuneClient({
  apiKey: process.env.COMMUNE_API_KEY,
});

from commune import CommuneClient

client = CommuneClient(api_key="comm_...")
# Or set COMMUNE_API_KEY env var and call CommuneClient()

const available = await commune.phoneNumbers.search({
  country: 'US',
  type: 'local',
  areaCode: '415',
  capabilities: { sms: true },
});

console.log(available[0].phoneNumber);  // +14155550001

available = client.phone_numbers.search(
    country="US",
    type="local",
    area_code="415",
    capabilities={"sms": True},
)

print(available[0].phone_number)  # +14155550001

curl -X GET "https://api.commune.email/v1/phone-numbers/available?country=US&type=local&area_code=415" \
  -H "Authorization: Bearer comm_..."

const phoneNumber = await commune.phoneNumbers.purchase({
  number: '+14155550001',
  friendlyName: 'Support Line',
});

console.log(phoneNumber.id);     // pn_01abc123
console.log(phoneNumber.number); // +14155550001
console.log(phoneNumber.status); // active

phone_number = client.phone_numbers.purchase(
    number="+14155550001",
    friendly_name="Support Line",
)

print(phone_number.id)     # pn_01abc123
print(phone_number.status) # active

curl -X POST https://api.commune.email/v1/phone-numbers/purchase \
  -H "Authorization: Bearer comm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+14155550001",
    "friendlyName": "Support Line"
  }'

const message = await commune.sms.send({
  phone_number_id: phoneNumber.id,
  to: '+14155559999',
  body: 'Hello from your AI agent!',
});

console.log(message.message_id);      // sms_SM01abc123
console.log(message.status);          // accepted
console.log(message.credits_charged); // 2

message = client.sms.send(
    phone_number_id=phone_number.id,
    to="+14155559999",
    body="Hello from your AI agent!",
)

print(message.message_id)
print(message.status)          # accepted
print(message.credits_charged) # 2

curl -X POST https://api.commune.email/v1/sms/send \
  -H "Authorization: Bearer comm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "pn_01abc123",
    "to": "+14155559999",
    "body": "Hello from your AI agent!"
  }'

await commune.phoneNumbers.update(phoneNumber.id, {
  webhook: {
    url: 'https://your-server.com/webhooks/sms',
  },
});

client.phone_numbers.update(
    phone_number.id,
    webhook={"url": "https://your-server.com/webhooks/sms"},
)

curl -X PATCH https://api.commune.email/v1/phone-numbers/pn_01abc123 \
  -H "Authorization: Bearer comm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "url": "https://your-server.com/webhooks/sms"
    }
  }'

import express from 'express';
import { CommuneClient } from 'commune-ai';
import Anthropic from '@anthropic-ai/sdk';

const app = express();
const commune = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY });
const anthropic = new Anthropic();

app.post('/webhooks/sms', express.json(), async (req, res) => {
  const { data } = req.body;
  if (data.direction !== 'inbound') return res.json({ ok: true });

  const response = await anthropic.messages.create({
    model: 'claude-sonnet-4-6',
    max_tokens: 160,
    system: 'You are a helpful assistant. Reply concisely — this is an SMS.',
    messages: [{ role: 'user', content: data.content }],
  });

  const replyText = response.content[0].type === 'text'
    ? response.content[0].text : '';

  await commune.sms.send({
    phone_number_id: data.metadata.phone_number_id,
    to: data.metadata.from_number,
    body: replyText,
    thread_id: data.thread_id,
  });

  res.json({ ok: true });
});

app.listen(3000);

from flask import Flask, request, jsonify
from commune import CommuneClient
import anthropic

app = Flask(__name__)
commune = CommuneClient()
claude = anthropic.Anthropic()

@app.route("/webhooks/sms", methods=["POST"])
def handle_sms():
    data = request.json["data"]
    if data["direction"] != "inbound":
        return jsonify(ok=True)

    response = claude.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=160,
        system="You are a helpful assistant. Reply concisely — this is an SMS.",
        messages=[{"role": "user", "content": data["content"]}],
    )

    commune.sms.send(
        phone_number_id=data["metadata"]["phone_number_id"],
        to=data["metadata"]["from_number"],
        body=response.content[0].text,
        thread_id=data["thread_id"],
    )

    return jsonify(ok=True)