# Abelo Documentation

> Abelo is an omnichannel messaging Business Solution Provider (BSP) and ecommerce marketing automation platform. Send verification (OTP), transactional alerts, and rich promotional campaigns across Viber and SMS (with WhatsApp upcoming). Synchronize Shopify and WooCommerce store data, build dynamic customer segments, automate lifecycle messaging, and enforce real-time GDPR consent compliance.

## Platform Overview

Abelo operates on a multi-tenant cloud architecture providing enterprise-grade messaging delivery, bidirectional ecommerce synchronization, and comprehensive developer APIs.

- **Primary Messaging Channels**: Viber Business Messages, SMS (worldwide carrier routing), and intelligent Viber-to-SMS failover.
- **REST API Base URL**: `https://api.abelo.ai/v1` (HTTPS, JSON bodies, UTF-8).
- **Authentication**: Bearer Token (`Authorization: Bearer <key_id>:<key_secret>`) and HMAC-SHA256 Request Signing.
- **Webhooks**: Real-time event notifications (`message.sent`, `message.delivered`, `message.seen`, `message.clicked`, `message.failed`, `message.expired`) signed with HMAC-SHA256 (`X-Abelo-Signature`).
- **Privacy & Compliance**: Real-time pre-send consent enforcement in Datastore, independent channel consent tracking, suppression lists, and GDPR Right to Erasure automation.
- **Ecommerce Integrations**: Bidirectional profile and order syncing with Shopify and WooCommerce, accompanied by the client-side Abelo Web SDK.
- **Billing Model**: Transparent prepaid credit ledger with automated pre-flight balance holds and settlement upon carrier Delivery Reports (DLRs).

---

## Getting Started & Quickstart

- [Send Your First Standard Campaign](https://docs.abelo.ai/getting-started/first-standard-campaign/): Step-by-step guide to configuring, segmenting, and launching a broadcast marketing campaign over Viber and SMS.
- [Trigger Your First API Campaign](https://docs.abelo.ai/getting-started/first-api-campaign/): End-to-end tutorial to setting up an API campaign in the CMS and triggering your first programmatic message via `POST /v1/messages/send`.

---

## REST API Reference

The Abelo REST API enables programmatic integration with backend servers, authentication microservices, and ecommerce backends.

- [API Overview & Quickstart](https://docs.abelo.ai/api/): Architectural overview, base URL specification (`https://api.abelo.ai/v1`), cURL, Python, and Node.js quickstarts.
- [Postman Collection & Quickstart Guide](https://docs.abelo.ai/api/postman/): Official Postman collection, public workspace (https://www.postman.com/abelo-ai/abelo-public-api), pre-request HMAC signing automation, and companion GitHub quickstart repository (https://github.com/abelo-ai/api-postman-collection) with cURL, Python, and Node.js scripts.
- [API Authentication](https://docs.abelo.ai/api/authentication/): Generating scoped API keys, Bearer token format (`ak_...:as_...`), and cryptographic HMAC-SHA256 request signing for high-security environments.
- [Triggering API Campaigns (`POST /v1/messages/send`)](https://docs.abelo.ai/api/guides/triggering-api-campaigns/): Complete payload specification for programmatic dispatches (`campaign_id`, `recipient`, `params`, `client_reference`, `webhook_url`), parameter validation rules across Viber and SMS (125 char max, link restrictions for OTP/Transactional), and consent resolution.
- [Syncing Profiles (`/v1/profiles`)](https://docs.abelo.ai/api/guides/syncing-profiles/): CRUD endpoints to create, query (`GET /v1/profiles?phone_number=...`), update, and delete unified customer profiles and channel marketing consent.
- [Errors & Rate Limits](https://docs.abelo.ai/api/rate-limits-errors/): HTTP status codes (200, 201, 204, 400, 401, 403, 404, 409, 422, 429, 500), JSON error schemas, sliding-window token-bucket rate limits, and normalized messaging error codes.
- [Interactive Swagger UI](https://docs.abelo.ai/api/reference/swagger/): Live browser-based OpenAPI explorer to test endpoints and inspect Pydantic schemas.

---

## Webhooks & Real-Time Event Dispatch

Abelo dispatches real-time HTTP `POST` notifications for all message lifecycle and engagement events.

- [Webhooks Overview](https://docs.abelo.ai/api/webhooks/overview/): Architectural overview of outbound webhooks, lifecycle events, and the two delivery routing models:
  1. *Per-Message Webhook URL* (`webhook_url` passed in `messages/send`, signed with API Key's `webhook_signing_secret`).
  2. *Organization Broadcast* (configured globally in CMS, signed with Webhook's `signing_secret`).
- [Webhook Signature Verification](https://docs.abelo.ai/api/webhooks/signatures/): How to verify incoming HMAC-SHA256 signatures (`X-Abelo-Signature: sha256=...`), timestamp validation (`X-Abelo-Timestamp` within 300s replay window), and ready-to-use verification snippets in Python (FastAPI), Node.js (Express), and Go.
- [Webhook Event Topics & Payloads](https://docs.abelo.ai/api/webhooks/topics/): Detailed payload specifications for `message.sent`, `message.delivered`, `message.seen`, `message.clicked` (including user-agent and device telemetry), `message.failed`, and `message.expired`.

---

## Messaging Channels & Delivery

- [Channels & Delivery Architecture](https://docs.abelo.ai/concepts/channels-and-delivery/): Unified messaging delivery across conversational and telecom layers.
- [Viber Business Messaging](https://docs.abelo.ai/user-guides/campaigns/viber-campaigns/): Rich media cards, action buttons, Time-to-Live (TTL) expiration windows, real-time Seen & Click tracking, and automatic SMS failover.
- [SMS Messaging](https://docs.abelo.ai/user-guides/campaigns/sms-campaigns/): Universal worldwide reach, GSM-7 (160 chars) vs Unicode UCS-2 (70 chars) character segmentation, and carrier-level delivery reports.
- [Sender Configurations](https://docs.abelo.ai/user-guides/settings/channels/): Managing verified brand Viber Service IDs and registered alphanumeric SMS sender identities.

---

## Audience, Consent & GDPR Compliance

- [Audience Profiles](https://docs.abelo.ai/user-guides/audience/profiles/): Single customer view, E.164 phone normalization, custom attributes, order statistics, and communication activity history.
- [Dynamic Segments](https://docs.abelo.ai/user-guides/audience/segments/): Real-time audience segmentation using multi-condition filters (order counts, total spend, channel consent, engagement history).
- [Lists](https://docs.abelo.ai/user-guides/audience/lists/): Static contact lists and CSV audience imports.
- [Opt-outs & Suppression Lists](https://docs.abelo.ai/user-guides/audience/suppression-lists/): Global blacklist suppression, channel opt-outs, and automatic dispatch exclusion.
- [GDPR & Privacy Compliance](https://docs.abelo.ai/concepts/compliance-gdpr/): Channel-independent consent storage (`viber_marketing_consent`, `sms_marketing_consent`), real-time pre-send Datastore re-checks, and automated Right to Erasure ("Right to Be Forgotten") execution.

---

## Ecommerce & Integrations

- [Shopify Integration](https://docs.abelo.ai/user-guides/integrations/shopify/): Real-time webhook synchronization for customers, checkouts, and orders; automatic customer redaction handling.
- [WooCommerce Integration](https://docs.abelo.ai/user-guides/integrations/woocommerce/): REST API synchronization of orders, buyer profiles, and checkout consent states.
- [Abelo Web SDK](https://docs.abelo.ai/user-guides/settings/integrations/): Client-side script snippet (`cdn.abelo.ai`), domain allowlist security, lead capture forms, and abandoned cart tracking.

---

## Templates & Personalization

- [Templates Management](https://docs.abelo.ai/user-guides/templates/templates/): Designing reusable message templates across Viber (image, text, button) and SMS.
- [Personalization Variables](https://docs.abelo.ai/user-guides/templates/variables/): Liquid-style `{{variable_code}}` syntax, standard profile attributes (`{{first_name}}`, `{{phone_number}}`), mandatory OTP PIN (`{{pin}}`), and custom transactional variables (`{{order_number}}`, `{{tracking_code}}`).

---

## Billing & Financial Ledgers

- [Billing Overview](https://docs.abelo.ai/user-guides/billing/overview/): Organization billing profile, currency configuration, and legal tax information.
- [Messaging Balance & Reservations](https://docs.abelo.ai/user-guides/billing/messaging-balance/): Prepaid credit ledger mechanics, automated pre-flight balance holds, carrier DLR settlements, and instant release of unused credits for undelivered messages.
- [Payments & Invoices](https://docs.abelo.ai/user-guides/billing/payments/): Submitting bank transfers, proof of payment uploads, and downloadable PDF VAT invoices.

---

## Full Documentation File

For LLMs, AI coding assistants, and context-ingestion pipelines requiring the complete technical manual in a single text file:

- [Full Documentation (llms-full.txt)](https://docs.abelo.ai/llms-full.txt): Complete, concatenated reference documentation covering all architecture, APIs, data schemas, webhooks, and guides.
