Skip to main content
ShumoulShumoul Developer Portalplatform.shumoul.com
Version: Latest

6. API Reference

This is the complete HTTP API surface for WhatsApp Integration inside Shumoul.Saas.Api — 74 endpoints across 9 controllers. Every endpoint below was verified directly against the current controller and service source code; nothing here is inferred or invented.

Base URL: https://{tenant-subdomain}.{shumoul-domain}/api/v{version}/{route} — API version is currently 1 for every controller documented here.

6.0 Conventions Used By Every Endpoint Below​

Authentication & Authorization​

Every endpoint requires a valid JWT bearer token (Authorization: Bearer {token}) except WhatsAppWebhookController's two actions, which are [AllowAnonymous] because Meta calls them without any Shumoul auth token — signature validation is the substitute security control there (see §8 Webhooks). Every other action additionally requires a specific permission via [MustHavePermission("Permissions.X.Y")].

Standard headers​

Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
Accept-Language: ar-SA        (or en-US — drives bilingual field selection and template language)

Response envelope — Result<T>​

Every endpoint except DataTable endpoints and WhatsAppController's manual test endpoints returns:

{ "succeeded": true, "message": null, "data": { "...": "the T payload documented per endpoint" } }

On failure:

{ "succeeded": false, "message": "Human-readable error", "data": null }

DataTable endpoints​

POST GetConversations and POST GetMessages accept a DtParameters body and return the unwrapped DtResult<T> directly:

{ "draw": 1, "start": 0, "length": 25, "search": {"value": "", "regex": false},
  "order": [{"column": 0, "dir": "desc"}], "columns": [{"data": "lastMessageAt", "name": "", "searchable": true, "orderable": true}] }
{ "draw": 1, "recordsTotal": 240, "recordsFiltered": 12, "data": [ "...one row per T" ] }

Two permission families​

  • PermissionConstants.WhatsApp.* — used only by WhatsAppController's manual test endpoints.
  • PermissionConstants.WhatsAppInbox.* — used throughout Inbox, Note, SavedReply, Tag, and Timeline controllers.

Controller Index​

#ControllerRoute prefixEndpoints
1WhatsAppWebhookControllerapi/v1/notifications2
2WhatsAppControllerapi/v1/WhatsApp4
3WhatsAppInboxControllerapi/v1/whatsapp/inbox28
4WhatsAppNoteControllerapi/v1/whatsapp/notes4
5WhatsAppSavedReplyControllerapi/v1/whatsapp/saved-replies9
6WhatsAppTagControllerapi/v1/whatsapp/tags7
7WhatsAppTimelineControllerapi/v1/whatsapp/timeline1
8CommunicationControllerapi/v1/Communication12
9CommunicationDiagnosticsControllerapi/v1/Communication7
Total74

Meta API call surface — only three code paths make outbound HTTP calls to Meta, referenced throughout this reference as "Calls Meta API":

  1. WhatsAppCloudApiClient via IWhatsAppService — the platform's own WhatsApp number.
  2. TenantWhatsAppSender.SendTemplateAsync — a tenant's own WhatsApp Business number.
  3. TenantWhatsAppSender.TestConnectionAsync — a direct business-account lookup, not exposed by IWhatsAppService.

6.1 Certification Addendum (Phase 2.2)​

The fields below apply uniformly across all 74 endpoints unless an endpoint's own page states otherwise — stated once here rather than repeated 74 times, per endpoint pages already covering what's unique (business-specific error cases, side effects, and Angular/Flutter notes).

HTTP Status Codes​

CodeMeaningApplies to
200Success — Result<T>.SuccessAsync, a DtResult<T>, a raw test-endpoint DTO, or a binary/text file streamEvery successful call
400Validation/business-rule failure (ValidationException), or a malformed request bodyAny endpoint with server-side business rules (e.g. window-expiry checks, system-tag protection)
401Missing or invalid JWT bearer tokenEvery endpoint except WhatsAppWebhookController's two actions
403Authenticated but lacking the required [MustHavePermission] permission; or, for the webhook POST action only, an invalid X-Hub-Signature-256Every permissioned endpoint; webhook POST specifically
404Entity not found (EntityNotFoundException) — e.g. an unknown conversationId/noteId/tagId route parameterAny endpoint taking an entity ID route parameter
500Unhandled exception — should be rare; every action follows the platform's standard Result<T>/exception-middleware patternAny endpoint, on an unexpected failure

Validation Rules​

No WhatsApp or Communication-module request DTO has a dedicated FluentValidation validator — confirmed by inspecting Shumoul.Application/Validators/ (78 validator files exist platform-wide; none reference any WhatsApp/Communication DTO). Validation is limited to:

  • ASP.NET Core model binding (a malformed JSON body or an unparsable route Guid returns 400 automatically).
  • Inline service-layer checks, called out per endpoint where they exist (e.g. the 24-hour reply-window check on SendReply, the IsSystem tag-protection check on UpdateTag/DeleteTag, ValidateSettings's configuration checks).

Business Rules — Where to Find Them​

Endpoint-specific business rules are documented as Error cases on each endpoint's own entry in §6.2–6.9. Cross-cutting business rules that apply platform-wide are documented in §11 Templates (template approval, 24-hour window) and §10 Inbox/Conversation (conversation lifecycle rules).

Runtime Flow​

Every endpoint's underlying runtime flow is diagrammed in §23 Sequence Diagrams and §5 Runtime Flows — cross-referenced per endpoint where the flow isn't a single-step CRUD operation.

None, for every one of the 74 endpoints. Every endpoint in this reference performs a synchronous, immediate action (a direct Meta API call, or a direct database read/write) — none of them enqueue a Hangfire job or any Background Jobs Framework pipeline. The only background process anywhere in the WhatsApp/Communication surface is the Notification Framework's generic, channel-agnostic retry pipeline (notification-retry-processor-pipeline, every 2 minutes) — and it is reached only via the separate, not-in-this-reference generic Notification Framework dispatch API, never directly by any of these 74 endpoints. See §23.9 Background Retry.

Only WhatsAppInboxController's conversation-lifecycle actions broadcast a SignalR event — see the "Side effects" note on each such endpoint in §6.3, and the full event catalog in §7 SignalR. No other controller in this reference touches SignalR.

This system's endpoint patternMeta Graph API endpoint called
Any SendText*/SendReply actionPOST /{version}/{phoneNumberId}/messages (text)
Any SendTemplate*/Send/WhatsApp/Send/Document actionPOST /{version}/{phoneNumberId}/messages (template)
GetMediaInfo, Media (download)GET /{version}/{mediaId} then GET {signed CDN url}
Test/WhatsApp, TestConnectionAsync-based diagnosticsGET /{version}/{businessAccountId}?fields=id,name
webhook (GET/POST), all Notes/Tags/SavedReplies/Timeline/Conversations-metadata endpointsNone — these are ERP-internal only and never call Meta