API REST

La API REST de Artificialic te permite integrar tu plataforma de mensajería con sistemas externos como CRMs, bots, ERPs o cualquier aplicación que necesite enviar mensajes o gestionar contactos programáticamente.

Autenticación

Todas las solicitudes a la API deben incluir un header Authorization con una clave de API válida:

Authorization: Bearer ak_tu_clave_aqui

Obtener una clave de API

1. Ve a Configuración → API en tu dashboard.
2. Haz clic en Crear clave.
3. Asigna un nombre descriptivo (ej. "Integración CRM") y selecciona los permisos necesarios.
4. Copia la clave inmediatamente. Solo se muestra una vez. Si la pierdes, deberás crear una nueva.

Características de seguridad

• Las claves tienen el prefijo ak_ seguido de 64 caracteres hexadecimales.
• Se almacenan como un hash SHA-256 — ni siquiera nosotros podemos ver tu clave.
• Puedes revocar una clave en cualquier momento desde el dashboard. La revocación es inmediata.
• Cada clave registra la fecha de último uso para que puedas auditar el acceso.

Scopes (Permisos)

Cada clave de API tiene uno o más scopes que determinan qué operaciones puede realizar. Asigna solo los permisos que necesites (principio de menor privilegio).

Modo de envío

Cuando un mensaje sale por la API hay que decidir a quién se le atribuye. No es cosmético: define si la conversación queda marcada como atendida por un humano, lo que detiene los bots y las automatizaciones de ese hilo.

Cada clave tiene su modo, configurable en Configuración → API:

• API REST (por defecto): el mensaje se atribuye a la clave. No toma la conversación, no frena las automatizaciones y no se asigna a nadie. En el panel se ve como API REST · nombre de la clave. Es lo que quieres para avisos, confirmaciones y recordatorios que manda tu sistema.
• Como agente humano: sale a nombre de un miembro de tu equipo, toma el control de la conversación y pausa los bots. Úsalo solo cuando tu sistema es la interfaz por la que responde una persona.

Se puede des-escalar por solicitud mandando sendMode: "via_api" en el cuerpo. Lo contrario no: una clave en modo API REST que pida as_user recibe 403 SEND_MODE_NOT_ALLOWED. Escalar es decisión del dueño de la clave, no de quien llama.

Canales de la clave

Por defecto una clave accede a todos los canales de tu organización, incluidos los que conectes después. Puedes restringirla desde el panel: a partir de ahí, usar un canal fuera de la lista devuelve 403 CHANNEL_NOT_ALLOWED, y las lecturas también se acotan.

Al enviar, el canal se resuelve así: si mandas channelId se usa ese; si mandas channelType gana el canal por defecto de la clave, y si hay varios candidatos se elige el más antiguo de forma determinista avisándolo en el header X-Channel-Resolution. Si no mandas ninguno, se usa el canal por defecto. Si prefieres que la ambigüedad sea un error, configura la clave para exigir canal explícito.

Límites e idempotencia

120 solicitudes por minuto por clave (ajustable según tu plan), con sub-límites más estrictos para envíos, borrados y difusiones. El cuerpo máximo es 256 KB. Al superar un límite respondemos 429 con Retry-After y los headers X-RateLimit-*.

Si se te corta la conexión antes de recibir la respuesta, no sabes si el mensaje salió. Manda un header Idempotency-Key único por operación: si reintentas con la misma clave y el mismo cuerpo, te devolvemos la respuesta original con Idempotency-Replayed: true en vez de enviar de nuevo.

curl -X POST "$BASE/api/v1/messages" \
  -H "Authorization: Bearer ak_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"channelId":"...","phoneNumber":"5215512345678","content":"Hola"}'

Webhooks salientes

En vez de preguntarnos cada X segundos si pasó algo, registra una URL y te avisamos nosotros. Se configuran en Configuración → API → Webhooks. Los eventos se suscriben uno por uno: mensaje entrante, cambio de estado de entrega, conversación nueva, cambio de asignación, cambio de modo de atención y difusión finalizada.

Tu URL es pública, así que cualquiera podría mandarle eventos falsos: por eso cada entrega va firmada con el secreto que te damos al crear el webhook (se muestra una sola vez). El header X-Artificialic-Signature tiene el formato t=<unix>,v1=<hmac>, y lo firmado es timestamp.cuerpo — verifica sobre el cuerpo crudo, antes de parsear el JSON.

Cada entrega trae además estos headers:

• X-Artificialic-Event — tipo de evento, para rutear sin parsear el cuerpo.
• X-Artificialic-Delivery — id único de la entrega: úsalo para deduplicar reintentos.
• X-Artificialic-Attempt — número de intento (1 = primero).

Verificar la firma

// Node.js — verifica sobre el cuerpo CRUDO, no el JSON re-serializado
import { createHmac, timingSafeEqual } from "crypto";

function verifySignature(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.split("="))
  );

  // Anti-replay: rechaza firmas de hace más de 5 minutos
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

Responde 2xx para confirmar. Ante 5xx o 429 reintentamos hasta 5 veces con espera creciente; otros 4xx no se reintentan. Si tu endpoint falla 20 eventos seguidos lo desactivamos y te lo mostramos en el panel.

Referencia completa (OpenAPI)

Esta página cubre los conceptos y los endpoints más usados. La referencia exhaustiva está en la especificación OpenAPI 3.1, que puedes importar en Postman, Insomnia o un generador de SDK:

GET /api/v1/openapi.json

Es pública y no requiere autenticación: describe la forma de la API, no datos de nadie. Ahí están también conversaciones, media, plantillas, difusiones, etiquetas, carpetas y webhooks.

Formato de respuestas

Todas las respuestas son JSON. Las respuestas exitosas envuelven los datos en un campo data:

// Respuesta exitosa
{
  "data": {
    "id": "clxyz...",
    "name": "Juan Pérez",
    ...
  }
}

// Lista con paginación
{
  "data": [ ... ],
  "nextCursor": "clxyz..." // null si no hay más resultados
}

Las respuestas de error usan un campo error con un código máquina y un mensaje legible:

// Respuesta de error
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key inválida o revocada"
  }
}

Códigos HTTP

Todas las operaciones

La lista completa de endpoints, con el permiso que exige cada uno. Las secciones siguientes profundizan en los más usados — parámetros, respuestas y ejemplos. Para el detalle exhaustivo de cualquiera de los demás, la especificación OpenAPI los describe todos y se puede importar en Postman o en un generador de SDK.

Endpoints — Canales

GET

/api/v1/channels

Retorna la lista de canales conectados a tu organización. No incluye credenciales de acceso.

Scope requerido: channels:read

Query params

Respuesta

{
  "data": [
    {
      "id": "cm1abc...",
      "name": "WhatsApp Business",
      "type": "WHATSAPP",
      "status": "CONNECTED",
      "profilePictureUrl": "https://...",
      "createdAt": "2026-01-15T10:30:00.000Z"
    }
  ]
}

Ejemplo cURL

curl -H "Authorization: Bearer ak_tu_clave" \
  https://tu-dominio.com/api/v1/channels

Endpoints — Contactos

GET

/api/v1/contacts

Lista los contactos de tu organización con paginación basada en cursor.

Scope requerido: contacts:read

Query params

Respuesta

{
  "data": [
    {
      "id": "cm1def...",
      "name": "Juan Pérez",
      "phoneNumber": "584121234567",
      "externalId": null,
      "email": "[email protected]",
      "avatarUrl": null,
      "createdAt": "2026-02-10T08:00:00.000Z"
    }
  ],
  "nextCursor": "cm1ghi..."  // null si no hay más páginas
}

Paginación

La API usa paginación por cursor. Para obtener la siguiente página, pasa el valor de nextCursor como parámetro cursor:

# Primera página
GET /api/v1/contacts?limit=20

# Siguiente página
GET /api/v1/contacts?limit=20&cursor=cm1ghi...

Ejemplo cURL

curl -H "Authorization: Bearer ak_tu_clave" \
  "https://tu-dominio.com/api/v1/contacts?search=juan&limit=10"

GET

/api/v1/contacts/:id

Obtiene un contacto con todas sus conversaciones. Esto es clave para saber qué channelId usar al enviar un mensaje.

Scope requerido: contacts:read

Path params

Respuesta

{
  "data": {
    "id": "cm1def...",
    "name": "Juan Pérez",
    "phoneNumber": "584121234567",
    "externalId": null,
    "email": "[email protected]",
    "avatarUrl": null,
    "metadata": null,
    "createdAt": "2026-02-10T08:00:00.000Z",
    "conversations": [
      {
        "id": "cm1conv...",
        "status": "OPEN",
        "channelId": "cm1ch...",
        "lastMessageAt": "2026-03-20T14:00:00.000Z",
        "channel": {
          "name": "WhatsApp Business",
          "type": "WHATSAPP"
        }
      }
    ]
  }
}

El array conversations te permite identificar en qué canales tiene conversaciones activas este contacto. Usa el channelId junto con el id del contacto para enviar mensajes.

Ejemplo cURL

curl -H "Authorization: Bearer ak_tu_clave" \
  https://tu-dominio.com/api/v1/contacts/cm1def...

POST

/api/v1/contacts

Crea un nuevo contacto en tu organización.

Scope requerido: contacts:write

Body (JSON)

Respuesta (201 Created)

{
  "data": {
    "id": "cm1new...",
    "name": "María García",
    "phoneNumber": "584121234567",
    "externalId": null,
    "email": null,
    "createdAt": "2026-03-23T10:00:00.000Z"
  }
}

Errores específicos

Ejemplo cURL

curl -X POST \
  -H "Authorization: Bearer ak_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{"name":"María García","phoneNumber":"+584121234567"}' \
  https://tu-dominio.com/api/v1/contacts

PATCH

/api/v1/contacts/:id

Actualiza uno o más campos de un contacto existente. Solo envía los campos que deseas modificar.

Scope requerido: contacts:write

Path params

Body (JSON, todos opcionales)

Respuesta

{
  "data": {
    "id": "cm1def...",
    "name": "Juan A. Pérez",
    "phoneNumber": "584121234567",
    "externalId": null,
    "email": "[email protected]",
    "createdAt": "2026-02-10T08:00:00.000Z"
  }
}

Ejemplo cURL

curl -X PATCH \
  -H "Authorization: Bearer ak_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}' \
  https://tu-dominio.com/api/v1/contacts/cm1def...

DELETE

/api/v1/contacts/:id

Elimina un contacto y todas sus conversaciones asociadas. Esta acción es irreversible.

Scope requerido: contacts:delete — scope aparte de contacts:write, porque el borrado arrastra en cascada las conversaciones del contacto y todo su historial de mensajes. Una clave con solo contacts:write recibe 403.

Path params

Respuesta

{
  "success": true
}

Ejemplo cURL

curl -X DELETE \
  -H "Authorization: Bearer ak_tu_clave" \
  https://tu-dominio.com/api/v1/contacts/cm1def...

Endpoints — Mensajes

POST

/api/v1/messages

Envía un mensaje de texto o una plantilla a un contacto. Acepta múltiples formas de identificar al contacto y al canal. Si el contacto o la conversación no existen, se crean automáticamente — salvo que lo apagues con createContactIfMissing o en la configuración de la clave.

Scope requerido: messages:send

Identificación del contacto (al menos uno requerido)

Identificación del canal (al menos uno requerido)

Si no mandas ninguno de los dos, se usa el canal por defecto de la clave. Si tampoco hay, la respuesta es 400 CHANNEL_REQUIRED. Ver Canales de la clave.

Contenido del mensaje (exactamente uno requerido)

Comportamiento del envío (opcionales)

Flujo interno

1. Se resuelve el canal (por ID, por tipo, o el canal por defecto de la clave) y se valida contra su lista de canales permitidos.
2. Se resuelve o crea el contacto (por ID, teléfono, facebookId o instagramId).
3. Se crea la conversación si no existe (upsert).
4. Se verifica la ventana de conversación (ej. 24h para WhatsApp — las plantillas no requieren ventana abierta).
5. Se crea el mensaje con estado PENDING.
6. Se envía al proveedor del canal.
7. Se actualiza el estado a SENT o DELIVERED.
8. Se emite un evento SSE para actualización en tiempo real.

Respuesta

Con el modo API REST (el de fábrica) el mensaje se persiste como SYSTEM sin usuario asociado: no toma la conversación ni frena las automatizaciones. En el panel se ve como API REST · <nombre de la clave>. Con as_user el senderType es AGENT y sender trae al miembro.

{
  "data": {
    "id": "cm1msg...",
    "conversationId": "cm1conv...",
    "senderType": "SYSTEM",
    "senderId": null,
    "contentType": "TEXT",
    "content": "Hola, tu pedido está listo",
    "status": "SENT",
    "externalId": "wamid.abc...",
    "createdAt": "2026-03-23T10:30:00.000Z",
    "updatedAt": "2026-03-23T10:30:01.000Z",
    "sender": null
  },
  "meta": {
    "channel": { "id": "cm1ch...", "name": "Ventas", "type": "WHATSAPP" }
  }
}

Errores específicos

Ejemplo 1: Texto plano por número de teléfono

curl -X POST \
  -H "Authorization: Bearer ak_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+584121234567",
    "channelType": "WHATSAPP",
    "content": "Hola, tu pedido está listo para retiro."
  }' \
  https://tu-dominio.com/api/v1/messages

Ejemplo 2: Template de WhatsApp

curl -X POST \
  -H "Authorization: Bearer ak_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+584121234567",
    "channelType": "WHATSAPP",
    "template": {
      "id": "cm1tmpl...",
      "type": "message_template",
      "variables": { "1": "Juan", "2": "#12345" }
    }
  }' \
  https://tu-dominio.com/api/v1/messages

Ejemplo 3: Template genérica

curl -X POST \
  -H "Authorization: Bearer ak_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "cm1def...",
    "channelId": "cm1ch...",
    "template": {
      "id": "cm1gen...",
      "type": "generic_template",
      "variables": { "1": "Juan", "2": "#12345" }
    }
  }' \
  https://tu-dominio.com/api/v1/messages

Ejemplo 4: Retrocompatible (contactId + channelId + content)

curl -X POST \
  -H "Authorization: Bearer ak_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "cm1def...",
    "channelId": "cm1ch...",
    "content": "Hola, tu pedido está listo."
  }' \
  https://tu-dominio.com/api/v1/messages

GET

/api/v1/messages/:id/status

Consulta el estado de entrega actual de un mensaje. La respuesta inicial del POST /api/v1/messages indica solo que el mensaje fue encolado en el proveedor (status SENT); los estados posteriores (DELIVERED, READ, FAILED) llegan de manera asíncrona a través de webhooks. Este endpoint te permite consultar el estado más reciente sin tener que escuchar webhooks.

Scope requerido: messages:read

Parámetros de URL

Respuesta

{
  "data": {
    "id": "cm1msg...",
    "externalId": "wamid.HBg...",
    "status": "DELIVERED",
    "errorMessage": null,
    "contentType": "TEMPLATE",
    "conversationId": "cm1conv...",
    "createdAt": "2026-03-23T10:30:00.000Z",
    "updatedAt": "2026-03-23T10:30:05.123Z"
  }
}

Estados posibles

Errores específicos

Ejemplo: consultar por wamid

curl -H "Authorization: Bearer ak_tu_clave" \
  https://tu-dominio.com/api/v1/messages/wamid.HBgMNTg.../status

Ejemplo: consultar por cuid interno

curl -H "Authorization: Bearer ak_tu_clave" \
  https://tu-dominio.com/api/v1/messages/cm1msg.../status

POST

/api/v1/messages/media

Envía una imagen, audio, video o documento a una conversación existente. El archivo viaja en base64 dentro del JSON (no multipart): mantiene el mismo contrato que el resto de la API — JSON + Bearer — y las mismas defensas de tamaño.

Scope requerido: media:send

Body (JSON)

Acepta Idempotency-Key igual que el envío de texto. El mensaje se atribuye según el modo de la clave (API REST o agente humano), con las mismas reglas.

Respuesta

{
  "data": {
    "id": "cm1msg...",
    "conversationId": "cm1conv...",
    "senderType": "SYSTEM",
    "contentType": "IMAGE",
    "mediaUrl": "https://...",
    "status": "SENT",
    "externalId": "wamid.abc...",
    "createdAt": "2026-03-23T10:30:00.000Z"
  }
}

Ejemplo cURL

curl -X POST \
  -H "Authorization: Bearer ak_tu_clave" \
  -H "Content-Type: application/json" \
  -d "{
    \"conversationId\": \"cm1conv...\",
    \"mediaType\": \"image\",
    \"mimeType\": \"image/jpeg\",
    \"filename\": \"recibo.jpg\",
    \"caption\": \"Tu comprobante de pago\",
    \"data\": \"$(base64 -w0 recibo.jpg)\"
  }" \
  https://tu-dominio.com/api/v1/messages/media

Errores comunes

Ejemplos de integración

Flujo completo: enviar un mensaje a un contacto

Este ejemplo muestra cómo obtener los canales, buscar un contacto y enviarle un mensaje usando JavaScript (Node.js / fetch):

const API_URL = "https://tu-dominio.com";
const API_KEY = "ak_tu_clave_aqui";

const headers = {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

// 1. Obtener canales disponibles
const channelsRes = await fetch(`${API_URL}/api/v1/channels`, { headers });
const { data: channels } = await channelsRes.json();
const whatsappChannel = channels.find(ch => ch.type === "WHATSAPP");

console.log("Canal WhatsApp:", whatsappChannel.id);

// 2. Buscar contacto por teléfono
const contactsRes = await fetch(
  `${API_URL}/api/v1/contacts?search=584121234567`,
  { headers }
);
const { data: contacts } = await contactsRes.json();
const contact = contacts[0];

console.log("Contacto:", contact.id, contact.name);

// 3. Enviar mensaje
const msgRes = await fetch(`${API_URL}/api/v1/messages`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    contactId: contact.id,
    channelId: whatsappChannel.id,
    content: "Hola, tu pedido #1234 está listo para retiro.",
  }),
});

const { data: message } = await msgRes.json();
console.log("Mensaje enviado:", message.id, "Estado:", message.status);

Mismo flujo con cURL

# 1. Listar canales
curl -s -H "Authorization: Bearer ak_tu_clave" \
  https://tu-dominio.com/api/v1/channels

# 2. Buscar contacto
curl -s -H "Authorization: Bearer ak_tu_clave" \
  "https://tu-dominio.com/api/v1/contacts?search=584121234567"

# 3. Enviar mensaje
curl -X POST \
  -H "Authorization: Bearer ak_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "CONTACT_ID",
    "channelId": "CHANNEL_ID",
    "content": "Hola, tu pedido #1234 está listo para retiro."
  }' \
  https://tu-dominio.com/api/v1/messages