Guia publica para consumir la API

Solicitar acceso

El registro publico crea una solicitud pendiente. No entrega API key ni crea acceso directo.

POST https://api.botyconnect.com/api/v1/botyconnect/access-requests
Accept: application/json

{
  "company_name": "Empresa Demo",
  "tax_id": "900000000-1",
  "country": "Colombia",
  "contact_name": "Laura Gomez",
  "contact_email": "laura@empresa.com",
  "contact_phone": "+57 300 000 0000",
  "estimated_monthly_messages": 50000,
  "estimated_numbers_count": 3,
  "use_case": "Mensajeria masiva desde backend propio.",
  "webhook_url": "https://empresa.com/webhooks/botyconnect"
}

Autenticacion

La empresa consume la API con una API key emitida por Botyconnect. El secret completo se muestra una sola vez.

Authorization: Bearer bc_live_xxxxxxxxxxxxxxxxx
Idempotency-Key: campaign-001

Crear campana

El backend del tercero crea campanas masivas indicando el numero autorizado, template y destinatarios.

POST https://api.botyconnect.com/api/v1/botyconnect/campaigns
Authorization: Bearer bc_live_xxxxxxxxxxxxxxxxx
Idempotency-Key: campaign-001

{
  "account_id": "wacc_xxxxxxxxx",
  "external_reference": "promo-junio-001",
  "template_name": "promo_junio",
  "template_language": "es",
  "body_placeholders": ["Laura"],
  "recipients": [
    {
      "wa_id": "573001112233",
      "external_contact_id": "crm-123",
      "vars": {
        "nombre": "Laura"
      }
    }
  ]
}

Consultar estado

La empresa puede consultar campanas o recibir los estados por webhook.

GET https://api.botyconnect.com/api/v1/botyconnect/campaigns/cmp_xxxxxxxxx
Authorization: Bearer bc_live_xxxxxxxxxxxxxxxxx

GET https://api.botyconnect.com/api/v1/botyconnect/campaigns/cmp_xxxxxxxxx/recipients
Authorization: Bearer bc_live_xxxxxxxxxxxxxxxxx

Creditos

El saldo es global por empresa. El tercero decide internamente como distribuir consumo entre numeros.

GET https://api.botyconnect.com/api/v1/botyconnect/credits/balance
Authorization: Bearer bc_live_xxxxxxxxxxxxxxxxx

Webhooks

La empresa configura su URL. Botyconnect devuelve un signing secret una sola vez y envia eventos firmados.

POST https://api.botyconnect.com/api/v1/botyconnect/webhooks/endpoints
Authorization: Bearer bc_live_xxxxxxxxxxxxxxxxx
Idempotency-Key: webhook-prod-001

{
  "url": "https://empresa.com/webhooks/botyconnect",
  "events": ["message.sent", "message.delivered", "message.failed"]
}

{
  "event": "message.delivered",
  "tenant_id": "uuid-empresa",
  "campaign_id": "uuid-campana",
  "account_id": "wacc_xxxxxxxxx",
  "status": "delivered",
  "timestamp": "2026-06-08T10:00:00Z"
}

Numeros y coexistencia

Una empresa puede tener uno o varios numeros. Cada envio valida que el `account_id` pertenezca al tenant de la API key.

Errores esperados