SDKs oficiales

Para no armar los requests HTTP a mano, Arplyx ofrece SDKs oficiales que envuelven la API con tipos, manejo de errores e idempotencia. Hacen lo mismo que la API REST; elegí el de tu lenguaje.

TypeScript / Node.js — @arplyx/sdk

npm install @arplyx/sdk

import { Arplyx, ArplyxError } from '@arplyx/sdk';

const arplyx = new Arplyx({ apiKey: process.env.ARPLYX_API_KEY! });

const msg = await arplyx.sendMessage({
  externalId: 'pedido-10045',
  to: '+5491155551234',
  text: 'Tu pedido fue confirmado.',
  channel: 'whatsapp_direct',
  whatsappAccountId: 'TU_ACCOUNT_ID',
});
console.log(msg.messageId, msg.status);

Funciona con ESM y CommonJS. Requiere Node.js 18+.

Python — arplyx

pip install arplyx

from arplyx import Arplyx

client = Arplyx(api_key="ak_live_...")

msg = client.send_message(
    external_id="pedido-10045",
    to="+5491155551234",
    text="Tu pedido fue confirmado.",
    channel="whatsapp_direct",
    whatsapp_account_id="TU_ACCOUNT_ID",
)
print(msg.message_id, msg.status)

Requiere Python 3.8+.

Qué exponen

Ambos SDKs cubren las mismas operaciones que la API:

Operación	TypeScript	Python
Enviar mensaje (texto o plantilla)	sendMessage(...)	send_message(...)
Enviar broadcast a una lista	sendBroadcast(...)	send_broadcast(...)
Listar cuentas de WhatsApp	listWhatsappAccounts()	list_whatsapp_accounts()
Consultar estado de un mensaje	getMessage(id)	get_message(id)
Listar mensajes con filtros y cursor	listMessages({...})	list_messages(...)
¿Este número ya me escribió?	getInboundSender(phone) / lookupInboundSenders({...})	get_inbound_sender(phone) / lookup_inbound_senders([...])
Listar mensajes entrantes (plan Pro)	listInboundMessages({...})	list_inbound_messages(...)
Gestionar webhook endpoints	createWebhookEndpoint(...), listWebhookEndpoints(), updateWebhookEndpoint(...), deleteWebhookEndpoint(...), rotateWebhookEndpointSecret(...), testWebhookEndpoint(...)	create_webhook_endpoint(...), list_webhook_endpoints(), …
Verificar la firma de un webhook	verifyWebhookSignature(...) / constructWebhookEvent(...)	verify_webhook_signature(...) / construct_webhook_event(...)

getMessage acepta tu externalId

No hace falta guardar el messageId de Arplyx: getMessage("turno-4812") funciona igual que con el id propio de Arplyx. Lo mismo aplica a GET /messages/{id} en la API REST.

Recibir webhooks

Los SDKs incluyen la verificación de firma lista para usar — constructWebhookEvent verifica y devuelve el evento parseado en un solo paso (ver el contrato completo):

TypeScriptPython

import express from 'express';
import { constructWebhookEvent, WebhookVerificationError } from '@arplyx/sdk';

app.post('/webhooks/arplyx', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = constructWebhookEvent(
      process.env.ARPLYX_WEBHOOK_SECRET!,
      req.body, // Buffer crudo
      req.header('x-arplyx-signature')
    );
  } catch (err) {
    if (err instanceof WebhookVerificationError) return res.status(401).end();
    throw err;
  }
  res.status(200).end();

  if (event.type === 'message.status') {
    console.log(event.data.externalId, '→', event.data.status);
  } else if (event.type === 'message.inbound') {
    console.log('entrante de', event.data.from, ':', event.data.text);
  }
});

from arplyx import construct_webhook_event, WebhookVerificationError

@app.post("/webhooks/arplyx")
async def arplyx_webhook(request: Request):
    try:
        event = construct_webhook_event(
            os.environ["ARPLYX_WEBHOOK_SECRET"],
            await request.body(),  # bytes crudos
            request.headers.get("x-arplyx-signature"),
        )
    except WebhookVerificationError:
        raise HTTPException(status_code=401)

    if event["type"] == "message.inbound":
        print("entrante de", event["data"]["from"], ":", event["data"]["text"])
    return {"ok": True}

Manejo de errores

Las respuestas de error de la API se traducen a una excepción tipada ArplyxError, con status (código HTTP) y code (validation_error, conflict, quota_exceeded, etc. — ver Errores y estados).

TypeScriptPython

try {
  await arplyx.sendMessage({ externalId: 'x', to: '+5491155551234', text: 'hola' });
} catch (err) {
  if (err instanceof ArplyxError) {
    console.error(err.status, err.code, err.details);
  }
}

from arplyx import ArplyxError

try:
    client.send_message(external_id="x", to="+5491155551234", text="hola")
except ArplyxError as e:
    print(e.status, e.code, e.details)

API key

Los SDKs se autentican con tu API key (ak_live_…). Generala desde Portal → API Keys — ver Autenticación. Guardala en una variable de entorno, nunca en el código fuente.

¿Usás un agente de IA?

Si querés que un asistente (Claude, Cursor, etc.) use Arplyx directamente, mirá Conectar por MCP.