Connectus API v3
Iniciar sesión
Credenciales

API v3 de Connectus

Una sola API REST para enviar SMS, correos y mensajes de WhatsApp, acortar links, programar campañas y repartir saldo entre subclientes. Todas las respuestas son JSON. Inicia sesión para que tus credenciales se carguen automáticamente en los ejemplos y en la consola de pruebas.

URL base https://plataforma.connectus.la
Autenticación Header Authorization: Basic
Formato application/json
Codificación UTF-8

Autenticación

Cada request lleva el header Authorization con el ID de tu cuenta y tu API key unidos por dos puntos y codificados en Base64:

http header
Authorization: Basic SURfREVfQ1VFTlRBOkFQSV9LRVk=

El ID de cuenta y la API key se obtienen en la plataforma, en Admin → Empresa y cuenta. La key es única por usuario y por cuenta, y todo lo que hagas con ella queda registrado a nombre de ese usuario.

  • Trata la API key como una contraseña: nunca la publiques en código de frontend, repositorios o apps móviles.
  • Si no envías el header, la respuesta es 401 con {"error":"You must submit an API key"}.
  • Si la key no existe o fue rotada, la respuesta es 401 con {"error":"Invalid or expired API key"}.
  • Regenerar la key desde Admin → Empresa y cuenta invalida la anterior de inmediato.

Errores

Los errores devuelven un objeto con la clave error (string o arreglo de strings). Algunos endpoints de WhatsApp agregan code y details para automatizar el manejo.

CódigoSignificado
200 / 201 / 202Operación aceptada. 202 indica procesamiento en background.
204Operación aceptada, sin contenido en la respuesta.
400Falta un parámetro obligatorio o su formato es inválido.
401Header Authorization ausente o credenciales inválidas.
403El producto no está habilitado para la cuenta, o el usuario no tiene el rol requerido.
404El recurso no existe o pertenece a otra cuenta.
409Conflicto de estado (por ejemplo, un número de WhatsApp ya conectado).
412Precondición de negocio no cumplida: saldo insuficiente, número inválido, contenido rechazado.
422El payload es válido pero los datos no pasan la validación.
502 / 504Error o timeout del proveedor externo (carrier, SMTP, Meta). Reintentable.
  • Ojo con los envíos de email y links cortos: algunos rechazos de negocio llegan con 200 y la clave error en el cuerpo. Valida siempre la presencia del identificador (id, id_sms, short_link) antes de dar el envío por bueno.

General

Verificación de credenciales y datos de la cuenta.

POST /api_v3/test API key

Probar credenciales

Devuelve 200 si el header Authorization es válido. Úsalo como health check de tu integración.

Respuestas
200 OK
{
  "message": "test"
}
401 Sin credenciales
{
  "error": "You must submit an API key"
}
401 Credenciales inválidas
{
  "error": "Invalid or expired API key"
}
GET /api_v3/account API key

Datos de la cuenta

Devuelve el registro completo de la cuenta asociada a la API key, incluidos los feature flags de cada producto.

  • Los flags sms, email_enabled, whatsapp_qr y meta_whatsapp indican qué productos puede usar la cuenta. Si un producto está apagado, sus endpoints responden 403.
Respuestas
200 OK (recortado)
{
  "id": 5,
  "name": "Mi Empresa",
  "id_unique": "5f9618aee2ef4968995b43c8c823befb",
  "rut": 76123456,
  "dv": "K",
  "phone": 56227840830,
  "email": "[email protected]",
  "address_1": "Soria 626",
  "priority": 1,
  "postpaid": 1,
  "id_country": 1,
  "short_link_enabled": true,
  "is_company": true,
  "sms_otp": false,
  "validator": true,
  "email_server_type": "smtp",
  "sms": true,
  "email_enabled": true,
  "whatsapp_qr": false,
  "meta_whatsapp": true
}

SMS

Envío individual, OTP, consulta de saldo y reportes de mensajería SMS.

POST /api_v3/sms/send_individual Ejecuta de verdad API key

Enviar SMS

Envía un SMS a un destinatario. Descuenta saldo del país de destino.

Si no se envía src_number se usa el número marcado como predeterminado de la cuenta. Si no se envía id_delivery, el mensaje se agrupa en el delivery mensual automático de tipo API.

Body
CampoTipoDescripción
dst_number* string Número destino en formato internacional, sin + ni espacios.
sms_content* string Texto del mensaje.
src_number integer Número remitente. Debe pertenecer a la cuenta. (opcional)
id_delivery string id_unique de un delivery existente con id_product = 1 y deliver_at futuro. (opcional)
id_client string id_unique de un subcliente: descuenta de su saldo en vez del saldo libre. (opcional)
  • El contenido pasa por el validador anti-scam de la cuenta; si lo rechaza responde 412 con el motivo.
  • Guarda el id_sms: es el identificador que se usa para consultar el estado.
  • En cuentas postpago no se valida saldo: el envío sale igual y se factura después.
  • Los rechazos de id_delivery (no existe, id_product distinto de 1, fecha pasada) salen con 200 y la clave error, no con 4xx: valida la presencia de id_sms.
Respuestas
200 Enviado
{
  "id_sms": "8f39eacf5c904bf590c1956f52543026"
}
422 Falta un campo
{
  "error": "Destination number not found"
}
412 Sin saldo / número inválido
{
  "error": "Your balance for Chile is too low"
}
412 Remitente ajeno a la cuenta
{
  "error": "The source number is not included in the registered account numbers"
}
403 SMS no habilitado
{
  "error": "SMS no está habilitado para esta cuenta. Usá el modo de prueba."
}
POST /api_v3/sms/send_otp Ejecuta de verdad API key

Enviar SMS OTP

Ruta dedicada a códigos de un solo uso: entrega priorizada y sin validación anti-scam.

Requiere que la cuenta tenga habilitado el permiso de envío OTP.

Body
CampoTipoDescripción
dst_number* string Número destino en formato internacional.
sms_content* string Texto del mensaje, normalmente el código.
src_number string Número remitente. Por defecto el primero de la cuenta. (opcional)
save_content string Con valor hash se guarda el contenido como SHA-256 en vez de texto plano. (opcional)
  • Usa save_content=hash cuando el OTP no deba quedar legible en los reportes.
  • A diferencia de send_individual, no valida ni descuenta saldo: el OTP sale aunque la cuenta esté en cero y su consumo no aparece en GET /api_v3/sms/balance.
Respuestas
200 Enviado
{
  "message_id": "1c4d90ab7e2f4a63b5188c02d7e4fa19"
}
403 Sin permiso OTP
{
  "success": false,
  "message": "cuenta no tiene permiso de envío otp"
}
504 Timeout del carrier
{
  "error": "No se pudo contactar con Jasmin (timeout)"
}
GET /api_v3/sms/balance API key

Saldo SMS

Saldo de SMS disponible agrupado por país (código ISO corto).

Respuestas
200 OK
{
  "balances": {
    "CL": 15320,
    "PE": 400,
    "AR": 0
  }
}
GET /api_v3/sms/:id API key

Estado de un SMS

Estado de entrega de un SMS a partir del id devuelto por el envío.

Parámetros de ruta
CampoTipoDescripción
id* string id_sms devuelto por el envío.
  • Estados frecuentes: NEW, ESME_ROK (aceptado por el carrier), DELIVRD (entregado), UNDELIV (no entregado), EXPIRED, REJECTD, ESME_RINVDSTADR (número inválido).
  • Requiere que la cuenta esté validada; si no, responde 401 aunque las credenciales sean correctas.
  • Hoy el estado se consulta sólo por polling. La URL de estado de SMS de Admin → Empresa y cuenta no dispara notificaciones automáticas por cambio de estado: ver el webhook de salida Estado de SMS para el detalle.
Respuestas
200 OK
{
  "status": "DELIVRD"
}
401 Cuenta no validada
{
  "error": "Account is not active"
}
404 No existe
{
  "error": "Not found"
}
GET /api_v3/sms/date_report API key

Reporte por fechas

Lista los SMS salientes de la cuenta en un rango de fechas (máximo 7 días).

Query string
CampoTipoDescripción
begin_date* date Fecha inicial YYYY-MM-DD.
end_date* date Fecha final YYYY-MM-DD.
  • El identificador de cada SMS viene en id_sms (el mismo valor que devuelve el envío), no en id_unique.
  • El rango incluye los dos extremos: end_date entra completo, hasta las 23:59:59.
Respuestas
200 OK
[
  {
    "id_sms": "8f39eacf5c904bf590c1956f52543026",
    "status": "DELIVRD",
    "sms_content": "Hola",
    "created_at": "2026-08-05T12:00:00.000-04:00",
    "updated_at": "2026-08-05T12:00:04.000-04:00",
    "src_number": 56442349340,
    "dst_number": 56987688060
  }
]
422 Rango inválido
{
  "error": "Date range cannot be greater than 7 days"
}
GET /api_v3/sms/delivery_info API key

SMS de un delivery

Devuelve los SMS salientes asociados a un delivery de la cuenta.

Query string
CampoTipoDescripción
delivery_id* string id_unique de un delivery de tu cuenta.
  • El identificador de cada SMS viene en id_sms (el mismo valor que devuelve el envío), no en id_unique.
  • El delivery tiene que pertenecer a tu cuenta: si es de otra, responde 404.
  • Para consultar por rango de fechas en vez de por campaña, usa GET /api_v3/sms/date_report.
Respuestas
200 OK
[
  {
    "id_sms": "8f39eacf5c904bf590c1956f52543026",
    "status": "DELIVRD",
    "sms_content": "Hola",
    "created_at": "2026-08-05T12:00:00.000-04:00",
    "updated_at": "2026-08-05T12:00:04.000-04:00",
    "src_number": 56442349340,
    "dst_number": 56987688060
  }
]
400 Falta el parámetro
{
  "error": "delivery_id is required"
}
404 No existe
{
  "error": "Delivery with ID b2ef511e53a341bd983c870a71093b6b not found"
}

Email

Envío transaccional de correos, OTP por email y consulta de saldo.

POST /api_v3/email/send_single Ejecuta de verdad API key

Enviar email

Encola un correo individual usando un remitente verificado de la cuenta.

El src_email debe existir en la cuenta y estar verificado. Si el destinatario está desuscrito de ese remitente, el envío se registra como FAILED y no se entrega.

Body
CampoTipoDescripción
src_email* string Remitente verificado de la cuenta.
dst_email* string Destinatario.
subject* string Asunto.
email_content* string Cuerpo del correo. Acepta HTML.
sender string Nombre visible del remitente. (opcional)
id_client string id_unique de un subcliente: descuenta de su saldo. (opcional)
id_delivery string id_unique de un delivery con id_product = 2 y deliver_at futuro. (opcional)
  • Este endpoint responde 200 con la clave error en los rechazos de negocio: valida siempre la presencia de id en la respuesta.
  • Rechazos posibles con 200: Empty source emails, Source email not available (1) y (2), Your balance is insufficient, The free balance is insufficient, Client does not exist, Client has no email balance, The destination email is unsubscribed…, los tres de id_delivery y Error could not be generated.
  • Los remitentes se dan de alta y verifican en Email → Configuración.
Respuestas
200 Encolado
{
  "id": "3e794ad2835e40a7a0fb817884f61fc7"
}
200 Remitente no disponible
{
  "error": "Source email not available (1)"
}
200 Sin saldo
{
  "error": "Your balance is insufficient"
}
403 Email no habilitado
{
  "error": "Email no está habilitado para esta cuenta. Usá el modo de prueba."
}
POST /api_v3/email/send_otp_email Ejecuta de verdad API key

Enviar email OTP

Envío inmediato vía SMTP de Connectus, pensado para códigos de verificación.

A diferencia de send_single, no encola: entrega al SMTP en la misma request y devuelve el estado real del proveedor.

Body
CampoTipoDescripción
src_email* string Remitente verificado de la cuenta.
dst_email* string Destinatario.
subject* string Asunto.
email_content* string Cuerpo del correo. Acepta HTML.
sender string Nombre visible del remitente. (opcional)
  • Requiere que la cuenta esté en estado Activa para usar el SMTP de Connectus.
  • Igual que send_single, los rechazos de negocio salen con 200 y la clave error (Empty source emails, Source email not available (1) y (2), saldo insuficiente, destinatario desuscrito): valida siempre la presencia de id.
Respuestas
200 Entregado al SMTP
{
  "id": "3e794ad2835e40a7a0fb817884f61fc7"
}
200 Remitente no disponible
{
  "error": "Source email not available (1)"
}
200 Sin saldo
{
  "error": "Your balance is insufficient"
}
422 Rechazado por el proveedor
{
  "error": "El correo no fue enviado porque el dominio remitente no tiene DKIM configurado",
  "status": "MISSING_DKIM",
  "id": "3e794ad2835e40a7a0fb817884f61fc7"
}
GET /api_v3/email/balance API key

Saldo de emails

Saldo total de correos disponibles en la cuenta.

Respuestas
200 OK
{
  "balance": 48200
}
GET /api_v3/email/:id API key

Estado de un email

Estado de un correo a partir del id devuelto por el envío.

Parámetros de ruta
CampoTipoDescripción
id* string id devuelto por el envío.
  • Estados frecuentes: NEW, SENT_TO_SMTP, PENDING, DELIVRD (entregado), OPENED, FAILED, MISSING_DKIM.
  • Para correos enviados por el SMTP de Connectus el estado se refresca contra el proveedor en el momento de la consulta.
Respuestas
200 OK
{
  "status": "DELIVRD"
}
404 No existe
{
  "error": "Not found"
}

Deliveries

Un delivery agrupa mensajes bajo una campaña con fecha de salida. Crea uno programado y pasa su id_unique en los envíos para agendarlos.

POST /api_v3/deliveries Ejecuta de verdad API key

Crear delivery

Crea una campaña programada. La fecha debe ser futura.

Body
CampoTipoDescripción
delivery[name]* string Nombre, máximo 100 caracteres.
delivery[deliver_at]* datetime Fecha y hora de salida, formato YYYY-MM-DD HH:MM:SS. Debe ser futura.
delivery[id_product]* integer 1 = SMS, 2 = Email, 3 = WhatsApp.
delivery[delivery_type] string Etiqueta libre de origen. (opcional)
delivery[id_contact_list] integer Lista de contactos asociada. (opcional)
Respuestas
201 Creado
{
  "id_unique": "b2ef511e53a341bd983c870a71093b6b",
  "name": "Campaña agosto",
  "deliver_at": "2026-12-01T10:00:00.000-03:00",
  "created_at": "2026-08-06T09:12:00.000-04:00",
  "id_product": 1,
  "status": "NEW"
}
400 Parámetro faltante o inválido
{
  "error": "Missing or invalid parameter: deliver_at cannot be in the past"
}
GET /api_v3/deliveries/:id API key

Ver delivery

Resumen del delivery con el conteo de mensajes por estado.

Parámetros de ruta
CampoTipoDescripción
id* string id_unique del delivery.
  • product_info es el conteo de mensajes del delivery agrupado por estado; las claves dependen del producto (estados de SMS, de email o de WhatsApp).
  • Cuando el delivery tiene un link corto asociado, has_links es true y vienen link y link_clicks.
Respuestas
200 OK
{
  "id_unique": "b2ef511e53a341bd983c870a71093b6b",
  "delivery_type": "API",
  "created_at": "06/08/2026 12:46",
  "deliver_at": "2026-12-01T10:00:00.000-03:00",
  "user_name": "Ana Pérez",
  "name": "Campaña agosto",
  "has_links": false,
  "link_clicks": null,
  "link": null,
  "link_type": "none",
  "id_product": 1,
  "product_info": {
    "DELIVRD": 120,
    "UNDELIV": 3,
    "ESME_ROK": 8
  }
}
404 No existe o es de otra cuenta
{
  "error": "Delivery not found or does not belong to the current account"
}
PATCH /api_v3/deliveries/:id Ejecuta de verdad API key

Editar delivery

Renombra o reprograma un delivery que todavía no salió.

Parámetros de ruta
CampoTipoDescripción
id* string id_unique del delivery.
Body
CampoTipoDescripción
delivery[name]* string Nuevo nombre.
delivery[deliver_at]* datetime Nueva fecha futura, formato YYYY-MM-DD HH:MM:SS.
  • PUT funciona igual que PATCH.
  • Ambos campos son obligatorios aunque solo quieras cambiar uno: reenvía el valor actual del otro.
  • Solo se puede editar el nombre y la fecha. El producto y la lista de contactos no son modificables.
Respuestas
200 Actualizado
{
  "id_unique": "b2ef511e53a341bd983c870a71093b6b",
  "name": "Campaña agosto v2",
  "deliver_at": "2026-12-02T10:00:00.000-03:00",
  "created_at": "2026-08-06T09:12:00.000-04:00",
  "id_product": 1,
  "status": "NEW"
}
422 Ya salió
{
  "error": "Cannot update delivery with a past deliver_at date"
}

Subclientes

Reparte el saldo de tu cuenta entre subclientes y factura por separado. Las operaciones de escritura requieren un usuario ADMIN.

GET /api_v3/clients API key

Listar subclientes y saldos

Saldos asignados por subcliente más el saldo libre de la cuenta.

Respuestas
200 OK
{
  "data": {
    "free_sms_balance_by_country": [
      {
        "id_country": 1,
        "country_name": "Chile",
        "balance": 14820
      },
      {
        "id_country": 2,
        "country_name": "Mexico",
        "balance": 0
      }
    ],
    "free_email_balance": 47200,
    "free_whatsapp_balance": 0,
    "clients": [
      {
        "id_unique": "9f2ab1c4",
        "name": "Tienda Norte",
        "balance": {
          "sms_balance": [
            {
              "id_country": 1,
              "country_name": "Chile",
              "balance": 500
            }
          ],
          "email_balance": 1000,
          "whatsapp_balance": 0
        }
      }
    ]
  }
}
POST /api_v3/clients Ejecuta de verdad API key

Crear subcliente

Crea un subcliente. Requiere rol ADMIN.

Body
CampoTipoDescripción
client[name]* string Nombre del subcliente.
client[id_unique] string Identificador propio. Si se omite se genera uno de 8 caracteres. (opcional)
Respuestas
201 Creado
{
  "name": "Tienda Norte",
  "id_unique": "9f2ab1c4",
  "created_at": "2026-08-06T09:12:00.000-04:00",
  "balance": {
    "sms_balance": [

    ],
    "email_balance": 0,
    "whatsapp_balance": 0
  }
}
403 Sin permisos
{
  "error": "Admin role required"
}
GET /api_v3/clients/:id API key

Ver subcliente

Datos y saldo de un subcliente.

Parámetros de ruta
CampoTipoDescripción
id* string id_unique del subcliente.
Respuestas
200 OK
{
  "name": "Tienda Norte",
  "id_unique": "9f2ab1c4",
  "balance": {
    "sms_balance": [
      {
        "id_country": 1,
        "country_name": "Chile",
        "balance": 500
      }
    ],
    "email_balance": 1000,
    "whatsapp_balance": 0
  }
}
404 No existe
{
  "error": "Client not found"
}
PATCH /api_v3/clients/:id Ejecuta de verdad API key

Editar subcliente

Renombra un subcliente. Requiere rol ADMIN.

Parámetros de ruta
CampoTipoDescripción
id* string id_unique del subcliente.
Body
CampoTipoDescripción
client[name]* string Nuevo nombre.
  • PUT funciona igual que PATCH.
Respuestas
200 OK
{
  "name": "Tienda Norte S.A.",
  "id_unique": "9f2ab1c4"
}
DELETE /api_v3/clients/:id Ejecuta de verdad API key

Eliminar subcliente

Elimina el subcliente y devuelve su saldo al saldo libre de la cuenta.

Parámetros de ruta
CampoTipoDescripción
id* string id_unique del subcliente.
Respuestas
204 Eliminado
Sin cuerpo.
POST /api_v3/clients/:id/add_balance Ejecuta de verdad API key

Asignar saldo

Traspasa saldo de la cuenta al subcliente. Requiere rol ADMIN.

Parámetros de ruta
CampoTipoDescripción
id* string id_unique del subcliente.
Body
CampoTipoDescripción
amount* integer Cantidad de mensajes a asignar. Mayor que cero.
product* integer 1 = SMS, 2 = Email, 3 = WhatsApp.
id_country integer Obligatorio cuando product = 1. Chile = 1. (opcional)
Respuestas
200 OK
{
  "message": "Balance added successfully"
}
422 Sin saldo en la cuenta
{
  "error": "Insufficient account balance"
}
POST /api_v3/clients/:id/remove_balance Ejecuta de verdad API key

Quitar saldo

Devuelve saldo del subcliente a la cuenta. Requiere rol ADMIN.

Parámetros de ruta
CampoTipoDescripción
id* string id_unique del subcliente.
Body
CampoTipoDescripción
amount* integer Cantidad a devolver. Mayor que cero.
product* integer 1 = SMS, 2 = Email, 3 = WhatsApp.
id_country integer Obligatorio cuando product = 1. (opcional)
Respuestas
200 OK
{
  "message": "Balance removed successfully"
}
422 El subcliente no tiene ese saldo
{
  "error": "Insufficient client balance"
}

WhatsApp QR

Mensajería sobre un número vinculado por código QR. Para el canal oficial usa WhatsApp Meta.

POST /api_v3/whatsapp/send_message Ejecuta de verdad API key

Enviar mensaje

Envía un mensaje de texto desde un número QR vinculado a la cuenta.

Body
CampoTipoDescripción
src_number* string Número QR vinculado a la cuenta.
dst_number* string Número destino en formato internacional.
whatsapp_content* string Texto del mensaje.
id_client string id_unique de un subcliente: descuenta de su saldo. (opcional)
id_delivery string id_unique de un delivery con id_product = 3 y deliver_at futuro. (opcional)
Respuestas
200 Enviado
{
  "message_id": "9d0a7c31b2e4487fa61c58d3e07b9a42"
}
400 Número no disponible
{
  "error": "Source number not available"
}
401 Sin números QR
{
  "error": "Account has no available numbers"
}
GET /api_v3/whatsapp/status API key

Estado de un mensaje

Estado de entrega de un mensaje de WhatsApp QR.

Query string
CampoTipoDescripción
message_id* string message_id devuelto por el envío.
  • Estados posibles: NEW (encolado), SENT (entregado al proveedor), NOT_SENT y ERROR. Este canal no reporta entrega al destinatario: no existe un estado DELIVERED.
  • La ruta acepta GET y POST indistintamente; los parámetros van igual en query string o en el body.
  • Cuando el mensaje no existe responde 200, no 404: valida la clave status.
Respuestas
200 OK
{
  "status": "SENT"
}
200 No encontrado
{
  "error": "Message not found"
}
GET /api_v3/whatsapp/messages API key

Conversación

Últimos 10 mensajes intercambiados entre dos números.

Query string
CampoTipoDescripción
src_number* string Número QR de la cuenta.
dst_number* string Número del contacto.
  • La ruta acepta GET y POST indistintamente.
  • Consulta en vivo al proveedor del número QR, así que es más lenta que el resto de los endpoints.
Respuestas
200 OK
{
  "conversation": [
    {
      "from": "56912345678",
      "to": "56987688060",
      "status": "read",
      "whatsapp_content": "Hola",
      "timestamp": 1754400000
    }
  ]
}
500 Respuesta ilegible del proveedor
{
  "conversation": {
    "error": "true"
  }
}

WhatsApp Meta

Canal oficial de WhatsApp: integración nativa con Meta (Tech Provider directo).

GET /api_v3/meta/whatsapp/go_live_status API key

Estado go-live

Checklist de salida a producción más el health check en vivo del número.

  • Cada item de checks trae code, status y message. Los códigos son connected_number, account_mode, quality_rating, token_health, webhook_health, smoke_test y approved_templates.
Respuestas
200 OK
{
  "go_live_status": "ready",
  "checks": [
    {
      "code": "connected_number",
      "status": "ok",
      "message": "Número conectado"
    },
    {
      "code": "token_health",
      "status": "ok",
      "message": "Token vigente"
    }
  ],
  "health": {
    "status": "healthy",
    "can_send_message": true,
    "checks": [

    ],
    "error_message": null,
    "checked_at": "2026-08-06T09:12:00.000-04:00"
  },
  "phone_connection": {
    "id": 3,
    "phone_number_id": "2020202020",
    "display_phone_number": "+56 9 8765 4321",
    "quality_rating": "GREEN",
    "account_mode": "LIVE",
    "messaging_limit_tier": "TIER_1K"
  }
}
POST /api_v3/meta/whatsapp/onboarding_sessions Ejecuta de verdad API key

Canjear código de Embedded Signup

Intercambia el código del Embedded Signup de Meta y persiste la conexión.

Body
CampoTipoDescripción
code* string Código devuelto por el Embedded Signup.
waba_id* string Id de la WhatsApp Business Account.
phone_number_id* string Id del número a conectar.
business_id string Id del Business Manager. (opcional)
Respuestas
201 Creada
{
  "session_id": 8,
  "status": "connected",
  "meta_waba_id": "1122334455",
  "phone_number_id": "2020202020",
  "display_phone_number": "+56 9 8765 4321",
  "next_step": null
}
400 Falta un parámetro
{
  "error": "Missing required param(s): code",
  "code": "missing_param"
}
409 Número ya conectado
{
  "error": "El número ya está conectado a otra cuenta",
  "code": "connection_conflict"
}
GET /api_v3/meta/whatsapp/onboarding_sessions/:id API key

Estado del onboarding

Consulta el avance de una sesión de onboarding de Meta.

Parámetros de ruta
CampoTipoDescripción
id* integer session_id devuelto al crear la sesión.
Respuestas
200 OK
{
  "session_id": 8,
  "status": "connected",
  "steps": [
    {
      "name": "code_exchange",
      "status": "done"
    }
  ],
  "error_code": null,
  "error_message": null
}
404 No existe
{
  "error": "Meta onboarding session not found",
  "code": "meta_session_not_found"
}

Estadísticas

Agregados de consumo de la plataforma.

GET /api_v3/stats/messages_summary API key

Resumen de mensajes

Totales de SMS y email por año, mes y modalidad de pago.

Métrica agregada de toda la plataforma, no de tu cuenta. Para el consumo propio usa /api_v3/sms/date_report o los reportes del panel.

  • El rango de años está fijo en el código (2024 y 2025): no acepta parámetros de fecha y no devuelve años posteriores hasta que se actualice el controlador.
  • postpaid: 0 = cuentas prepago, 1 = postpago.
Respuestas
200 OK
[
  {
    "year": 2025,
    "month_num": 8,
    "postpaid": 0,
    "sms_sum": 152340,
    "email_sum": 98200
  }
]

Webhooks

Callbacks HTTP que Connectus hace hacia tu servidor. Se configuran en Admin → Empresa y cuenta y no se disparan desde esta consola.

POST https://tu-servidor.com/webhook-sms-status Saliente

Salida · estado de SMS

Connectus postea a la URL configurada en Admin → Empresa y cuenta el estado de un SMS.

  • El payload tiene sólo esas dos claves y el estado va en español: PROGRAMADO, EN_COLA, ENVIADO_A_CARRIER, ESPERANDO_RESPUESTA, ENTREGADO, NO_ENTREGABLE o NUMERO_INVALIDO. No incluye src_number ni dst_number.
  • Hoy no se dispara solo por cada cambio de estado: el camino automático está roto y los envíos que sí salen vienen de procesos batch. Confirmá con soporte antes de basar tu integración en este webhook; mientras tanto, consultá el estado con GET /api_v3/sms/:id.
  • Responde 200 lo antes posible. Para probar durante el desarrollo puedes usar webhook.site.
Payload
200 Payload que recibís
{
  "status": "ENTREGADO",
  "id_sms": "8f39eacf5c904bf590c1956f52543026"
}
POST https://tu-servidor.com/webhook-sms-entrante Saliente

Salida · SMS entrante

Se dispara cuando alguien responde a uno de tus números.

  • Las respuestas con texto de baja (NO SMS, SALIR, NOMASSMS…) generan además una desuscripción automática.
Payload
200 Payload que recibís
{
  "id_sms": "9a8b7c6d5e4f3021",
  "src_number": "56987688060",
  "src_provider": "Entel",
  "dst_number": "56442349340",
  "sms_content": "NO SMS",
  "sms_content_binary": "4e4f20534d53"
}

¿Te falta algo? Escríbenos a [email protected].